Engage SDK Social: サードパーティの技術的統合手順

Google は、ユーザーのアプリをカテゴリ別に整理し、没入感のある新しいエクスペリエンスによってアプリ コンテンツの使用や発見をパーソナライズできるオンデバイス サーフェスを構築しています。このフルスクリーン エクスペリエンスにより、デベロッパー パートナーは、アプリ外の専用チャンネルで優れたリッチ コンテンツを紹介できるようになります。

このドキュメントでは、デベロッパー パートナーが Engage SDK を使用してソーシャル コンテンツを統合し、この新しいサーフェス領域にコンテンツを表示する手順を説明します。

統合の詳細

次のセクションでは、統合の詳細を説明します。

用語

おすすめコンテンツ クラスタには、特定のデベロッパー パートナーが提供する、パーソナライズされたおすすめ情報が表示されます。

おすすめコンテンツの構成は次のとおりです。

おすすめコンテンツ クラスタ: 同一のデベロッパー パートナーが提供するおすすめコンテンツのグループが表示される UI ビュー。

各おすすめコンテンツ クラスタは、次の 2 種類のエンティティのいずれかで構成されます。

  • PortraitMediaEntity
  • SocialPostEntity

PortraitMediaEntity には、投稿用の縦向き画像が 1 件必要です。プロフィールとインタラクション関連のメタデータは省略可能です。

  • 投稿

    • ポートレート モードの画像とタイムスタンプ、または
    • ポートレート モードの画像 + テキスト コンテンツとタイムスタンプ
  • プロフィール

    • アバター、名前またはハンドル、追加の画像
  • インタラクション

    • 合計数とラベルのみ、または
    • 合計数とビジュアル(アイコン)

SocialPostEntity には、プロフィール、投稿、インタラクション関連のメタデータが含まれます。

  • プロファイル

    • アバター、名前またはハンドル、追加のテキスト、追加の画像
  • 投稿

    • テキストとタイムスタンプ、または
    • リッチメディア(画像またはリッチ URL)とタイムスタンプ、または
    • テキストとリッチメディア(画像またはリッチ URL)とタイムスタンプ
  • 操作

    • カウントとラベルのみ、または
    • カウントとビジュアル(アイコン)

事前作業

最小 API レベル: 19

アプリに com.google.android.play:engage ライブラリを追加します。

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

概要

この設計は、バインドされたサービスの実装に基づいています。

クライアントが公開できるデータには、各種クラスタに関する次の上限が適用されます。

クラスタタイプ クラスタ数の上限 クラスタ内のエンティティ数の下限 クラスタ内のエンティティ数の上限
おすすめコンテンツ クラスタ 最大 5 個 最小 5 個(PortraitMediaEntity、または SocialPostEntity 最大 25 個(PortraitMediaEntity、または SocialPostEntity

ステップ 1: エンティティ データを提供する

この SDK では、各アイテムタイプを表すさまざまなエンティティを定義しています。この SDK は、ソーシャル カテゴリで次のエンティティをサポートしています。

  1. PortraitMediaEntity
  2. SocialPostEntity

下記の表に、各タイプで使用可能な属性と、必須か任意かをまとめています。

PortraitMediaEntity

属性 必須 / 任意 説明 形式
アクション URI 必須

プロバイダ アプリ内のエンティティへのディープリンク。

注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください

URI
投稿関連のメタデータ(必須)
画像 必須

画像は縦向きのアスペクト比にする必要があります。

複数の画像が指定されている場合、UI には画像が 1 つしか表示されない場合があります。ただし、アプリに他にも画像があることが、UI で視覚的に示される場合があります。

投稿が動画の場合、プロバイダは画像として表示するための動画のサムネイルを提供する必要があります。

詳しくは、画像の仕様をご覧ください。
テキスト コンテンツ 任意 投稿や更新などのメインテキスト 文字列(推奨: 最大 140 文字)
タイムスタンプ 任意 投稿が公開された日時。 エポック タイムスタンプ(ミリ秒)
プロフィール関連のメタデータ(省略可)
名前 必須 プロフィール名または ID またはハンドル(「John Doe」、「@TeamPixel」など) 文字列(推奨: 最大 25 文字)
アバター 必須

ユーザーのプロフィール写真またはアバター画像。

1:1 の正方形の画像

詳しくは、画像の仕様をご覧ください。
その他の画像 任意

プロフィール バッジ。(例: 認証済バッジ)

1:1 の正方形の画像

詳しくは、画像の仕様をご覧ください。
インタラクション関連のメタデータ(省略可)
合計数 必須 インタラクションの数を表します(例:「370 万」)。 文字列(合計数とラベルを合わせて 20 文字以内を推奨)
ラベル

任意

指定しない場合は、ビジュアルを指定する必要があります。

そのインタラクションの目的(「高評価」など)を表します。 文字列(合計数とラベルを合わせて 20 文字以内を推奨)
ビジュアル

任意

指定しない場合は、ラベルを指定する必要があります。

インタラクションの目的を表します。 例: 高評価アイコンや絵文字の画像。

複数の画像を指定できますが、その全部がすべてのフォーム ファクタに表示されるとは限りません。

1:1 の正方形の画像

詳しくは、画像の仕様をご覧ください。
DisplayTimeWindow(省略可)- コンテンツがサーフェスに表示される時間帯を設定します
開始タイムスタンプ 任意

このエポック タイムスタンプ以降にコンテンツがサーフェスに表示されます。

設定されていない場合、コンテンツはサーフェスに表示されます。

エポック タイムスタンプ(ミリ秒)
終了タイムスタンプ 任意

このエポック タイムスタンプ以降は、コンテンツがサーフェスに表示されなくなります。

設定されていない場合、コンテンツはサーフェスに表示されます。

エポック タイムスタンプ(ミリ秒)

SocialPostEntity

属性 必須 / 任意 説明 形式
アクション URI 必須

プロバイダ アプリ内のエンティティへのディープリンク。

注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください

URI

投稿関連のメタデータ(必須)

TextContent、Image、WebContent のうち少なくとも 1 つが必須です。

画像 任意

画像は縦向きのアスペクト比にする必要があります。

複数の画像が指定されている場合、UI には画像が 1 つしか表示されない場合があります。ただし、アプリに他にも画像があることが、UI で視覚的に示される場合があります。

投稿が動画の場合、プロバイダは画像として表示するための動画のサムネイルを提供する必要があります。

詳しくは、画像の仕様をご覧ください。
テキスト コンテンツ 任意 投稿や更新などのメインテキスト 文字列(推奨: 最大 140 文字)
リンク プレビュー(省略可)
リンク プレビュー - タイトル 必須 ウェブページのコンテンツのタイトルを示すテキスト 文字列
リンク プレビュー - ホスト名 必須 ウェブページの所有者を示すテキスト(例:「INSIDER」) 文字列
リンク プレビュー - 画像 任意 ウェブ コンテンツのヒーロー画像 詳しくは、画像の仕様をご覧ください。
タイムスタンプ 任意 投稿が公開された日時。 エポック タイムスタンプ(ミリ秒)
プロフィール関連のメタデータ(省略可)
名前 必須 プロフィール名または ID またはハンドル(「John Doe」、「@TeamPixel」など)。 文字列(推奨: 最大 25 文字)
追加テキスト 任意

プロフィール ID またはハンドル、または追加のメタデータとして使用可能

例: 「@John-Doe」、「フォロワー 500 万人」、「あなたへのおすすめ」、「急上昇」、「5 件の新しい投稿」

文字列(推奨: 最大 40 文字)
アバター 必須

ユーザーのプロフィール写真またはアバター画像。

1:1 の正方形の画像

詳しくは、画像の仕様をご覧ください。
その他の画像 任意

プロフィール バッジ(例: 認証済バッジ)

1:1 の正方形の画像

詳しくは、画像の仕様をご覧ください。
インタラクション関連のメタデータ(省略可)
合計数 必須 インタラクションの数を表します(例:「370 万」)。 文字列(合計数とラベルを合わせて 20 文字以内を推奨)
ラベル

任意

指定しない場合は、ビジュアルを指定する必要があります。

インタラクションの目的を表します。(例:「高評価」) 文字列(合計数とラベルを合わせて 20 文字以内を推奨)
ビジュアル

任意

指定しない場合は、ラベルを指定する必要があります。

インタラクションの目的を表します。 例: 高評価アイコンや絵文字の画像。

複数の画像を指定できますが、その全部がすべてのフォーム ファクタに表示されるとは限りません。

1:1 の正方形の画像

詳しくは、画像の仕様をご覧ください。
DisplayTimeWindow(省略可)- コンテンツがサーフェスに表示される時間帯を設定します
開始タイムスタンプ 任意

このエポック タイムスタンプ以降にコンテンツがサーフェスに表示されます。

設定されていない場合、コンテンツはサーフェスに表示されます。

エポック タイムスタンプ(ミリ秒)
終了タイムスタンプ 任意

このエポック タイムスタンプ以降は、コンテンツがサーフェスに表示されなくなります。

設定されていない場合、コンテンツはサーフェスに表示されます。

エポック タイムスタンプ(ミリ秒)

画像の仕様

Google が画像にアクセスできるようにするため、画像は公開 CDN でホストする必要があります。

ファイル形式

PNG、JPG、静止 GIF、WebP

最大ファイルサイズ

5120 KB

その他の推奨事項

  • 画像のセーフエリア: 重要なコンテンツは、画像の中央 80% の範囲内に配置してください。
  • 透明な背景を使用して、ダークモードとライトモードの設定で画像が適切に表示されるようにします。

ステップ 2: クラスタデータを提供する

WorkManager などを使用して、コンテンツ公開ジョブをバックグラウンドで実行し、定期的に、またはイベントごとに(ユーザーがアプリを開いたときや、新しいアカウントをフォローしたときなど)スケジュールを設定することをおすすめします。

AppEngageSocialClient はソーシャル クラスタの公開を行います。

クライアントでクラスタを公開するには、次の API があります。

  • isServiceAvailable
  • publishRecommendationClusters
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

この API は、サービスを統合に使用できるかどうか、コンテンツをデバイスに表示できるかどうかを確認するために使用されます。

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 オブジェクトのリストを公開するために使用されます。

RecommendationCluster オブジェクトには次の属性があります。

属性 必須 / 任意 説明
SocialPostEntity または PortraitMediaEntity のリスト 必須 このおすすめコンテンツ クラスタのおすすめコンテンツを構成するエンティティのリスト。単一クラスタ内のエンティティは、同じタイプにする必要があります。
タイトル 必須

おすすめクラスタのタイトル(例: 友人からの最新情報)。

推奨テキストサイズは 25 文字未満(長すぎるテキストは省略記号が表示されます)

アクション URI 任意

おすすめコンテンツの完全なリストをユーザーに表示するパートナー アプリ内のページへのディープリンク。

注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください

Kotlin


client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build())

Java


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build());

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

  • 既存のおすすめコンテンツ クラスタのデータがすべて削除されます。
  • リクエストのデータが解析され、新しいおすすめコンテンツ クラスタに保存されます。

エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

publishUserAccountManagementRequest

この API は、ログインカードを公開するために使用されます。ログイン アクションにより、ユーザーをアプリのログインページに誘導し、アプリでコンテンツを公開(または、よりパーソナライズされたコンテンツを提供)できるようにします。

次のメタデータはログインカードの一部です。

属性 必須 / 任意 説明
アクション URI 必須 アクションへのディープリンク(アプリのログインページへの移動など)
画像 省略可 - 指定しない場合は、タイトルを指定する必要があります

カードに表示される画像

解像度 1264×712 でアスペクト比 16×9 の画像

タイトル 省略可 - 指定しない場合は、画像を指定する必要があります カード上のタイトル
アクション テキスト 任意 行動を促すフレーズ(ログインなど)で表示されるテキスト
字幕 任意 カードの字幕(省略可)

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

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

  • デベロッパー パートナーが提供した既存の UserAccountManagementCluster データが削除されます。
  • リクエストのデータが解析されて、更新済みのユーザー アカウント管理クラスタに保存されます。

エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

updatePublishStatus

社内の業務上の理由でいずれのクラスタも公開されていない場合は、updatePublishStatus API を使用して公開ステータスを更新することを強くおすすめします。公開ステータスの更新が必要な理由は:

  • ダッシュボードではこのステータスの値に基づいて、統合の健全性などの指標が追加されるため、コンテンツが公開されている(STATUS == PUBLISHED)場合でも公開ステータスを明示する必要があります。
  • コンテンツは未公開でも統合ステータスが壊れていなければ(STATUS == NOT_PUBLISHED)、アプリの健全性ダッシュボードでアラートがトリガーされるのを回避できます。未公開ステータスを明示することで、プロバイダにとって想定済みの理由からコンテンツが非公開であるという確認がとれます。
  • デベロッパーは、データの公開状況に関する情報を提供できます。
  • 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 は、ログインカードを公開することをおすすめします。なんらかの理由でプロバイダがログインカードを公開できない場合は、ステータス コード NOT_PUBLISHED_REQUIRES_SIGN_IN を使用して、updatePublishStatus API を呼び出すことをおすすめします。

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

deleteRecommendationClusters

この API は、おすすめコンテンツ クラスタのコンテンツを削除するために使用されます。

Kotlin


client.deleteRecommendationClusters()

Java


client.deleteRecommendationClusters();

サービスがリクエストを受信すると、おすすめコンテンツ クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

deleteUserManagementCluster

この API は、ユーザー アカウント管理クラスタのコンテンツを削除するために使用されます。

Kotlin


client.deleteUserManagementCluster()

Java


client.deleteUserManagementCluster();

サービスがリクエストを受信すると、ユーザー アカウント管理クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

deleteClusters

この API は、特定のクラスタタイプのコンテンツを削除するために使用されます。

Kotlin


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

Java


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

サービスがリクエストを受信すると、指定したクラスタタイプに一致するすべてのクラスタから既存のデータが削除されます。クライアントは、1 つまたは複数のクラスタタイプを渡すこともできます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

エラー処理

publish 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 として返されます。原因はエラーコードとして含まれます。

エラーコード
SERVICE_NOT_FOUND そのデバイスではこのサービスを利用できません。
SERVICE_NOT_AVAILABLE サービスをそのデバイスで利用することはできますが、呼び出し時には利用できません(明示的に無効になっている場合など)。
SERVICE_CALL_EXECUTION_FAILURE スレッドに関する問題が発生し、タスクを実行できませんでした。その場合は再試行できます。
SERVICE_CALL_PERMISSION_DENIED 呼び出し元がサービスの呼び出しを行うことができません。
SERVICE_CALL_INVALID_ARGUMENT リクエストに無効なデータが含まれています(クラスタ数が許容数を超えているなど)。
SERVICE_CALL_INTERNAL サービス側でエラーが発生しています。
SERVICE_CALL_RESOURCE_EXHAUSTED サービスの呼び出し頻度が高すぎます。

ステップ 3: ブロードキャスト インテントを処理する

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

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

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

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

}

  • AndroidManifest.xml ファイルで <receiver> タグを使用して、実装を静的に宣言します。これにより、アプリが実行されていないときでもブロードキャスト インテントを受信し、コンテンツを公開できるようになります。
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
   </receiver>
</application>

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

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

統合ワークフロー

統合完了後に検証を行う手順のガイドについては、デベロッパー向けの Engage 統合ワークフローをご覧ください。

よくある質問

よくある質問については、Engage SDK に関するよくある質問をご覧ください。

お問い合わせ

統合プロセスについてご不明な点がありましたら、engage-developers@google.com までお問い合わせください。担当チームができる限り速やかに返信いたします。

次のステップ

この統合が完了した後のステップは次のとおりです。

  • Google によるテストの準備が整った統合済みの APK を添付して、engage-developers@google.com にメールを送信します。
  • Google 内部で検証と審査を行い、想定どおりに統合が機能するかどうかを確認します。変更が必要な場合は、Google から必要な詳細事項をご連絡します。
  • テストが完了し、変更の必要もない場合は、更新された統合済みの APK を Google Play ストアに公開できるようになったことを Google からお知らせします。
  • 更新された APK が Google Play ストアに公開されていることを Google が確認したら、おすすめコンテンツ クラスタが公開され、ユーザーに表示されます。