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

Часто задаваемые вопросы о публикации

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

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

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

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

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

Это решает партнер-разработчик. 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.

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

Часто задаваемые вопросы о Google TV Freeplay 2.0

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

Что такое Engage?

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

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

Video Discovery API и Engage – это одно и то же?

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

Преимущества Engage

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

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

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

На каких платформах поддерживается Engage?

1. Google TV
2. Android TV (только на устройстве, но поддерживает Engage SDK);
3. Мобильное приложение Google TV для Android
4. Мобильное приложение Google TV для iOS
5. Подборки Google Play
6. Google Entertainment Space
7. iOS-устройства (с интеграцией REST API).

Предназначен ли Engage SDK для продолжения просмотра?

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

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

Engage запускается поэтапно.

• Ранний доступ. Сначала мы предоставим доступ к функции избранным партнерам в рамках программы раннего доступа.
• Расширение доступа. Мы работаем над тем, чтобы скоро сделать Engage доступным для всех разработчиков.

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

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

Требования к изображениям обновлены в разделе Создание объектов.

Будут ли данные для раздела "Продолжить просмотр" извлекаться сервером Google из клиента и отражаться на всех устройствах?

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

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

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

• Повышение удержания пользователей. Даже если приложение не установлено на устройстве или пользователь не вошел в аккаунт, контент в строке "Продолжить просмотр" побуждает пользователей снова взаимодействовать с вашим приложением, повышая удержание.

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

Сколько объектов можно опубликовать в кластере продолжения?

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

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

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

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

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

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

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

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

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

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

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

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

Какие ошибки часто допускаются при интеграции?

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

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

• Отсутствуют ссылки. Убедитесь, что вы указали действительные 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, на которых выполнен вход в этот аккаунт, в строке "Продолжить просмотр" будут показываться актуальные данные из связанных объектов accountId и profileId.

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

Связывать аккаунты не нужно. Его приоритет снижается, и все связанные с ним сценарии использования будут охвачены новым Device Entitlements API.

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

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

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

Можно ли отключить синхронизацию между устройствами?

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

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

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

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

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

Вопросы о REST API

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

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

Legacy Watch Next Questions

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

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

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

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

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

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

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

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

1. Посмотрите видео, которое длится дольше 20 минут, в течение примерно 5 минут. Выйдите из приложения. Карточка видео должна появиться в строке "Продолжить просмотр". Примечание. В CW показывается только 5 карточек для каждого стороннего приложения.
2. При выборе новой карточки в строке "Продолжить просмотр" воспроизведение видео должно возобновляться с нужного момента. Примечание. Воспроизведение любого нового или старого контента должно возобновляться с того места, на котором оно было остановлено.
3. При смене аккаунта на устройстве Google TV карточки в строке "Продолжить просмотр" должны меняться. Должны показываться только видео из текущего аккаунта. Отсортировано по дате. Профиль стороннего приложения CW будет смешанным. Примечание. В разделе "Продолжить просмотр" для аккаунта GoogleAccount2 будет показан сторонний контент, который пользователь смотрел в этом аккаунте.
4. Выйдите из приложения, нажав кнопку "Назад". > Убедитесь, что карточка отображается в строке "Продолжить просмотр".
5. Скройте видео в строке "Продолжить просмотр". Оно не должно показываться снова. Проверьте, остается ли скрытый контент скрытым по истечении 24 часов и даже после открытия приложения через 24 часа. Убедитесь, что при скрытии одного объекта не скрываются другие.
6. Доступность контента в строке "Продолжить просмотр" с полными метаданными: изображение карточки, название приложения, название, номер сезона и серии для телеконтента.
7. На индикаторе выполнения появится надпись "Проверить".
8. Пользователь посмотрел контент до финальных титров – контент не отображается в строке "Продолжить просмотр".
9. Убедитесь, что в строке "Продолжить просмотр" нет непросмотренных объектов.
10. Убедитесь, что элементы в разделе "Продолжить просмотр" расположены в хронологическом порядке в зависимости от того, когда пользователь смотрел контент, а не когда он в последний раз открывал приложение или когда был последний день.
11. Убедитесь, что информация о серии и сезоне на карточке "Продолжить просмотр" соответствует тому, что вы смотрели.
12. Убедитесь, что завершенные элементы (элементы, в которых начались титры или которые уже закончились) не отображаются в строке "Продолжить просмотр".
13. Выключите устройство на середине серии, фильма или шоу. "Выключите устройство на середине серии, фильма или шоу. Убедитесь, что при включении устройства и на другом телевизоре на карточке показана правильная информация , а сама карточка и индикатор выполнения находятся в нужном месте.
14. Выключите устройство после полного просмотра серии 1, проверьте
15. Серия 1 исчезает и не появляется в строке "Продолжить просмотр" (на втором устройстве и при включении тестового устройства).
    1. В строке "Продолжить просмотр" на втором устройстве и на тестовом устройстве после его включения должна появиться серия 2 (если она доступна).
16. Первый сценарий. Телевизор 1: аккаунт Google: мама, аккаунт/профиль стороннего сервиса: аккаунт 1/профиль 1. Посмотрите контент и убедитесь, что в данных CW отображается контент, просмотренный в профиле profile_1 стороннего аккаунта account_1.

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

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

    1. Аккаунт Google: mom. Новое устройство или стороннее приложение установлено, но вход не выполнен. На новом устройстве (после сброса настроек) убедитесь, что в виджете "Подключенные устройства" показываются данные из стороннего приложения, которое использовалось в аккаунте Google последним.
19. 1. Примечание. В строке "Продолжить просмотр" не должен показываться сторонний контент, если аккаунт Google ещё не связан со сторонним профилем.

В приложении Google TV для iOS не показывается контент, который можно продолжить смотреть. Что случилось?

Чтобы контент появлялся в строке "Продолжить просмотр" на устройствах iOS, вам нужно будет отправлять ссылки на контент для iOS.

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

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

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

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

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

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

Как эффективно обновлять данные

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

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

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