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

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

Кто занимается публикацией контента?

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

Нужно ли разработчику публиковать все типы кластеров?

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

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

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

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

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

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

Зачем разработчикам Android-приложений нужно регистрироваться для рассылки широковещательных интентов?

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

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

Приложение для проверки не поддерживает тестирование широковещательных намерений с разрешениями. Вам необходимо удалить разрешения во время тестирования и добавить их обратно перед переключением SDK на производственную версию на шаге 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

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

Что такое Engage?

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

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

Video Discovery API — это то же самое, что и Engage?

Да, это одно и то же. SDK Engage — это библиотека, которая включает поддержку строки «продолжить просмотр». Engage поддерживает больше типов контента, чем просто видео, поэтому интеграция больше не называется «Поиск видео».

В чём преимущества использования Engage?

Ответ: Engage позволяет зрителям с легкостью продолжить просмотр вашего контента с того места, где они остановились, независимо от используемого устройства. Вот как это работает:

• Бесперебойная работа на всех платформах Google: начните просмотр на Google TV и продолжите его на своем телефоне Android, iPhone или планшете Android. Это работает даже на устройствах, на которых вы еще не установили приложение!
• Повышение вовлеченности и удержания пользователей: функция Engage помогает вернуть пользователей в ваше приложение, даже на новых устройствах. Предоставляя пользователям возможность возобновить просмотр любимых передач, вы увеличиваете вероятность того, что они продолжат смотреть.
• Более широкий охват: помимо Google TV, Engage работает и с другими медиаприложениями Android, такими как Play Collections и другими медиаприложениями Google.
• Обратная совместимость: Если вы уже используете старую функцию « Смотреть дальше », это не проблема! Engage обратно совместим, поэтому ваша существующая интеграция по-прежнему будет работать.

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

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

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

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

Да, SDK Engage поддерживает отображение контента в строке «Продолжить просмотр». Он необходим для интеграции с Engage.

Доступна ли платформа Engage для всех?

Внедрение Engage осуществляется поэтапно.

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

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

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

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

С учетом новой документации по API, будут ли данные о продолжении просмотра, получаемые сервером Google с клиентского устройства, отображаться на всех устройствах?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Какие распространенные ошибки следует избегать при интеграции?

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

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

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

Для телесерий:

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

Для фильмов:

• Точное местоположение при воспроизведении: Как и в случае с телесериалами, убедитесь в точности последнего местоположения при воспроизведении.

Для прямых трансляций видео:

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

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

• Информация об авторе: Укажите автора видеоролика.

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

Вопросы по учетной записи и профилю

Моё приложение использует анонимный вход пользователей. Требуется ли AccountProfile для Engage?

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

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

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

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

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

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

Требуется ли profileId для Engage?

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

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

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

Требуется ли привязка учетных записей для внедрения Engage?

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

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

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

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

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

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

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

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

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

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

Вопросы по REST API

Есть ли документация по REST API?

Ориентировочная дата запуска REST API — март 2025 года, это указано в документации для разработчиков Engage.

Вопросы по теме "Наследие"

Заменяет ли Engage API для Watch Next?

Engage будет обратно совместим со всеми устройствами Android TV, поддерживающими API Watch Next. Для интеграции на Google TV и других платформах, поддерживающих Engage, разработчикам следует использовать SDK Engage.

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

В чём разница между LastPlayBackPositionTimeMillis и duration?

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

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

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

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

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

17. TV2: GoogleAccount: mom. Проверьте данные CW из первого сценария. Теперь войдите в приложение 3p под другим аккаунтом. Аккаунт/профиль 3p: account_2/profile_2. Смотрите контент и убедитесь, что данные CW отображают контент, просмотренный аккаунтом/профилем 3p account_2/profile_2.

18. Аккаунт Google: mom. Новый корпус устройства / стороннее приложение не установлено. На новом устройстве (перезагрузите устройство) функция Verify CW отображает данные из последнего использованного стороннего приложения, которое использовалось аккаунтом Google. Примечание: строка CW не должна отображать содержимое стороннего приложения, если GAIA еще не связана с профилем стороннего приложения на другом устройстве.

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

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

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

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

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

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

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

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

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

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

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

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

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