FIVE Android SDK version 20211029 マイグレーションガイド

本ガイドでは FiveAd Android SDK version 20211029 以降の SDK へのマイグレーション方法を説明します。

FiveAd Android SDK version 20211029 では以下の API 変更が行われました。

以下ではこれらの変更に対応する方法について説明いたします。

FiveAdListener の非推奨化と FiveAdLoadListener と FiveAdViewEventListener の新設

従来のコールバックAPIは、エラーが単一のコールバックで返されておりロード失敗と広告の表示中のエラーの区別がつきにくい、また静止画の場合にのみ返される onFiveAdImpressionImage というコールバックが存在したが、動画と静止画で処理を分ける必要があり扱いづらいといった問題がありました。そこで、今回のアップデートではこれらの問題を解決するようにコールバックAPIを再設計しました。

FiveAdListener は FiveAdLoadListener と FiveAdViewEventListener に分割されました。 FiveAdListener を利用したコードは従来通り動作しますが、新しい API には以下のような優位点があります。

具体的な手順

以下のプログラムをマイグレーションすることを考えます。

// マイグレーション前
class Before extends Activity implements FiveAdListener {
  private FiveAdCustomLayout customLayoutAd;
  private void showAd() {
    customLayoutAd = new FiveAdCustomLayout(this, SLOT_ID);
    customLayoutAd.setListener(this);
    customLayoutAd.loadAdAsync();
  }
  public void onFiveAdLoad(@NonNull FiveAdInterface ad) {
    // ロード成功時の処理
  }
  public void onFiveAdError(@NonNull FiveAdInterface ad, @NonNull FiveAdListener.ErrorCode errorCode) {
    // ロードエラー時の処理
    // 表示エラー時の処理
  }
  public void onFiveAdStart(@NonNull FiveAdInterface ad) {
    // 動画広告の再生開始を計測
  }
  public void onFiveAdImpressionImage(@NonNull FiveAdInterface ad) {
    // 静止画広告のインプレッションを計測
  }
  public void onFiveAdClose(@NonNull FiveAdInterface ad) {
    // 広告が閉じたときの処理
  }

  // 他の FiveAdListener メソッド
}

// マイグレーション step 1
class Step1 extends Activity implements FiveAdListener, FiveAdLoadListener, FiveAdViewEventListener {
  private FiveAdCustomLayout customLayoutAd;
  private void showAd() {
    customLayoutAd = new FiveAdCustomLayout(this, SLOT_ID);
    customLayoutAd.setListener(this);
    customLayoutAd.loadAdAsync();
  }
  public void onFiveAdLoad(@NonNull FiveAdInterface ad) {
    // ロード成功時の処理
  }
  public void onFiveAdError(@NonNull FiveAdInterface ad, @NonNull FiveAdListener.ErrorCode errorCode) {
    // ロードエラー時の処理
    // 表示エラー時の処理
  }
  public void onFiveAdStart(@NonNull FiveAdInterface ad) {
    // 動画広告の再生開始を計測
  }
  public void onFiveAdImpressionImage(@NonNull FiveAdInterface ad) {
    // 静止画広告のインプレッションを計測
  }
  public void onFiveAdClose(@NonNull FiveAdInterface ad) {
    // 広告が閉じたときの処理
  }

  public void onFiveAdImpression(@NonNull FiveAdInterface ad) {
    // インプレッションを計測
  }
  public void onFiveAdLoadError(@NonNull FiveAdInterface ad, @NonNull FiveAdErrorCode errorCode) {
    // ロードエラー時の処理
  }
  public void onFiveAdViewError(@NonNull FiveAdInterface ad, @NonNull FiveAdErrorCode errorCode) {
    // 表示エラー時の処理
  }

  // 他の FiveAdListener メソッド
}

// マイグレーション step 2
class Step2 extends Activity implements FiveAdListener, FiveAdLoadListener, FiveAdViewEventListener {
  private FiveAdCustomLayout customLayoutAd;
  private void showAd() {
    customLayoutAd = new FiveAdCustomLayout(this, SLOT_ID);
    customLayoutAd.setLoadListener(this);
    customLayoutAd.setViewEventListener(this);
    customLayoutAd.loadAdAsync();
  }
  public void onFiveAdLoad(@NonNull FiveAdInterface ad) {
    // ロード成功時の処理
  }
  public void onFiveAdError(@NonNull FiveAdInterface ad, @NonNull FiveAdListener.ErrorCode errorCode) {
    // ロードエラー時の処理
    // 表示エラー時の処理
  }
  public void onFiveAdStart(@NonNull FiveAdInterface ad) {
    // 動画広告の再生開始を計測
  }
  public void onFiveAdImpressionImage(@NonNull FiveAdInterface ad) {
    // 静止画広告のインプレッションを計測
  }
  public void onFiveAdClose(@NonNull FiveAdInterface ad) {
    // 広告が閉じたときの処理
  }

  public void onFiveAdImpression(@NonNull FiveAdInterface ad) {
    // インプレッションを計測
  }
  public void onFiveAdLoadError(@NonNull FiveAdInterface ad, @NonNull FiveAdErrorCode errorCode) {
    // ロードエラー時の処理
  }
  public void onFiveAdViewError(@NonNull FiveAdInterface ad, @NonNull FiveAdErrorCode errorCode) {
    // 表示エラー時の処理
  }

  // 他の FiveAdListener メソッド
}

// マイグレーション step 3
class Step3 extends Activity implements FiveAdLoadListener, FiveAdViewEventListener {
  private FiveAdCustomLayout customLayoutAd;
  private void showAd() {
    customLayoutAd = new FiveAdCustomLayout(this, SLOT_ID);
    customLayoutAd.setLoadListener(this);
    customLayoutAd.setViewEventListener(this);
    customLayoutAd.loadAdAsync();
  }
  public void onFiveAdLoad(@NonNull FiveAdInterface ad) {
    // ロード成功時の処理
  }
  public void onFiveAdStart(@NonNull FiveAdInterface ad) {
    // 動画広告の再生開始を計測
  }
  public void onFiveAdClose(@NonNull FiveAdInterface ad) {
    // 広告が閉じたときの処理
  }

  public void onFiveAdImpression(@NonNull FiveAdInterface ad) {
    // インプレッションを計測
  }
  public void onFiveAdLoadError(@NonNull FiveAdInterface ad, @NonNull FiveAdErrorCode errorCode) {
    // ロードエラー時の処理
  }
  public void onFiveAdViewError(@NonNull FiveAdInterface ad, @NonNull FiveAdErrorCode errorCode) {
    // 表示エラー時の処理
  }

  // 他の FiveAdListener メソッド
}

FiveAdErrorCode の導入

FiveAdListener.onFiveAdError は FiveAdListener.ErrorCode enum を引数として受け取っていましたが、
FiveAdLoadListener.onFiveAdLoadError と FiveAdViewEventListener.onFiveAdViewError は、FiveAdErrorCode enum を引数として受け取るようになります。

FiveAdErrorCode は FiveAdListener.ErrorCode に対して以下の変更があります。

音声設定 API の再設計

従来のSDKは音声設定が分かりづらかったため、音声設定に関する再設計を行いました。簡単にまとめると、

音声設定 API の詳細

新しいSDKでは、音声設定には以下のような明確な優先順位が付けられました。

広告ごとの音声設定は FiveAdInterface の enableSound で設定することが可能です。これは従来通りの API となっています。

アプリ全体のデフォルト設定は、SDK初期化時に FiveAdConfig の enableSoundByDefault で設定することができます。従来の SDK では FiveAd.enableSound により設定していましたが、こちらは非推奨となりました。また FiveAd.isSoundEnabled もあわせて非推奨となっています。

アプリ全体のデフォルト設定は管理画面でも設定できますが、管理画面の設定よりもSDK初期化時の設定が優先されます。スロットごとの設定については、現在管理画面のリニューアルを行っており、リニューアル後に解放される予定です。

従来のSDKでは、ユーザがある広告で音声ボタンを操作すると、その設定が保存されて他の広告枠でも音声設定が変わるようになっていました。しかしこれはメディア側の意図に反する動作をしてしまうことがあったため、今回の修正で廃止されました。したがって、ユーザがある広告で音声ボタンを操作しても、他の広告でそれが反映されることはありません。

音声の仕様については、今後も改良を重ねていこうと考えています。

FiveAdConfig.formats の廃止

FADAdViewW320H180 及び FADInFeed の機能が削除されたことにより FiveAdConfig.formats の設定は不要になりました。 FiveAdConfig.formats への代入コードは削除してください。

loadAd の非推奨化

loadAd は将来廃止される予定です。 loadAdAsync をご利用ください。

非推奨だった FADAdViewW320H180 及び FADInFeed の削除

非推奨だった WebView 機能の削除

広告 ID の宣言

2021 年の Google Play 開発者サービスの更新(https://support.google.com/googleplay/android-developer/answer/6048248) に対応するために、 FiveAd Android SDK はライブラリマニフェストにて以下の広告 ID の宣言を行うように変更されました。

ビルド時にFiveAd Android SDK のライブラリマニフェストはアプリのマニフェストに統合されるため、明示的な宣言は不要です。最終的に生成されたマニフェストに広告 ID が宣言されていることをご確認ください。

一方で、広告 ID の宣言が禁止されているアプリに FiveAd Android SDK を組み込む場合には、広告 ID を取得する宣言がアプリマニフェストに統合されないようにする必要があります。

概要