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

Повысьте вовлеченность пользователей в приложение, взаимодействуя с ними там, где они находятся. Интегрируйте Engage SDK, чтобы предоставлять персонализированные рекомендации и дополнительный контент непосредственно пользователям на различных платформах устройства, таких как «Коллекции» , «Развлекательное пространство » и Play Store. Интеграция добавляет менее 50 КБ (в сжатом виде) к среднему размеру APK-файла и занимает у большинства приложений около недели на разработку. Узнайте больше на нашем корпоративном сайте .

В этом руководстве содержатся инструкции для партнеров-разработчиков по предоставлению контента для чтения (электронных книг, аудиокниг, комиксов/манги) на информационных платформах Engage.

Детали интеграции

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

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

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

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

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

    

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

    

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

  

• В разделе «Рекомендуемые» представлены избранные элементы от нескольких партнеров-разработчиков в едином интерфейсе. Будет создан единый раздел «Рекомендуемые», который будет отображаться в верхней части интерфейса с приоритетным размещением над всеми разделами «Рекомендуемые». Каждому партнеру-разработчику будет разрешено транслировать до 10 объектов в разделе «Рекомендуемые».

  

Предварительная работа

Минимальный уровень 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.5.12'
}

Краткое содержание

Данная архитектура основана на реализации привязанного сервиса .

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

Шаг 1: Предоставьте данные сущности.

В SDK определены различные сущности для представления каждого типа элементов. Для категории «Чтение» мы поддерживаем следующие сущности:

1. EbookEntity
2. AudiobookEntity
3. BookSeriesEntity

Приведенные ниже диаграммы описывают доступные характеристики и требования для каждого типа.

EbookEntity

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

AudiobookEntity

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

BookSeriesEntity

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

Технические характеристики изображения

Ниже перечислены необходимые спецификации для графических ресурсов:

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

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 используется для проверки доступности сервиса для интеграции и возможности отображения контента на устройстве.

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.
    }
}

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 .

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

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

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

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

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

publishFeaturedCluster

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

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

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

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

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

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

publishContinuationCluster

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

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

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

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

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

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

publishUserAccountManagementRequest

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

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

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());

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.

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

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

deleteRecommendationClusters

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteContinuationCluster

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

client.deleteContinuationCluster()

client.deleteContinuationCluster();

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

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

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

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

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 , при этом причина ошибки указывается в виде кода ошибки.

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

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

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

Для настройки BroadcastReceiver необходимо использовать два следующих способа:

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

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)
}

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);

}

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

<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_CONTINUATION It is recommended to start a вызов `publishContinuationCluster` при получении этого интента.

Рабочий процесс интеграции

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

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

Часто задаваемые вопросы по Engage SDK можно найти в разделе "Часто задаваемые вопросы".

Контакт

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

Следующие шаги

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

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