フルスクリーン広告のアクティビティのサポート

SDK ランタイムは、SDK が新しいアクティビティを起動する方法に制限を課します。通常、全画面広告フォーマットでは、制御とユーザー エクスペリエンスを向上させるために別のアクティビティを開始しますが、この点が課題となります。これに対処するため、SDK ランタイムにはサンドボックス化されたアクティビティ用の新しいメカニズムが導入されています。

SDK ランタイム環境内で読み込まれた SDK は、マニフェストで <activity> タグを直接定義したり、独自のアクティビティを開始したりすることはできません。代わりに、新しいインテント アクション START_SANDBOXED_ACTIVITY が導入されました。

SDK もこのアクションでインテントを起動することは制限されますが、SDK はクライアント アプリにこのインテントの開始をリクエストできます。システムは、プラットフォーム定義のアクティビティを作成し、SDK に渡します。このアクティビティは、SDK と同じプロセスで実行されます。

SDK は、このアクティビティを使用して、全画面広告のエクスペリエンスを実装および管理できます。

プラットフォームによって提供されるアクティビティは標準の android.app.Activity で、クライアント アプリのタスクの一部として起動されます。

SDK ランタイムでのアクティビティの作成

アクティビティを作成する主な方法は 2 つあります。Jetpack の効率化された Activity ライブラリを使用する方法と、プラットフォーム API を直接操作する方法です。

Activity ライブラリは、基盤となる複雑さを抽象化することでアクティビティの作成を簡素化するため、Activity ライブラリを使用することをおすすめします。

アクティビティ ライブラリ

アクティビティ ライブラリには、次のようなメリットがあります。

  • アクティビティ ハンドラの登録と、その識別子のクライアント アプリとの共有に関する内部の詳細を抽象化します。
  • アプリ デベロッパーが、アプリ内で SDK がアクティビティを作成する方法をより細かく制御できるように、満たすべき条件（述語）を設定できるようにします。
  • アクティビティを起動する API を SDK が定義するための統一された方法を作成します。

アクティビティ ライブラリは 3 つ（コア、クライアント、プロバイダ）あります。

  • コア ライブラリは、クライアント アプリとプロバイダ ライブラリで使用されるインターフェースを提供します。
  • プロバイダ ライブラリは、SDK がアクティビティを起動するための API を提供します。
  • クライアント ライブラリは、クライアント アプリがアクティビティ ランチャーを作成するための API を提供します。SDK はこの API を使用して、アプリにアクティビティの起動をリクエストできます。

これらのライブラリでは、次の API が導入されています。

  • SdkActivityLauncher: アクティビティ ランチャーを使用すると、SDK はクライアント アプリからアクティビティの起動を処理できます。クライアント アプリはランチャーを作成し、アクティビティを開始する SDK の API にパラメータとして渡す必要があります。
  • <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): クライアント アプリがアクティビティから呼び出してランチャーを作成できる拡張関数。
  • SdkActivityLauncher.launchSdkActivity(IBinder): SDK がアプリにアクティビティの起動をリクエストするために使用するメソッド。

アクティビティ ライブラリを使用してアクティビティを起動するフローは次のとおりです。

  1. SDK は、アクティビティを開始する API に SdkActivityLauncher 型のパラメータを追加します。
  2. クライアント アプリは、アクティビティの 1 つで createSdkActivityLauncher を呼び出して、API 呼び出しで SDK に渡すことができるランチャーを作成します。
  3. SDK は SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) を呼び出し、識別子トークンを取得します。
  4. SDK は launchSdkActivity を呼び出してアクティビティを起動します。

次の図は、アクティビティ ライブラリを使用する場合のフローを示しています。

アクティビティ ライブラリのシーケンス図
アクティビティ ライブラリを使用してアクティビティを開始するフローを示すシーケンス図。

プラットフォーム API

このプラットフォームでは、SDK ランタイム内のサンドボックス化されたアクティビティの作成と管理を容易にするために、次の API が導入されています。

プラットフォーム API を使用してアクティビティを開始するには、SDK は次のフローに従う必要があります。

  1. SDK は、提供された API を使用してアクティビティ ハンドラを登録し、識別子を取得します。
  2. SDK はこの ID をクライアント アプリと共有します。
  3. クライアント アプリは、プラットフォーム API startSdkSandboxActivity(Activity, IBinder) を使用して SDK ランタイムでアクティビティを開始するメソッドを呼び出し、パラメータとして、この新しいアクティビティの選択された開始アクティビティとアクティビティ ハンドラの識別子を渡します。
  4. プラットフォームがアクティビティを開始し、アクティビティ ハンドラ（SdkSandboxActivityHandler.onActivityCreated(Activity)）のコールバックを通じて SDK に通知します。
  5. SDK はアクティビティを使用して広告を挿入します。

Platform API を使用すると、SDK は適切なタイミングで SdkSandboxActivityHandler の識別子を API を介してクライアント アプリと共有し、その使用方法をクライアント アプリに伝える役割を担います。

次のフロー図では、コールバック（SDK の API の一部として定義）を想定するメソッド launchActivity(AppCallback) を持つ SDK の例を示しています。このコールバックは、SDK がアクティビティ ハンドラ（SdkSandboxActivityHandler）の識別子をクライアント アプリと共有するために使用されます。

プラットフォーム API のシーケンス図
プラットフォーム API を使用してアクティビティを開始するフローを示すシーケンス図。

視認性

SDK ランタイム内では、クライアント アプリのビュー階層に統合された広告は、サイドチャネルを使用して、SDK プロセスからクライアント アプリのプロセスに SDK ビューをレンダリングします。

SDK は、SDK ランタイムの外部で使用する場合と同じ View API を使用して、広告がユーザーに表示されるかどうかを判断することはできません。広告ビューはアプリのウィンドウにアタッチされていないためです（視認性）。

一方、プラットフォーム提供のアクティビティは SDK ランタイム プロセス内でネイティブに実行されるため、サイドチャネルは不要になり、SDK は標準の Android Activity API と View API を使用できます。

こうした実装の違いがあるため、現在、広告の読み込みコンテキストに関係なく、ビューアビリティ シグナルを取得するためのインターフェースを統一する取り組みが進められています。

Lifecycle

SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) を介して SDK に渡される ActivityHolder は LifecycleOwner を実装し、Lifecycle.Event について知るために使用できます。

「戻る」ナビゲーション

ActivityHolder.getOnBackPressedDispatcher() メソッドは、戻るナビゲーションを処理する OnBackPressedCallback インスタンスを登録するために使用できる OnBackPressedDispatcher を返します。