Engage SDK Read: инструкции по технической интеграции со сторонними сервисами

Повышайте вовлеченность пользователей, обращаясь к ним там, где они находятся. Интегрируйте Engage SDK, чтобы показывать персональные рекомендации и контент, который пользователи не досмотрели, на разных платформах на устройстве, например в подборках, Entertainment Space и Google Play. Интеграция добавляет менее 50 КБ (в сжатом виде) к среднему размеру APK и занимает у разработчиков около недели. Подробную информацию вы найдете на нашем сайте.

В этом руководстве рассказывается, как партнеры-разработчики могут публиковать контент для чтения (электронные и аудиокниги, комиксы и мангу, блоги, новости и журналы) на платформах Google Play Points.

Поддерживаемые категории и платформы

Доступность платформ Engage SDK зависит от категории контента в приложении. В таблице ниже указано, какие требования нужно выполнить, чтобы ваши товары показывались на разных платформах.

Статус Категория контента или сценарий использования Поддерживаемые платформы
Поддерживается
(Доступно на всех платформах)
  • Электронные книги
  • Комиксы и манга
  • Аудиокниги
  • Сервисы для чтения пользовательского контента в длинной форме
  • Блоги
  • Подборки
  • Entertainment Space
  • Вкладка "Приложения" в Google Play
  • Вкладка "Вы" в Google Play (только персональные рекомендации и продолжение)
  • Страница приложения в Google Play
Частично поддерживается
(Доступно на некоторых платформах)
  • Новости и журналы*
  • Подборки
  • Entertainment Space
Чего пользователь не может
  • Программа для чтения электронных книг или PDF-файлов
  • Рецензии на книги
  • Энциклопедии и словари
  • Переводчик
  • Религиозные тексты

Новостные приложения

Новостные приложения предлагают разнообразный контент, к которому применяются разные правила. Поскольку контент Engage SDK в Google Play соответствует премиум-инструментам для развития, новостные статьи и видеоклипы из новостных приложений не подходят для Google Play, хотя они подходят для подборок и Entertainment Space. В то же время нетрадиционный новостной контент, например подкасты и рецепты, может быть допущен к публикации в Google Play.

Тип объекта Подходит для подборок Доступно в Entertainment Space Доступно в Google Play
Новостная статья Да (вкладка "Книги") Да (вкладка "Книги") Нет
Видеоклип Да (вкладка "Видео") Да (вкладка "Видео") Нет
Подкаст Да (вкладка "Аудио") Да (вкладка "Аудио") Да
Рецепт Да (вкладка "Еда") Нет Да

Сведения об интеграции

В этом разделе подробно описаны шаги, модели данных и терминология, необходимые для интеграции с Engage SDK для чтения контента.

Терминология

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

  • Рекомендации – персонализированные предложения контента от отдельных партнеров-разработчиков.

    Рекомендации имеют следующую структуру:

    • Кластер рекомендаций. Элемент интерфейса, содержащий группу рекомендаций от одного партнера-разработчика.

      Рисунок 1. Интерфейс Entertainment Space с кластером рекомендаций от одного партнера.
    • Объект. Объект, представляющий один элемент в кластере. Объектом может быть электронная или аудиокнига, серия книг и т. д. Список поддерживаемых типов объектов приведен в разделе Предоставление данных об объектах.

      Рисунок 2. Интерфейс Entertainment Space, в котором показан один объект в кластере рекомендаций одного партнера.
  • В кластере Продолжение собраны недочитанные книги от разных партнеров-разработчиков. Каждый партнер-разработчик сможет транслировать не более 10 объектов в кластере продолжения.

    Рисунок 3. Интерфейс Entertainment Space с кластером продолжения, в котором показаны незавершенные рекомендации от нескольких партнеров (в настоящее время видна только одна рекомендация).
  • В кластере Рекомендуемые показываются товары от разных партнеров-разработчиков. В верхней части интерфейса будет только один кластер "Рекомендуемые", который будет иметь приоритет над всеми кластерами рекомендаций. Каждый партнер-разработчик сможет транслировать до 10 объектов в кластере "Рекомендуемые".

    Рисунок 4. Интерфейс Entertainment Space с кластером "Рекомендуемые", в котором представлены рекомендации от нескольких партнеров (в данный момент видна только одна рекомендация).

Подготовка

Минимальный уровень API: 19.

Добавьте библиотеку com.google.android.engage:engage-core в приложение:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.6.0'
}

Сводка

Дизайн основан на реализации привязанной службы.

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

Тип кластера Ограничения кластера Максимальное количество объектов в кластере
Кластеры рекомендаций Не более 7 Не более 50
Кластер продолжения Не более 1 Не более 20
Рекомендуемый кластер Не более 1 Не более 20

Шаг 1. Укажите данные о компании

В SDK определены разные объекты, представляющие каждый тип товара. Для категории "Чтение" поддерживаются следующие объекты:

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

В таблицах ниже перечислены доступные атрибуты и требования для каждого типа.

EbookEntity

Объект EbookEntity представляет электронную книгу (например, электронную версию книги Becoming Мишель Обамы).

Атрибут Требования Примечания
Название Обязательно
Постеры Обязательно Добавьте хотя бы одно изображение. Ознакомьтесь со спецификациями изображений.
Автор Обязательно Необходимо указать хотя бы одного автора.
URI ссылки для действия Обязательно

Ссылка на контент в приложении поставщика для электронной книги.

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

Дата публикации Необязательно В миллисекундах с начала эпохи, если указано.
Описание Необязательно Если вы указываете это значение, оно должно содержать не более 200 символов.
Цена Необязательно Произвольный текст
Количество страниц Необязательно Если указано, должно быть положительным целым числом.
жанр; Необязательно Список жанров, к которым относится книга.
Название серии Необязательно Название серии, к которой относится электронная книга (например, Гарри Поттер).
Индекс серии Необязательно Индекс электронной книги в серии, где 1 – первая книга в серии. Например, если Гарри Поттер и узник Азкабана – третья книга в серии, то значение должно быть равно 3.
Продолжить выбор типа фотокниги Необязательно

TYPE_CONTINUE – продолжить чтение незаконченной книги.

TYPE_NEXT – продолжение серии.

TYPE_NEW – недавно выпущенный.

Время последнего взаимодействия Условно обязательно

Обязательно, если объект находится в кластере продолжения.

В кластер "Продолжить чтение" могут входить *недавно* приобретенные электронные книги.

В миллисекундах с начала эпохи.

Процент выполнения Условно обязательно

Обязательно, если объект находится в кластере продолжения.

Значение должно быть больше 0 и меньше 100.

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

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

Если правило не настроено, контент может показываться на платформе.

В миллисекундах с начала эпохи.

Временная метка окончания Необязательно

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

Если правило не настроено, контент может показываться на платформе.

В миллисекундах с начала эпохи.

AudiobookEntity

Объект AudiobookEntity представляет аудиокнигу (например, аудиокнигу Becoming Мишель Обамы).

Атрибут Требования Примечания
Название Обязательно
Постеры Обязательно Добавьте хотя бы одно изображение. Ознакомьтесь со спецификациями изображений.
Автор Обязательно Необходимо указать хотя бы одного автора.
URI ссылки для действия Обязательно

Ссылка на контент в приложении поставщика аудиокниги.

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

Narrator Необязательно Укажите хотя бы одного диктора.
Дата публикации Необязательно В миллисекундах с начала эпохи, если указано.
Описание Необязательно Если вы указываете это значение, оно должно содержать не более 200 символов.
Цена Необязательно Произвольный текст
Продолжительность Необязательно Если значение указано, оно должно быть положительным.
жанр; Необязательно Список жанров, к которым относится книга.
Название серии Необязательно Название серии, к которой относится аудиокнига (например, Гарри Поттер).
Индекс серии Необязательно Индекс аудиокниги в серии, где 1 – первая аудиокнига в серии. Например, если Гарри Поттер и узник Азкабана – третья книга в серии, то значение должно быть равно 3.
Продолжить выбор типа фотокниги Необязательно

TYPE_CONTINUE – продолжить чтение незаконченной книги.

TYPE_NEXT – продолжение серии.

TYPE_NEW – недавно выпущенный.

Время последнего взаимодействия Условно обязательно

Обязательно, если объект находится в кластере продолжения.

В миллисекундах с начала эпохи.

Процент выполнения Условно обязательно

Обязательно, если объект находится в кластере продолжения.

*Недавно* приобретенные аудиокниги могут быть частью кластера "Продолжить чтение".

Значение должно быть больше 0 и меньше 100.

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

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

Если правило не настроено, контент может показываться на платформе.

В миллисекундах с начала эпохи.

Временная метка окончания Необязательно

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

Если правило не настроено, контент может показываться на платформе.

В миллисекундах с начала эпохи.

BookSeriesEntity

Объект BookSeriesEntity представляет серию книг, например Гарри Поттер (7 книг).

Атрибут Требования Примечания
Название Обязательно
Постеры Обязательно Добавьте хотя бы одно изображение. Ознакомьтесь со спецификациями изображений.
Автор Обязательно Необходимо указать хотя бы одного автора.
URI ссылки для действия Обязательно

Ссылка на контент в приложении поставщика для аудио- или электронной книги.

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

Количество книг Обязательно Количество книг в серии.
Описание Необязательно Если вы указываете это значение, оно должно содержать не более 200 символов.
жанр; Необязательно Список жанров, к которым относится книга.
Продолжить выбор типа фотокниги Необязательно

TYPE_CONTINUE – продолжить чтение незаконченной книги.

TYPE_NEXT – продолжение серии.

TYPE_NEW – недавно выпущенный.

Время последнего взаимодействия Условно обязательно

Обязательно, если объект находится в кластере продолжения.

В миллисекундах с начала эпохи.

Процент выполнения Условно обязательно

Обязательно, если объект находится в кластере продолжения.

В кластер "Продолжить чтение" могут входить *недавно* приобретенные серии книг.

Значение должно быть больше 0 и меньше 100.

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

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

Если правило не настроено, контент может показываться на платформе.

В миллисекундах с начала эпохи.

Временная метка окончания Необязательно

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

Если правило не настроено, контент может показываться на платформе.

В миллисекундах с начала эпохи.

Требования к картинкам

В таблице ниже приведены требования к объектам изображений.

Соотношение сторон Поддерживаемые кластеры Минимальный размер (пиксели) Рекомендуемый размер (пиксели)
Квадрат (1:1). Все кластеры 300x300 1200x1200
Горизонтальное (1,91:1) Рекомендуемые и продолжение 600x314 1200x628
Вертикальное (4:5) Рекомендация 480x600 960x1200

Форматы файлов

PNG, JPG, статический GIF, WebP

Максимальный размер файла

5120 КБ

Дополнительные рекомендации

  • Рекомендуемые пределы допустимой области изображения: важный контент должен занимать центральные 80% изображения.

Пример

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

Шаг 2. Предоставьте данные о кластере

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

AppEngagePublishClient отвечает за публикацию кластеров. В клиенте доступны следующие API:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

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

Вы можете проверить доступность сервиса для каждого типа кластера, который вы собираетесь опубликовать. API isServiceAvailable принимает объект запроса ServiceAvailabilityRequest, который содержит типы кластеров, для которых необходимо проверить доступность сервиса. В таблице ниже приведены значения перечисления ClusterType, необходимые для ServiceAvailabilityRequest.

Тип кластера Константа типа кластера Целочисленное значение
Неизвестно TYPE_UNKNOWN 0
Кластер рекомендаций TYPE_RECOMMENDATION 1
Рекомендуемый кластер TYPE_FEATURED 2
Кластер продолжения TYPE_CONTINUATION 3
Кластер управления пользователями TYPE_ENGAGEMENT 8
Кластер подписок TYPE_SUBSCRIPTION 12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here such as retry.
    }
});
Функция условной доступности сервиса

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

Начиная с версии 1.6.0 Engage SDK позволяет проверять доступность определенных типов кластеров. Если ваше приложение использует прерывистую передачу данных:

  • Кластеры продолжения (например, "Продолжить чтение") по умолчанию включены на всех поддерживаемых устройствах.
  • Другие типы кластеров (например, рекомендации) включаются и отключаются периодически.

Если эта конфигурация по умолчанию вам не подходит, напишите на адрес engage-developers@google.com.

Для версий SDK до 1.6.0 (поддержка прекращена)

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

Этот API используется для публикации списка объектов RecommendationCluster.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build());

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

  • Существующие данные RecommendationCluster от партнера-разработчика удаляются.
  • Данные из запроса анализируются и сохраняются в обновленном кластере рекомендаций.

В случае ошибки весь запрос отклоняется и сохраняется существующее состояние.

publishFeaturedCluster

Этот API используется для публикации списка объектов FeaturedCluster.

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

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

  • Существующие данные FeaturedCluster от партнера-разработчика удаляются.
  • Данные из запроса анализируются и сохраняются в обновленной группе.

В случае ошибки весь запрос отклоняется и сохраняется существующее состояние.

publishContinuationCluster

Этот API используется для публикации объекта ContinuationCluster.

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

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

  • Существующие данные ContinuationCluster от партнера-разработчика удаляются.
  • Данные из запроса анализируются и сохраняются в обновленном кластере продолжения.

В случае ошибки весь запрос отклоняется и сохраняется существующее состояние.

publishUserAccountManagementRequest

Этот API используется для публикации карточки входа . Действие "Войти" направляет пользователей на страницу входа в приложение, чтобы оно могло публиковать контент (или предоставлять более персонализированный контент).

В карточке входа содержатся следующие метаданные:

Атрибут Требования Описание
URI действия Обязательно Ссылка на контент для действия (например, переход на страницу входа в приложение)
Изображение Необязательно. Если не указано, необходимо указать название.

Изображение на карточке

Изображения с соотношением сторон 16:9 и разрешением 1264 x 712.

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

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

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

  • Существующие данные UserAccountManagementCluster от партнера-разработчика удаляются.
  • Данные из запроса анализируются и сохраняются в обновленном кластере UserAccountManagementCluster.

В случае ошибки весь запрос отклоняется и сохраняется существующее состояние.

updatePublishStatus

Если по какой-либо внутренней причине ни один из кластеров не опубликован, мы настоятельно рекомендуем обновить статус публикации с помощью API updatePublishStatus. Это важно по следующим причинам :

  • Указывать статус нужно во всех случаях, даже когда контент опубликован (STATUS == PUBLISHED). Это необходимо для заполнения панелей управления, на которых статус используется для передачи данных о работоспособности и других показателей интеграции.
  • Если контент не опубликован, но статус интеграции не нарушен (STATUS == NOT_PUBLISHED), Google может не запускать оповещения на панелях мониторинга работоспособности приложения. Она подтверждает, что контент не опубликован по ожидаемой причине, известной поставщику.
  • Это помогает разработчикам понять, когда данные публикуются, а когда нет.
  • Google может использовать коды статуса, чтобы подсказать пользователю, как получить доступ к контенту приложения.

Список допустимых кодов статуса публикации :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Если контент не публикуется из-за того, что пользователь не вошел в аккаунт, Google рекомендует опубликовать карточку входа. Если по какой-либо причине поставщики не могут опубликовать карточку входа, мы рекомендуем вызвать API updatePublishStatus с кодом статуса NOT_PUBLISHED_REQUIRES_SIGN_IN.

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationsClusters

Этот API используется для удаления контента из кластеров рекомендаций.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

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

deleteFeaturedCluster

Этот API используется для удаления контента из рекомендуемой группы.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

deleteContinuationCluster

Этот API используется для удаления контента из кластера продолжения.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

deleteUserManagementCluster

Этот API используется для удаления контента кластера UserAccountManagement.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Когда сервис получает запрос, он удаляет существующие данные из кластера UserAccountManagement. В случае ошибки весь запрос отклоняется и сохраняется существующее состояние.

deleteClusters

Этот API используется для удаления контента кластера определенного типа.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

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

Обработка ошибок

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

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

Ошибка возвращается как AppEngageException с указанием причины в виде кода ошибки.

Код ошибки Название ошибки Примечание
1 SERVICE_NOT_FOUND Сервис недоступен на этом устройстве.
2 SERVICE_NOT_AVAILABLE Сервис доступен на устройстве, но не в момент вызова (например, он отключен).
3 SERVICE_CALL_EXECUTION_FAILURE Не удалось выполнить задачу из-за проблем с потоками. В этом случае можно повторить попытку.
4 SERVICE_CALL_PERMISSION_DENIED Вызывающий абонент не может выполнить вызов сервиса.
5 SERVICE_CALL_INVALID_ARGUMENT Запрос содержит недопустимые данные (например, количество кластеров превышает допустимое).
6 SERVICE_CALL_INTERNAL Ошибка на стороне сервиса.
7 SERVICE_CALL_RESOURCE_EXHAUSTED Вызов сервиса выполняется слишком часто.

Шаг 3. Обработка намерений широковещательной рассылки

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

Цель широковещательных намерений – повторная активация приложения и принудительная синхронизация данных. Широковещательные намерения не предназначены для частой отправки. Он запускается, только когда сервис Google Play Объекты определяет, что контент может быть устаревшим (например, ему неделя). Это позволяет пользователю видеть актуальный контент, даже если приложение не запускалось в течение длительного периода времени.

BroadcastReceiver необходимо настроить двумя способами:

  • Динамически зарегистрируйте экземпляр класса BroadcastReceiver с помощью Context.registerReceiver(). Это позволяет приложениям, которые все ещё находятся в памяти, обмениваться данными.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

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

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

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

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

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION 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);

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

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

}
  • Статически объявите реализацию с помощью тега <receiver> в файле AndroidManifest.xml. Это позволяет приложению получать намерения широковещательной рассылки, когда оно не запущено, а также публиковать контент.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Сервис будет отправлять следующие намерения:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION При получении этого намерения рекомендуется начать вызов publishRecommendationClusters.
  • com.google.android.engage.action.PUBLISH_FEATURED При получении этого намерения рекомендуется начать вызов publishFeaturedCluster.
  • com.google.android.engage.action.PUBLISH_CONTINUATIONIt is recommended to start apublishContinuationCluster` call when receiving this intent.

Процесс интеграции

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

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

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

Контакт

Если у вас возникнут вопросы в процессе интеграции, свяжитесь с engage-developers@google.com. Наши специалисты ответят вам в ближайшее время.

Дальнейшие действия

После завершения интеграции выполните следующие действия:

  • Отправьте письмо на адрес engage-developers@google.com и прикрепите к нему интегрированный APK-файл, готовый к тестированию в Google.
  • Google проверит, правильно ли работает интеграция. Если потребуются изменения, Google свяжется с вами и сообщит необходимые сведения.
  • Если тестирование прошло успешно и изменения не требуются, Google сообщит вам, что вы можете опубликовать обновленный и интегрированный APK-файл в Google Play.
  • После того как Google подтвердит, что обновленный APK-файл опубликован в Google Play, ваши кластеры Рекомендации, Рекомендуемые и Продолжение будут опубликованы и станут видны пользователям.