Engage SDK Codelab

1. はじめに

最終更新日: 2024 年 5 月 14 日

Engage SDK とは

Engage SDK を使用すると、ユーザーが利用している複数のデバイス上の Google サーフェスに個人用アプリのコンテンツを表示して、アプリのエンゲージメントを高めることができます。Engage SDK により、アプリはパーソナライズされた(1 対 1)おすすめコンテンツや連続性コンテンツを配信して、インストール済みのユーザーがアプリを開く前にエンゲージメントを高めることができます。

コンテンツ サーフェス

コレクション

エンターテイメント スペース

Google Play ストア(近日公開)

新しい Google Play ストア ウィジェットを使用して、ユーザーのホーム画面にコンテンツを直接表示できます。

一部の Android タブレットで、エンターテイメント コンテンツの新しいタッチポイントを作成できます。

今年の夏には、Google Play ストアを皮切りに、他のサーフェスにもアクセスできるようになります。

作成するアプリの概要

この Codelab を完了すると、Google サーフェスにコンテンツを送信できる Android 動画アプリができあがります。

必要なもの

  • 最新の Android SDK
  • 最新の Android Studio
  • Android 10 以降を搭載したモバイル デバイス 1 台。
  • モバイル デバイスを開発用コンピュータに接続するための USB データケーブル

エクスペリエンス

  • Java または Kotlin の使用経験があること。
  • Android 開発の知識があること。

2. サンプルアプリを実行する

始める前に、この Codelab の手順に沿って進めるためにサンプルアプリのコードをダウンロードします。

git がインストールされている場合は、リポジトリのクローンを作成します。

git clone https://github.com/googlesamples/engage-sdk-samples.git

または、こちらのリンクをクリックしてソースコードをダウンロードし、ダウンロードした zip ファイルを解凍します。

このプロジェクトは Gradle ビルドシステムを使用します。このプロジェクトをビルドするには、gradlew ビルド コマンドを使用するか、Android Studio で [プロジェクトをインポート] を使用します。

コードをダウンロードすると、2 つのサンプル プロジェクトが表示されます。

  • Java デベロッパーの場合 - 読書サンプルアプリを使用

このアプリは基本的な書籍ライブラリです。ユーザーはリストから書籍を選択し、その書籍を読み始めることができます。このアプリは、おすすめと連続性のデータが公開される仕組みを示しています。

  • Kotlin デベロッパーの場合 - 視聴サンプルアプリを使用

このアプリは基本的な動画ライブラリです。ユーザーはリストから動画を選択し、動画の視聴を開始できます。このアプリは、おすすめと連続性のデータが公開される仕組みを示しています。

Android 開発の学習に関するその他のリソースについては、developer.android.com のデベロッパー ガイドをご覧ください。

3. エンティティを作成する

この Codelab では、読書サンプルアプリと視聴サンプルアプリについて、それぞれ Engage SDK Read の統合ガイドEngage SDK Watch の統合ガイドを参照します。

エンティティは、クラスタ内の単一のアイテムを表すオブジェクトです。エンティティには、電子書籍、映画、関連するコンテンツ タイプなどがあります。

読書コンテンツの場合、SDK には次のエンティティ タイプがあります。

  • EbookEntity
  • AudiobookEntity
  • BookSeriesEntity

視聴コンテンツの場合、SDK には次のエンティティ タイプがあります。

  • MovieEntity
  • TvShowEntity
  • TvSeasonEntity
  • TvEpisodeEntity
  • LiveStreamingVideoEntity
  • VideoClipEntity

読書サンプルアプリで、EbookToEntityConverter.java ファイルに移動します。このファイルには、公開用の EbookEntity を作成するメソッドが含まれています。

EbookEntity.Builder entityBuilder = new EbookEntity.Builder()
        .setName("NAME OF EBOOK")
        .addAuthor("AUTHOR NAME")
        .setActionLinkUri(Uri.parse("DEEPLINK URI OF THIS EBOOK"))
        ...
         .build()

視聴サンプルアプリで、ItemToEntityConverter.kt ファイルに移動します。このファイルには、公開用の MovieEntity を作成するメソッドが含まれています。

val movieBuilder: MovieEntity.Builder =
      MovieEntity.Builder()
        .setName("NAME OF THE MOVIE")
        .addPosterImage(
          Image.Builder()
            .setImageUri(
              Uri.parse("android.resource://movie")
            )
            .setImageWidthInPixel(408)
            .setImageHeightInPixel(960)
            .setImageTheme(ImageTheme.IMAGE_THEME_LIGHT)
            .build()
        )
        .setPlayBackUri(Uri.parse(movie.playbackUri))
        .setReleaseDateEpochMillis(movie.releaseDate)
        .setAvailability(movie.availability)
        .setDurationMillis(movie.durationMillis)
        .addGenre(movie.genre)
          ..
           .build()

アプリケーション内でも同様に、独自のデータアイテムを公開したい対応する Engage エンティティに変換することもできます。

4. おすすめコンテンツ クラスタを構築する

エンティティを作成したので、クラスタにグループ化できます。

クラスタは、コンテンツをまとめたコレクションです。単一のデベロッパー パートナーが提供するコンテンツ アイテムのグループが表示される UI ビューとして可視化できます。

e8ec28fa54ac7eec.png

単一のパートナーが提供する電子書籍エンティティを含むおすすめコンテンツ クラスタが表示されているエンターテイメント スペースの UI。

読書コンテンツや視聴コンテンツなど、ほとんどのカテゴリで、SDK には次のクラスタタイプがあります。

  • おすすめコンテンツ クラスタは、アプリでのユーザーの行動に基づいてパーソナライズでき、新作、値下げ、ユーザーのお気に入りのトピックなど、テーマ別に整理できます。各アプリは、ユーザーごとに最大 5 つのおすすめコンテンツ クラスタを提供できます。
  • 連続性クラスタは、複数のアプリのコンテンツを 1 つの UI グループにまとめ、未視聴の映画や電子書籍などの進行中のコンテンツをユーザーが再開できるようにします。
  • 注目コンテンツ クラスタは、より大きくプレミアムな UI テンプレートを使用して、マルチアプリ クラスタ内のヒーロー コンテンツをハイライトできます。

読書コンテンツと視聴コンテンツの両方に対しておすすめコンテンツ クラスタを構築します。

読書サンプルアプリで、GetRecommendationClusters.java ファイルに移動します。ここには、おすすめコンテンツ クラスタの構築方法の例を示されています。

RecommendationCluster.Builder clusterBuilder = new RecommendationCluster.Builder();
// Set the cluster title
clusterBuilder.setTitle("For You");
for (int id : ebookIds) {
  //Create an ebook entity.
  EbookEntity entity = EbookToEntityConverter.convert(id); 
  // Add the ebook entity to the cluster
  clusterBuilder.addEntity(entity);
}
// Build the cluster
return clusterBuilder.build();

視聴サンプルアプリで、ClusterRequestFactory.kt ファイルに移動します。ここには、おすすめコンテンツ クラスタを作成する方法の例が示されています。

// Loads all the movie data 
val recommendationsList = movieDao.loadMovieIsCurrentlyWatching(false)
val recommendationCluster = RecommendationCluster.Builder()
for (item in recommendationsList) {
   //Create a movie entity.
    val movieEntity = ItemToEntityConverter.convertMovie(item)
    // Add the movie entity to the cluster
    recommendationCluster.addEntity(movieEntity)
}
// Build the cluster
return recommendationCluster.build

5. おすすめコンテンツ クラスタを公開する

ここまでで、エンティティを作成する方法と、これらのエンティティをクラスタにグループ化する方法を学びました。次のステップでは、クラスタを公開する方法について説明します。

AppEngagePublishClient は、クラスタを公開するための接続を確立します。

ステップ 1: クライアントを初期化する

// Java version
AppEngagePublishClient client = new AppEngagePublishClient(context);
// Kotlin version
val client = AppEngagePublishClient(context)

ステップ 2: クラスタを公開するリクエストを作成する

読書サンプルアプリで、EngageServiceWorker.java の setRecommendations メソッドを確認します。

// Initialize the builder
PublishRecommendationClustersRequest.Builder publishRequestBuilder = new PublishRecommendationClustersRequest.Builder();

// Add all Recommendation Clusters
for (RecommendationCluster cluster : clusters) {
   publishRequestBuilder.addRecommendationCluster(cluster);
}
// Build the request    
publishRequestBuilder.build();

視聴サンプルアプリで、ClusterRequestFactory.kt の constructRecommendationClustersRequest メソッドを確認します。

// Initialize the builder
val request = PublishRecommendationClustersRequest.Builder()
// Add all Recommendation Cluster
.addRecommendationCluster(recommendationCluster)
// Build the request    
.build()

ステップ 3: AppEngagePublishClient で publishRecommendationClusters メソッドを呼び出す

読書サンプルアプリで、EngageServiceWorker.java の setRecommendations メソッドを確認します。

client.publishRecommendationClusters(publishRequest);

視聴サンプルアプリで、EngageServiceWorker.kt の publishRecommendations メソッドを確認します。

client.publishRecommendationClusters(request)

isServiceAvailable API を使用する

publish API を呼び出す前に、isServiceAvailable を呼び出して、公開が許可されていることを確認する必要があります。

読書サンプルアプリで、EngageServiceWorker.java の startWork メソッドを確認します。

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

視聴サンプルアプリで、EngageServiceWorker.kt の doWork メソッドを確認します。

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

6. 公開ステータス

コンテンツが公開されない理由を示すには、updatePublishStatus API を使用することをおすすめします。これにより、アプリが意図的にコンテンツを公開していない場合に誤ったアラートを回避し、コンテンツにアクセスするための修正措置を講じるようにユーザーに案内し、コンテンツの公開状況に関する分析情報を提供できます。

ステータス コードについては、デベロッパー サイトをご覧ください。たとえば、ユーザーがログインする必要があるためにコンテンツが表示されない場合は、NOT_PUBLISHED_REQUIRES_SIGN_IN を使用します。このコードは次のステップで適用します。

読書サンプルアプリで、EngageServiceWorker.ktpublishAndSetResult メソッドを確認します。

int publishStatusCode;
              if (loggedInAccount.isPresent()) {
                // If an account is logged in and content is published
                publishStatusCode = AppEngagePublishStatusCode.PUBLISHED;
              } else {
                // If an account is not logged in and no content is published
                publishStatusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN;
              }
              setPublishStatus(client, publishStatusCode);
            })

視聴サンプルアプリで、EngageServiceWorker.ktpublishUserAccountManagement メソッドを確認します。

private suspend fun publishUserAccountManagement(): Result {
    val publishTask: Task<Void>
    val statusCode: Int
    if (db.accountDao().isAccountSignedIn()) {
      // If an account is logged in and content is published
statusCode = AppEngagePublishStatusCode.PUBLISHED
    } else {
     // If an account is not logged in and no content is published
      statusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN
    }
    return publishAndProvideResult(publishTask, statusCode)
  }

7. Work Manager とブロードキャスト インテント

Work Manager

コンテンツ公開ジョブはバックグラウンドで実行することをおすすめします(WorkManager を使用)。定期的に(1 日に 1 回など)スケジュールするか、ユーザー イベント(アプリの起動時やユーザーが読み上げセッションを終了した後など)に基づいてスケジュールします。以下の例では、スケジュール設定された公開に焦点を当てます。

読書サンプルアプリSetEngageState.java ファイルの queuePeriodicSetEngageStateWorker は、WorkManager を設定する方法の例を示しています。

// Create a work manager
WorkManager workManager = WorkManager.getInstance(appContext);

// Set up a periodic work request for 24 hrs.
PeriodicWorkRequest publishRequest =
        new PeriodicWorkRequest.Builder(
                EngageServiceWorker.class, /* repeatInterval= */ 24, TimeUnit.HOURS)
            .setInputData(clusterToPublishData)
            .build();
// Add the work request to queue
workManager.enqueueUniquePeriodicWork(
        publishWorkName, ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE, publishRequest);

視聴サンプルアプリPublisher.kt の periodicallyCallEngageServiceWorker は、WorkManager を設定する方法の例を示しています。

// Set up a periodic work request for 24 hrs.
val workRequest = PeriodicWorkRequestBuilder<EngageServiceWorker>(
          repeatInterval = 24,
          repeatIntervalTimeUnit = TimeUnit.HOURS
        )
        .setInputData(workDataOf(PUBLISH_TYPE to publishType))
        .build()

// Create a work manager and add the work request to queue
WorkManager.getInstance(context)
.enqueueUniquePeriodicWork(
workerName,
ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
workRequest
)

ブロードキャスト インテント

ジョブを介してコンテンツ公開 API の呼び出しを行うだけでなく、コンテンツ公開のリクエストを受信するために BroadcastReceiver を設定する必要もあります。

ブロードキャスト インテントの主目的は、アプリの再有効化とデータ同期の強制です。ブロードキャスト インテントは、頻繁に送信されることを想定した設計にはなっていません。Engage のサービスが、コンテンツが古い可能性がある(1 週間前など)と判断した場合にのみトリガーされます。そうすることで、アプリが長時間実行されていない場合でも、より確実にユーザーに新しいコンテンツを提供できます。

BroadcastReceiver は、次の 2 つの方法で設定する必要があります。

  • Context.registerReceiver() を使用して、BroadcastReceiver クラスのインスタンスを動的に登録します。これにより、メモリ内でまだアクティブになっているアプリからの通信が可能になります。

読書サンプルアプリで MainActivity.java ファイルを開き、以下を確認します。

private void registerReceiver() {
    BroadcastReceiver publishReceiver = new EngageServiceBroadcastReceiver();
    IntentFilter filter = new IntentFilter();
    filter.addAction(Intents.ACTION_PUBLISH_RECOMMENDATION);
    filter.addAction(Intents.ACTION_PUBLISH_FEATURED);
    filter.addAction(Intents.ACTION_PUBLISH_CONTINUATION);
    int flags = ContextCompat.RECEIVER_EXPORTED;
    ContextCompat.registerReceiver(getApplicationContext(), publishReceiver, filter, flags);
  }
  • AndroidManifest.xml ファイルで <receiver> タグを使用して、実装を静的に宣言します。これにより、アプリが実行されていないときでもブロードキャスト インテントを受信し、コンテンツを公開できるようになります。

読書サンプルアプリで AndroidManifest.xml ファイルを開き、以下を確認します。

<receiver
        android:name=".publish.EngageServiceBroadcastReceiver"
        android:exported="true">
      <intent-filter>
        <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
        <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
        <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
             </intent-filter>
 </receiver>

次のインテントがサービスによって送信されます。

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION このインテントを受信したときに、publishRecommendationClusters の呼び出しを開始することをおすすめします。
  • com.google.android.engage.action.PUBLISH_FEATURED このインテントを受信したときに、publishFeaturedCluster の呼び出しを開始することをおすすめします。
  • com.google.android.engage.action.PUBLISH_CONTINUATION このインテントを受信したときに、publishContinuationCluster の呼び出しを開始することをおすすめします。

8. テストに検証アプリを使用する

検証アプリをダウンロードして、統合を確認します。

検証用アプリでは、各クラスタが別々の行として表示されます。

  • データを公開するパッケージの名前を入力します。

d1ad850cd02991d.png

  • クラスタ内のすべてのエンティティが公開されていることを確認します。

3953d00488212411.png

  • エンティティ内のすべてのフィールドが公開されていることを確認します。行内の各アイテムで、ポスター画像をクリックしてインテントを検証できます。

23cd19224397adf3.png

ブロードキャスト インテント フローを確認する

検証アプリを使用してブロードキャスト インテントを検証し、UI の上部にあるボタンをクリックして、ブロードキャスト送信のロジックをトリガーします。

9cb0b5315057fbe1.png

9. 完了

Android アプリに Engage SDK を追加する方法は以上です。

詳しくは、Engage SDK デベロッパー ガイドとビジネス サイトをご覧ください。

リソース

公開されるコンテンツの種類に応じて、SDK にはさまざまなタイプのエンティティクラスが含まれています。利用可能なエンティティのリストは、以下の各カテゴリの統合ガイドで確認できます。