Engage SDK Часто задаваемые вопросы

Опубликовать часто задаваемые вопросы

Кто управляет публикацией контента?

Разработчик приложения управляет публикацией контента и отправляет запросы в Engage Service. Таким образом, партнёры-разработчики получают больше контроля над тем, когда и как публиковать контент для пользователей. Это позволяет избежать слишком частой активации партнёрского приложения для публикации контента.

Необходимо ли разработчику публиковать все типы кластеров?

Хотя технически разработчики могут публиковать только один кластер, мы настоятельно рекомендуем включать больше. В противном случае разработчики упустят возможность повысить вовлечённость своим контентом. Мы настоятельно рекомендуем публиковать все типы кластеров для каждой вертикали.

Как часто партнер-разработчик должен публиковать данные с помощью диспетчера работ во время работы приложения?

Это должно быть решено партнёром-разработчиком. Google рекомендует публиковать контент с общими рекомендациями один или два раза в день, а для контента корзины покупок, повторного заказа и другого контента с продолжением использовать методологию, управляемую событиями (например, запускать обработчик как обратный вызов, когда пользователь добавляет товары в корзину или останавливает просмотр фильма). Для социальных приложений критически важно публиковать обновлённые кластеры рекомендаций после каждого использования приложения . Пользователи социальных приложений больше заинтересованы в самых последних рекомендациях и в идеале хотели бы видеть публикацию не более одного раза.

Когда разработчику следует вызывать API удаления?

API удаления следует вызывать только при отсутствии контента для публикации. Не вызывайте API удаления и публикации последовательно для замены контента; API публикации автоматически удаляют ранее опубликованный контент.

Часто задаваемые вопросы о целях трансляции

Почему разработчикам приложений для Android необходимо регистрироваться для целей трансляции?

Чтобы предоставлять пользователю свежий контент, следует использовать широковещательные намерения для запуска синхронизации данных в случаях, когда пользователи нечасто пользуются приложением.

Не удалось проверить намерение трансляции

Приложение для проверки не поддерживает тестирование намерений трансляции с разрешениями. Вам необходимо удалить разрешения на время тестирования и добавить их заново перед переключением SDK на версию prod на шаге 6 .

Фоновое выполнение не допускается

При регистрации намерения трансляции вы можете столкнуться со следующей ошибкой:

Background execution not allowed: receiving Intent
{ act=com.google.android.engage.action.PUBLISH_RECOMMENDATION .. }

Вам необходимо динамически регистрировать вещательные приемники.

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION,
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null));
...

}

Часто задаваемые вопросы о рабочем процессе

При интеграции с SDK вы можете столкнуться со следующими ошибками:

Ошибки валидации на уровне приложения, кластера, сущности

В сводках на уровне приложения, кластера и сущности отображается количество ошибок валидации. Эти ошибки связаны с отсутствием обязательных полей или недопустимыми значениями. Сообщения об ошибках отображаются красным цветом под каждым соответствующим полем. Исправьте все ошибки валидации и проверьте корректность, прежде чем публиковать APK-файл.

Тестирование глубоких ссылок

Глубокие ссылки связаны с именем пакета. Хороший способ проверить глубокие ссылки — использовать инструмент adb.

adb shell am start -W -a android.intent.action.VIEW -d <DEEPLINK URI> <PACKAGE NAME>

Как рассчитать влияние интеграции?

Глубокие ссылки — отличный способ отслеживать атрибуцию. URL-адреса глубоких ссылок, ведущих пользователей в ваше приложение, можно включить с дополнительными параметрами отслеживания. Например, «http://xx/deeplink?source_tag=engage».

Разработчики могут добавлять собственные параметры отслеживания и указывать атрибуцию для расчета воздействия.

Часто задаваемые вопросы о Engage for TV 2.0

Общие вопросы

Что такое «Продолжить просмотр 2.0»?

Continue Watching 2.0 (Video Discovery API) выводит возможность продолжить просмотр с того места, где вы остановились, на новый уровень! Это значительное обновление, позволяющее зрителям легко возобновлять просмотр на более широком спектре устройств. Представьте, что вы начинаете смотреть фильм на Google TV, а затем без труда продолжаете его на телефоне по дороге на работу — в этом и заключается сила Continue Watching 2.0.

Эта новая система призвана повысить вовлеченность и удержание зрителей, обеспечивая бесперебойную работу во всей экосистеме Google.

Каковы преимущества использования Continue Watching 2.0?

Ответ: Функция «Продолжить просмотр 2.0» позволяет зрителям проще, чем когда-либо, продолжать просмотр вашего контента с того места, где они остановились, независимо от того, какое устройство они используют. Вот как это работает:

• Удобный просмотр на Google: начните смотреть на Google TV и продолжайте без проблем на телефоне, iPhone или планшете Android. Приложение работает даже на устройствах, на которых вы ещё не установили приложение!
• Повышение вовлечённости и удержания: функция «Продолжить просмотр 2.0» помогает возвращать пользователей в ваше приложение, даже на новых устройствах. Позволяя пользователям возобновлять просмотр любимых сериалов, вы повышаете вероятность того, что они продолжат смотреть.
• Более широкий охват: помимо Google TV, Continue Watching 2.0 работает и с другими мультимедийными приложениями Android, такими как Play Cubes и другие мультимедийные приложения Google.
• Обратная совместимость: если вы уже используете старую функцию « Смотреть далее », не проблема! Функция «Продолжить просмотр» версии 2.0 обратно совместима, поэтому ваша текущая интеграция будет работать.

Важное примечание: все новые интеграции с функцией «Продолжить просмотр» должны использовать версию «Продолжить просмотр» 2.0. Старая система «Воспроизвести следующий контент на разных устройствах» постепенно отменяется.

Какие поверхности поддерживают Continue Watching 2.0?

1. Google ТВ
2. Android TV (только на устройстве, но поддерживает Engage SDK)
3. Мобильное приложение Google TV для Android
4. Мобильное приложение Google TV для iOS
5. Игровые кубики
6. Пространство развлечений Google
7. Устройства iOS (с интеграцией REST API).

Является ли Engage SDK для продолжения просмотра версией 2.0?

Да, Engage SDK предназначен для Continue Watching 2.0. Он необходим для интеграции с Continue Watching 2.0.

Доступна ли функция «Продолжить просмотр 2.0» всем желающим?

Продолжить просмотр 2.0 внедряется поэтапно.

• Ранний доступ: Первоначально мы предоставляем доступ избранной группе партнеров через Программу раннего доступа (EAP).
• Расширение доступа: мы прилагаем все усилия, чтобы в ближайшее время сделать Continue Watching 2.0 доступным для всех разработчиков.

Для обеспечения плавного и успешного запуска мы предусмотрели меры безопасности, позволяющие управлять внедрением. Это включает в себя как список разрешенных пользователей на стороне Continue Watching 2.0, так и отдельную проверку в Engage SDK. Независимо от того, являетесь ли вы партнером программы раннего доступа (EAP) или планируете присоединиться в ближайшее время, свяжитесь с нами, чтобы мы могли настроить права доступа до начала интеграции Engage SDK.

Есть ли рекомендуемый размер изображения, который следует предоставить?

Требования к изображениям обновлены в разделе «Создание сущностей» .

Будут ли данные Continue Watching извлекаться сервером Google из клиента с учетом этой новой документации API и будут ли они отражены на всех устройствах?

Новый API предлагает значительные преимущества для продолжения просмотра, в том числе:

• Удобный просмотр на всех устройствах Google TV: пользователи могут начать просмотр на одном устройстве Google TV и продолжить его на любом другом устройстве Google TV, войдя в систему с той же учётной записью. Эта функция также работает на более старых версиях Android TV.

• Интеграция с мобильным приложением: функция Continue Watching доступна в мобильном приложении Google TV для Android и iOS, что позволяет пользователям легко переключаться между телевизором и мобильными устройствами.

• Улучшенное удержание пользователей: даже на устройствах без установленного приложения или когда пользователь не вошел в систему, функция «Продолжить просмотр» побуждает пользователей повторно взаимодействовать с вашим приложением, что повышает удержание.

• Расширение на другие платформы: эта интеграция распространяет функцию Continue Watching на другие медиаплатформы Google, такие как Android, Play Cubes, планшеты и другие медиаприложения и поверхности Google на Android, максимизируя вовлеченность пользователей на всех устройствах.

Какое количество сущностей я могу опубликовать в кластере Continuation?

Каждый партнёр-разработчик может иметь не более 5 объектов в кластере «Продолжение». Это ограничение необходимо для справедливого распределения контента в строке «Продолжить просмотр» на Google TV, которая является общим пространством для нескольких поставщиков медиаконтента.

Что произойдет, если я попытаюсь опубликовать более 5 сущностей?

EngageSDK отклонит ваш запрос на публикацию, если он превысит лимит в 5 сущностей. Для успешной публикации вам потребуется сократить количество сущностей в запросе. Включайте только те сущности, на которых пользователи остановились, поэтому в большинстве случаев таких сущностей будет немного. Если таких сущностей больше 5, вы можете выбрать для публикации более свежие.

Почему существует ограничение на количество сущностей?

Строка «Продолжить просмотр» на Google TV отображает контент от разных поставщиков медиаконтента. Ограничение количества объектов на одного поставщика позволяет пользователям видеть разнообразный выбор контента из всех любимых источников, обеспечивая справедливый и сбалансированный пользовательский опыт.

Вопросы по приложению для проверки

Обязательно ли тестировать мое приложение с помощью приложения для проверки перед отправкой?

Да, перед отправкой APK-файла необходимо протестировать приложение с помощью приложения для проверки.

Мы понимаем, что вы можете быть уверены в своей реализации, но интеграция с Continue Watching 2.0 включает в себя множество сложных компонентов. Приложение для проверки действует как подстраховка, выявляя потенциальные проблемы на ранних этапах и экономя ваше драгоценное время и силы в долгосрочной перспективе.

Подумайте об этом как о быстрой проверке, которая поможет гарантировать плавный запуск и отличный пользовательский опыт.

Заранее определив и решив любые проблемы, вы сможете избежать разочарований, связанных с отказами и повторными подачами.

Чтобы отправить APK-файл, вам необходимо прикрепить снимок экрана, показывающий, что ваше приложение прошло процедуру проверки.

На какие типичные ошибки следует обращать внимание при интеграции?

Приложение для проверки предназначено для выявления потенциальных проблем с интеграцией Continue Watching 2.0. Вот несколько распространённых ошибок, с которыми часто сталкиваются разработчики:

Для всех типов контента (фильмы, сериалы, прямые трансляции, видеоклипы):

• Недостающие ссылки: Убедитесь, что вы предоставляете корректные URI (ссылки) для вашего контента, специфичные для конкретной платформы. Эти ссылки сообщают системе, где найти ваш контент на каждой платформе.
• Отсутствуют заголовки: Не забудьте указать заголовки для всего вашего контента. Это поможет пользователям понять, что они смотрели.
• Соотношение сторон изображения: убедитесь, что все изображения, связанные с вашим контентом, имеют соотношение сторон, близкое к 16:9. Это обеспечит корректное отображение изображений на разных экранах.

Для ТВ-эпизодов:

• Полная информация об эпизоде: обязательно укажите название сериала, номер эпизода и сезона. Это поможет упорядочить эпизоды и позволит пользователям легко ориентироваться в сериале.
• Точная позиция воспроизведения: дважды проверьте, что последняя позиция воспроизведения меньше или равна общей длительности эпизода. Это позволит пользователям продолжить воспроизведение с нужного места.

Для фильмов:

• Точная позиция воспроизведения: как и в случае с телевизионными эпизодами, проверьте точность последней позиции воспроизведения.

Для потокового видео в реальном времени:

• Информация о вещателе: укажите название вещателя для прямых трансляций.

Для видеоклипов:

• Информация о создателе: укажите создателя видеоклипа.

Помните: приложение для проверки выявит эти проблемы, что позволит вам исправить их перед отправкой приложения. Это сэкономит ваше время и обеспечит более удобный интерфейс для пользователей.

Вопросы по аккаунту и профилю

Моё приложение использует анонимные логины. Требуется ли AccountProfile для Continue Watching 2.0?

AccountProfile предназначен для приложений, использующих индивидуальные учётные записи пользователей. Однако мы понимаем, что некоторые приложения, такие как ваше, могут использовать анонимные входы. Вот как работает Continue Watching 2.0 в этом случае:

• AccountProfile технически необходим, но... вы все равно можете интегрировать Continue Watching 2.0, даже если в вашем приложении нет системы учетных записей пользователей.
• Ограничено использованием на одном устройстве: кроссплатформенные возможности Continue Watching 2.0 основаны на идентификации пользователей на разных устройствах. Поскольку анонимные входы не позволяют этого, функция будет ограничена текущим устройством пользователя.
• Как настроить: Для этого необходимо отключить синхронизацию между устройствами. Это гарантирует, что записи «Продолжить просмотр» будут отображаться только на том устройстве, где был запущен просмотр.

Подводя итог: хотя вы можете интегрировать Continue Watching 2.0 с анонимными входами в систему, пользователи смогут возобновлять просмотр контента только на том же устройстве.

Могу ли я использовать AccountProfile только с accountId и без profileId, даже если мое приложение поддерживает и accountId, и profileId?

Для корректной работы AccountProfile необходимы как accountId, так и profileId. Вот почему:

• Единообразная идентификация: accountId идентифицирует пользователя, а profileId различает профили внутри учётной записи пользователя (если применимо). Предоставление обоих параметров гарантирует, что функция Continue Watching будет точно отслеживать и отображать контент для каждого отдельного профиля.
• Предотвращение ошибок: Неоднородное использование accountId и profileId в разных вызовах API может привести к неожиданному поведению и ошибкам. Например, если вы добавляете оба параметра при добавлении контента в функцию «Продолжить просмотр», но используете только accountId при удалении контента, система может некорректно определить и удалить нужные элементы.

Требуется ли profileId для продолжения просмотра 2.0?

• Требуется идентификатор аккаунта. Он идентифицирует пользователя на всех устройствах.
• profileId критически важен для комфортного пользовательского опыта. Хотя технически это необязательно, profileId настоятельно рекомендуется использовать, если ваш сервис поддерживает несколько профилей (как это делают многие стриминговые сервисы). Почему это так важно? Потому что без profileId функция «Продолжить просмотр» может показывать контент из других профилей той же учётной записи. Это может привести к путанице и разочарованию пользователей.
• Вкратце: предоставление profileId гарантирует, что функция «Продолжить просмотр» точно отражает историю просмотров каждого пользователя. Если ваше приложение поддерживает профиль в учётной записи, вам следует его предоставить.

Как Google использует profileId со своей стороны?

Если сервис предлагает разные профили для просмотра контента, accountId и profileId будут использоваться для связывания просматриваемого на устройстве контента с учётной записью Google, в которой выполнен вход на этом устройстве. Google будет регистрировать данные ContinueWatching в соответствии с комбинацией accountId-profileId. Любое устройство Google, на котором выполнен вход в ту же учётную запись Google, будет получать последние обновлённые данные из тех же связанных пар accountId-profileId в строке ContinueWatching.

Требуется ли привязка аккаунта для внедрения Continue Watching 2.0?

Привязка учётных записей не требуется. Она становится менее приоритетной, и все связанные с ней сценарии использования будут охватываться новым API Device Entitlements.

Вопросы по синхронизации между устройствами

Что означает «синхронизация между устройствами», когда пользователи дают согласие?

С согласия пользователя на синхронизацию между устройствами просматриваемый контент будет сохраняться на серверах Google TV, что позволит пользователю легко продолжить просмотр с того места, где он остановился, на любом устройстве, на котором он вошёл в систему. Без согласия история просмотров останется локальной для текущего устройства.

Можно ли установить для параметра «синхронизация между устройствами» значение «false»?

Флаг UserConsentToSyncAcrossDevices управляет тем, синхронизируются ли данные ContinuationCluster пользователя на его устройствах (телевизор, телефон, планшет и т. д.). Если этому флагу присвоено значение false, то продолжение просмотра происходит только на том же устройстве.

Чтобы максимально эффективно использовать нашу функцию кросс-устройства, мы настоятельно рекомендуем вашему приложению получить согласие пользователя и установить для параметра SyncAcrossDevices значение true.

Как получить согласие пользователя на передачу истории просмотров на устройствах, отличных от Android?

Какие данные передаются на сторонние серверы с устройств, отличных от Android?

Согласие собирается на уровне пользователя (на уровне профиля или учётной записи). После получения согласия полезные данные о продолжении просмотра, основанные на взаимодействии, могут быть отправлены куда угодно, чтобы Google мог отражать состояние возобновления повсеместного присутствия пользователя во всех объектах, с которыми он взаимодействовал частично или в ближайшее время, на любом устройстве (без необходимости повторно запрашивать согласие на каждом устройстве или платформе). Партнеры будут отправлять пользователям последние данные о состоянии продолжения просмотра (согласно спецификации), связанные с идентификатором профиля (который был сохранен на Android).

Вопросы по REST API

Существует ли документация по REST API?

Планируемая дата выхода REST API — март 2025 г., как указано в документации для разработчиков Continue Watching 2.0.

Legacy Watch Следующие вопросы

Заменяет ли API Video Discovery API API Watch Next?

API Video Discovery будет обратно совместим со всеми устройствами Android TV, поддерживающими API Watch Next. Всем разработчикам следует использовать API Video Discovery (Continue Watching 2.0) для публикации контента в строке «Продолжить просмотр».

Вопросы тестирования и интеграции

В чем разница между LastPlayBackPositionTimeMillis и длительностью?

LastPlayBackPositionTimeMillis должен отражать длительность воспроизведения в миллисекундах, в которой пользователь остановил просмотр (например, 605000 мс для 10 минут и 5 секунд). Оно не должно превышать общую длительность объекта.

Тогда как LastEngagementTime — это временная метка, когда пользователь последний раз взаимодействовал с контентом.

Какие тестовые случаи нам следует выполнить?

Ниже приведены тестовые примеры для Google TV, которые проводит наш отдел контроля качества. Аналогичные тестовые примеры можно провести и на других платформах.

1. Посмотрите видео продолжительностью более 20 минут примерно на 5 минут. Выйдите из приложения. Подсказка к видео должна отображаться в строке «Продолжить просмотр». Примечание: в CW мы отображаем только 5 подсказок на приложение 3P.
2. Выбор новой карточки в строке «Продолжить просмотр» должен продолжить воспроизведение видео с нужного места. Примечание: воспроизведение любого нового или старого контента должно возобновиться с того места, где оно было остановлено в прошлый раз.
3. Смена учётных записей на устройстве GTV должна изменить карточки в строке «Продолжить просмотр». Должны отображаться только видео из текущей учётной записи. Отсортировано по дате последнего просмотра. Профиль приложения 3P (CW) будет перемещён. Примечание: CW для GoogleAccount2 будет отображать контент 3P, просмотром которого занимался пользователь GoogleAccount2.
4. Выйдите из приложения, нажав кнопку «НАЗАД». Убедитесь, что карта отображается в строке «Продолжить просмотр».
5. Скройте видео в строке «Продолжить просмотр», оно больше не должно отображаться. Проверьте, сохраняется ли скрытый контент более 24 часов и даже после открытия приложения по истечении 24 часов. Убедитесь, что скрытие одного элемента не скрывает несколько элементов.
6. Доступность контента в разделе «Продолжить просмотр» с полными метаданными: изображение карточки, название приложения, заголовок, номер эпизода сезона для ТВ-контента.
7. Проверка хода выполнения отображается на панели выполнения.
8. Пользователь просмотрел контент до окончания титров — контент не отображается в разделе «Продолжить просмотр».
9. Убедитесь, что в строке продолжения просмотра не отображаются непросмотренные элементы.
10. Убедитесь, что элементы CW расположены в хронологическом порядке на основе времени совершения действий при просмотре, а не на основе времени последнего открытия приложения или последнего дня.
11. Подтвердите, что информация об эпизоде ​​и сезоне на карточке CW соответствует просмотренному контенту.
12. Подтвержденные выполненные (предметы на кредитах или выше) предметы не отображаются в продолжении просмотра
13. Выключите устройство во время просмотра эпизода/фильма/шоу. «Выключите устройство во время просмотра эпизода/фильма/шоу. Убедитесь, что при включении устройства и на другом телевизоре CW отображает нужную подсказку, в нужном месте и с индикатором хода».
14. Выключите устройство после полного просмотра 1-го эпизода, проверьте
15. Эпизод 1 пропадает и больше не появляется в строке «Продолжить просмотр» [на втором устройстве и при включении тестового устройства]
    1. Эпизод 2 (если доступен) должен появиться в строке «Продолжить просмотр» [на втором устройстве и при включении тестового устройства]
16. Первый сценарий: TV1: аккаунт Google: мама, аккаунт 3P / профиль: аккаунт 1 / профиль_1. Смотрите контент и убедитесь, что данные CW отображают контент, просмотренный аккаунтом 3P_1/профилем_1.

17. TV2: GoogleAccount: мама. Проверьте данные CW из первого сценария. Теперь войдите в приложение 3P под другой учётной записью. Учётная запись 3P / профиль: учётная_запись_2 / профиль_2. Смотрите контент и убедитесь, что данные CW отображают контент, просмотренный пользователем 3P учётная_запись_2/профиль_2.

18. GoogleAccount: мама. Новый чехол для устройства / приложение 3P не установлено. На новом устройстве (FDR-устройство) функция проверки CW отображает данные из последнего использованного приложения 3P, которое использовалось в GoogleAccount. Примечание: в строке CW не должно отображаться содержимое 3P, если GAIA ещё не связана с профилем 3P на другом устройстве.

    1. GoogleAccount: мама. Новый чехол для устройства / приложение 3P установлено, но вход в систему не выполнен. На новом устройстве (устройство FDR) Verify CW отображает данные из последнего использованного приложения 3P, которое использовалось в GoogleAccount.
19. 1. Примечание: строка «Продолжить просмотр» не должна отображать содержимое 3P, если аккаунт Google еще не связан с профилем 3P.

В приложении Google TV для iOS не отображается функция «Продолжить просмотр». Что случилось?

Вам необходимо будет отправить глубокие ссылки iOS, чтобы функция «Продолжить просмотр» отображалась на устройствах iOS.

Как часто следует обновлять информацию о продолжении просмотра? Стоит ли обновлять информацию о продолжении просмотра часто, например, каждые 15 секунд?

Нет, частые обновления не рекомендуются. Вот почему:

• Влияние на производительность: постоянная отправка обновлений создает ненужную нагрузку на наши серверы, что может замедлить работу системы для всех.
• Ненужные данные: пока пользователь активно смотрит, позиция воспроизведения постоянно меняется. Отправка обновлений каждые несколько секунд создаёт большой объём избыточных данных, которые бесполезны для возобновления воспроизведения.

Когда обновлять информацию о продолжении просмотра:

Сосредоточьтесь на фиксации значимых изменений в ходе просмотра. Вот основные сценарии:

• Воспроизведение приостановлено или остановлено: когда пользователь приостанавливает или прекращает просмотр, отправляйте обновление для сохранения его текущего положения.
• Приложение закрыто или переведено в фоновый режим: если пользователь выходит из приложения или переключается на другое приложение во время просмотра видео, отправьте обновление для сохранения его прогресса.
• Когда пользователь удаляет элемент из строки продолжения просмотра в приложении

Как эффективно обновить:

Вместо запланированных обновлений используйте события в жизненном цикле видеоплеера или приложения для запуска обновлений. Например:

• onPause, onStop: приостановка или остановка воспроизведения видео.
• onAppClose, onAppBackgrounded: когда приложение закрывается или переходит в фоновый режим.

Соблюдая эти рекомендации, вы обеспечите эффективное использование ресурсов, одновременно обеспечивая бесперебойный просмотр для своих пользователей.