ピクチャー イン ピクチャー広告を実装する（ベータ版）

ピクチャー イン ピクチャー

ピクチャー イン ピクチャー（PIP）広告は、記事、フィード、ゲームプレイなど、画面上のコンテンツの上に重ねて表示されるフローティング ウィンドウに表示されます。このフォーマットでは、広告が表示されたまま、ユーザーがアプリを操作できます。画面全体を占有しない広告を表示するには、このフォーマットを選択します。 詳しくは、ピクチャー イン ピクチャー 広告をご覧ください。

このガイドでは、アプリでピクチャー イン ピクチャー広告をリクエストして表示する方法について説明します GMA Next-Gen SDKを使用します。

始める前に

続行する前に、次の操作を行います。

広告を読み込む

PictureInPictureAd を読み込むには、広告リクエストを作成して load メソッドを呼び出します。

Kotlin

private fun loadPictureInPictureAd() {
  val request = PictureInPictureAdRequest.Builder(AD_UNIT_ID).build()

  PictureInPictureAd.load(
    request,
    object : AdLoadCallback<PictureInPictureAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(TAG, "Picture-in-Picture ad failed to load: $adError")
      }

      override fun onAdLoaded(ad: PictureInPictureAd) {
        Log.d(TAG, "Picture-in-Picture ad loaded.")

        // Capture the PictureInPictureAd reference for later use.
        pipAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

Java

private void loadPictureInPictureAd() {
  PictureInPictureAdRequest request = new PictureInPictureAdRequest.Builder(AD_UNIT_ID).build();

  PictureInPictureAd.load(
      request,
      new AdLoadCallback<PictureInPictureAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(TAG, "Picture-in-Picture ad failed to load: " + adError);
        }

        @Override
        public void onAdLoaded(@NonNull PictureInPictureAd ad) {
          Log.d(TAG, "Picture-in-Picture ad loaded.");

          // Capture the PictureInPictureAd reference for later use.
          pipAd = ad;
          setAdEventCallback(ad);
        }
      });
}

AD_UNIT_ID は、実際の広告ユニット ID に置き換えてください。

広告を表示する

ピクチャー イン ピクチャー広告を画面に表示するには、ピクチャー イン ピクチャー オプションを構成して show メソッドを呼び出します。次の例では、広告のデフォルトの位置と表示スコープを画面に設定しています。

Kotlin

private fun showPictureInPictureAd(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    val options =
      PictureInPictureAdOptions.Builder()
        // Uses the Google Mobile Ads SDK's default screen position.
        .setPosition(PictureInPictureAdPosition.DEFAULT)
        // Binds the ad lifecycle to the host screen.
        .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
        .build()
    ad.show(activity, options)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

Java

private void showPictureInPictureAd(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    PictureInPictureAdOptions options =
        new PictureInPictureAdOptions.Builder()
            // Uses the Google Mobile Ads SDK's default screen position.
            .setPosition(PictureInPictureAdPosition.DEFAULT)
            // Binds the ad lifecycle to the host screen.
            .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
            .build();
    pipAd.show(activity, options);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

位置を設定する

デフォルトでは、GMA Next-Gen SDK は、ピクチャー イン ピクチャー広告を最初に表示するときは画面の右下隅に、以前に表示したことがある場合は最後に表示した位置に表示します。広告の表示位置をカスタマイズするには、ピクチャー イン ピクチャー オプションで位置を設定します。次の例では、画面の左上隅のコンテンツの上に位置を設定しています。

Kotlin

private fun createTopLeftPositionOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Sets the ad position to the top-left corner of the screen.
    .setPosition(PictureInPictureAdPosition.TOP_LEFT)
    .build()
}

Java

private PictureInPictureAdOptions createTopLeftPositionOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Sets the ad position to the top-left corner of the screen.
      .setPosition(PictureInPictureAdPosition.TOP_LEFT)
      .build();
}

使用可能なすべての位置については、 PictureInPictureAdPositionをご覧ください。

表示スコープを設定する

デフォルトでは、GMA Next-Gen SDK はピクチャー イン ピクチャー広告を現在のホスト 画面にバインドします。GMA Next-Gen SDK ホスト画面のビュー階層が メモリに存在しなくなると、広告を閉じます。ホスト画面がメモリから削除された後も広告を表示するには、表示スコープをアプリケーションに設定します。

Kotlin

private fun createApplicationScopedOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Keeps the ad visible beyond the host screen's lifecycle.
    .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
    .build()
}

Java

private PictureInPictureAdOptions createApplicationScopedOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Keeps the ad visible beyond the host screen's lifecycle.
      .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
      .build();
}

詳しくは、画面間で広告を表示したままにする をご覧ください。

広告イベントのコールバックを設定する

ピクチャー イン ピクチャー広告のライフサイクル イベントを処理するには、広告を表示する前に広告にイベント コールバックを設定します。このコールバックは、クリックやインプレッションなどの標準イベントを報告します。また、広告の表示や非表示など、ピクチャー イン ピクチャー固有のイベントも報告します。

Kotlin

private fun setAdEventCallback(pipAd: PictureInPictureAd) {
  pipAd.adEventCallback =
    object : PictureInPictureAdEventCallback {
      override fun onAdShown() {
        Log.d(TAG, "Picture-in-Picture ad shown.")
      }

      override fun onAdHidden() {
        Log.d(TAG, "Picture-in-Picture ad hidden.")
      }

      override fun onAdImpression() {
        Log.d(TAG, "Picture-in-Picture ad recorded an impression.")
      }

      override fun onAdClicked() {
        Log.d(TAG, "Picture-in-Picture ad recorded a click.")
      }

      override fun onAdShowedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.")
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        Log.w(
          TAG,
          "Picture-in-Picture ad failed to show full screen content: $fullScreenContentError",
        )
      }

      override fun onAdPaid(value: AdValue) {
        Log.d(TAG, "Picture-in-Picture ad paid: ${value.valueMicros} ${value.currencyCode}")
      }
    }
}

Java

private void setAdEventCallback(@NonNull PictureInPictureAd pipAd) {
  pipAd.setAdEventCallback(
      new PictureInPictureAdEventCallback() {
        @Override
        public void onAdShown() {
          Log.d(TAG, "Picture-in-Picture ad shown.");
        }

        @Override
        public void onAdHidden() {
          Log.d(TAG, "Picture-in-Picture ad hidden.");
        }

        @Override
        public void onAdImpression() {
          Log.d(TAG, "Picture-in-Picture ad recorded an impression.");
        }

        @Override
        public void onAdClicked() {
          Log.d(TAG, "Picture-in-Picture ad recorded a click.");
        }

        @Override
        public void onAdShowedFullScreenContent() {
          Log.d(TAG, "Picture-in-Picture ad showed full screen content.");
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.");
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.w(
              TAG,
              "Picture-in-Picture ad failed to show full screen content: "
                  + fullScreenContentError);
        }

        @Override
        public void onAdPaid(@NonNull AdValue value) {
          Log.d(
              TAG,
              "Picture-in-Picture ad paid: "
                  + value.getValueMicros()
                  + " "
                  + value.getCurrencyCode());
        }
      });
}

広告を非表示にする

フローティング広告を画面から削除するには、hide メソッドを呼び出します。このメソッドは、広告の非表示イベント コールバックを呼び出します。

Kotlin

private fun hidePictureInPictureAd() {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    ad.hide()
  } else {
    Log.d(TAG, "No ad to hide.")
  }
}

Java

private void hidePictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.hide();
  } else {
    Log.d(TAG, "No ad to hide.");
  }
}

広告リソースをクリーンアップする

メモリリークを回避するには、アプリで広告の使用が終了したら、広告オブジェクトへの参照を削除します。たとえば、アプリで広告が表示されなくなったり、広告が操作されなくなったりした場合などです。画面スコープの広告の場合は、アプリがホスト画面をメモリから削除するときに参照を削除します。アプリスコープの広告の場合は、ユーザーが画面間を移動している間は広告の参照を保持し、ユーザーが広告を閉じたら参照を削除します。

Kotlin

private fun cleanUpPictureInPictureAd() {
  pipAd?.destroy()
  pipAd = null
}

Java

private void cleanUpPictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.destroy();
    pipAd = null;
  }
}

画面間で広告を表示したままにする

表示スコープをアプリケーションに設定すると、アプリがホスティング画面をメモリから削除しても、ピクチャー イン ピクチャー広告は表示されたままになります。ユーザーがホスト画面から移動したときに広告を操作または閉じるには、アプリがピクチャー イン ピクチャー広告にアクセスできる状態を維持する必要があります。広告は、1 つの画面のインスタンス変数ではなく、アプリレベルのシングルトンまたは共有状態マネージャーに保持することをおすすめします。

画面間で広告を表示したままにする方法の例については、サンプルアプリをご覧ください。