Amazon Publisher Services - Ad Generation Integration [Android]

Amazon Publisher ServicesとAd Generation SDKをAndroidで連携するためのマニュアルとなります。

サービスご利用にあたって

本連携については、Amazon Publisher Servicesの登録がお済みのうえ、行って頂くようお願いいたします。
Amazon Publisher Servicesのドキュメント等、公式サイトよりご確認お願いいたいます。

対応バージョン

• Android 5.0 (API Level 21)
• Amazon Publisher Services SDK v9.10.3

注意

• 広告のリフレッシュ（ローテーション）を行う場合はAmazon Publisher Servicesの機能を用いて実装してください。
• Ad Generationのローテーション及び、連携SDKのアドネットワークのローテーション設定はOFFにしてください。
• Amazon Publisher Services(DTB SDK)とAmazon Mobile Ad Network SDKの併用はサポート対象外となります。

Ad Generation管理画面での広告枠設定

1. 対象枠でカスタムタグを作成する。
2. カスタムタグ認証情報として「Amazon Header Bidding」を選択する。
3. アドネットワーク名を入力する。こちらは表示にのみ使用されます。
4. Key/CPMをデフォルト値から変更したい場合は変更します。

Amazon Publisher Services SDKの導入

Gradleを使用する (推奨)

Build.Gradleファイルを開き、 repositoriesと dependenciesに以下を追記してください。

repositories {

    ...

    mavenCentral()
}

dependencies {

    ...

    implementation ("com.amazon.android:aps-sdk:9.10.3")
}

手動でインストールする

1. [File] > [New] > [New Module] の順にクリックし、ポップアップダイアログボックスで[Import .JAR/.AAR Package] をクリックします。
2. 新しいダイアログボックスが開くので、 aps-sdk.aarまたは DTBAndroidSDK­x.x.aarをインポートします。
3. [File] > [Project Structure] > [app] > [Dependencies] と進み、対象のaar ファイルを依存関係として追加します。

アクセス権限とActivityのマニフェストへの追加

• 次のアクセス権限をマニフェストに追加します。
  INTERNET / ACCESS_WIFI_STATE / ACCESS_NETWORK_STATE は必須です。

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

• 位置情報ターゲティングをする場合は下記を追加してください

<uses-permission android：name = "android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android：name = "android.permission.ACCESS_FINE_LOCATION" />

Ad Generation SDKの導入

• Ad Generation AndroidSDKバナー導入マニュアルの[1. プロジェクトにSDKを追加する]から[3. Google Play Servicesを設定する]をご参照ください。

ProGuard

ProGuardの設定ファイルに以下を追加してください。

-keep class com.amazon.device.ads.** { *; }

Amazon Publisher Services SDK(DTB SDK)の初期設定

val apsAppID = "YOUR_APP_KEY"
val apsSlotID = "YOUR_SLOT_ID"

// アプリケーションキーを設定する
AdRegistration.getInstance(apsAppID, applicationContext)
AdRegistration.setAdNetworkInfo(DTBAdNetworkInfo(DTBAdNetwork.AD_GENERATION))

// Ad Generationのアドサーバーを利用するために下記を追加してください
// MRAIDのバージョンを 1.0, 2.0 のみセットする
AdRegistration.setMRAIDSupportedVersions(
    arrayOf(
        "1.0",
        "2.0"
    )
)
// MRAIDのポリシーをCUSTOMとしてセットする
AdRegistration.setMRAIDPolicy(MRAIDPolicy.CUSTOM)

// 位置情報の取得を許容する場合はコメントアウトを解除してください
// AdRegistration.useGeoLocation(true)

// デバッグ時はログレベル変更とテストモードを有効化してください※有効にしたままアプリをリリースしないようご注意ください
// AdRegistration.enableLogging(true) // ログ書き出し
// AdRegistration.enableTesting(true) // テストモード

public static final String APP_KEY = "YOUR_APP_KEY";
public static final String SLOT_ID = "YOUR_SLOT_ID";

// アプリケーションキーを設定する
AdRegistration.getInstance(APP_KEY, getApplicationContext());
AdRegistration.setAdNetworkInfo(new DTBAdNetworkInfo(DTBAdNetwork.AD_GENERATION));

// Ad Generationのアドサーバーを利用するために下記を追加してください
// MRAIDのバージョンを 1.0, 2.0 のみセット
AdRegistration.setMRAIDSupportedVersions(new String[] {"1.0", "2.0"});
// MRAIDのポリシーをCUSTOMとしてセットする
AdRegistration.setMRAIDPolicy(MRAIDPolicy.CUSTOM);

// 位置情報の取得を許容する場合はコメントアウトを解除してください
// AdRegistration.useGeoLocation(true);

// デバッグ時はログレベル変更とテストモードを有効化してください※有効にしたままアプリをリリースしないようご注意ください
// AdRegistration.enableLogging(true); // ログ書き出し
// AdRegistration.enableTesting(true); // テストモード

バナー広告

DTBAdRequestの生成と広告リクエスト

DTB SDKが生成するbid情報（DTBAdResponse）の有効期間は10分となります。

val adLoader: DTBAdRequest = DTBAdRequest()
adLoader.setSizes(DTBAdSize(320, 50, SLOT_ID)) // 320x50広告の場合
adLoader.loadAd(object : DTBAdCallback {
    override fun onSuccess(dtbAdResponse: DTBAdResponse) {
        android.util.Log.d("ADGSDK" , "APS ad load has succeeded")
        // Amazon広告リクエスト成功時は
        // DTBAdResponseのパラメーターを付与した上でAd Generationの広告のリクエストを行う。
        loadADG(dtbAdResponse)
    }
    override fun onFailure(adError: AdError) {
        android.util.Log.e("ADGSDK", "APS ad load has failed: " + adError.message)
        // Amazon広告リクエスト失敗時は
        // DTBAdResponseのパラメーターを付与せずAd Generationの広告のリクエストを行う。
        loadADG(null)
    }
})

final DTBAdRequest loader = new DTBAdRequest();
loader.setSizes(new DTBAdSize(320, 50, SLOT_ID)); // 320x50広告の場合
loader.loadAd(new DTBAdCallback() {
    @Override
    public void onSuccess(DTBAdResponse dtbAdResponse) {
        android.util.Log.d("ADGSDK" , "APS ad load has succeeded");
        // Amazon広告リクエスト成功時は
        // DTBAdResponseのパラメーターを付与した上でAd Generationの広告のリクエストを行う。
        loadADG(dtbAdResponse);
    }

    @Override
    public void onFailure(AdError adError) {
        android.util.Log.e("ADGSDK", "APS ad load has failed: " + adError.message);
        // Amazon広告リクエスト失敗時は
        // DTBAdResponseのパラメーターを付与せずAd Generationの広告のリクエストを行う。
        loadADG(null);
    }
});

Ad Generationの呼び出し

DTBAdResponseパラメーターの付与以外は通常のAd Genrationの広告リクエストと同様です。

fun loadADG(dtbAdResponse: DTBAdResponse?) {
    adg = ADG(this) // adgはADGクラスのインスタンスとして定義済みとする。
    adg?.locationId = "YOUR_ADGENERATION_AD_ID" // 広告枠ID指定
    adg?.setAdFrameSize(ADG.AdFrameSize.FREE.setSize(320, 50)) // サイズ指定
    adg?.adListener = AdListener() // Listener定義

    if (dtbAdResponse != null) {
        adg?.addHeaderBiddingParamsWithAmznAdResponse(dtbAdResponse)
    }
    // 表示
    ad_container?.addView(adg!!) // 広告表示領域としてad_containerを定義済みとする。
    adg?.start()
}

public void loadADG(DTBAdResponse dtbAdResponse) {
    ad_container = (LinearLayout) findViewById(R.id.ad_container); // 広告表示領域としてad_containerを定義済みとする。
    adg = new ADG(this); // adgはADGクラスのインスタンスとして定義済みとする。
    adg.setLocationId("YOUR_ADGENERATION_AD_ID"); // 広告枠ID指定
    adg.setAdFrameSize(ADG.AdFrameSize.FREE.setSize(320, 50)); // サイズ指定
    adg.setAdListener(new AdListener()); // Listener定義

    if(dtbAdResponse != null) {
        adg.addHeaderBiddingParamsWithAmznAdResponse(dtbAdResponse);
    }
    // 表示
    ad_container.addView(adg);
    adg.start();
}

@Override
protected void onPause() {
    super.onPause();
    // Ad Generationの広告ローテーションをオフにし忘れた時のためにpause処理を記述しておく
    if (adg != null) {
        adg.pause();
    }
}

@Override
protected void onDestroy() {
    super.onDestroy();
    if (adg != null) {
        // 広告を破棄する
        adg.stop();
    }
}

// Ad Generationイベントリスナー
class AdListener extends ADGListener {
    private static final String _TAG = "ADGListener";
    @Override
    public void onReceiveAd() {
        Log.d(_TAG, "onReceiveAdOfBanner");
    }
    @Override
    public void onFailedToReceiveAd(ADGConsts.ADGErrorCode code) {
        Log.d(_TAG, "onFailedToReceiveAd");
        // 不通とエラー過多のとき以外はリトライ
        // エラー時のリトライは特段の理由がない限り必ず記述するようにしてください。
        switch (code) {
            case EXCEED_LIMIT:
            case NEED_CONNECTION:
            case NO_AD:
                break;
            default:
                if (adg != null) {
                    adg.start();
                }
                break;
        }
    }
    @Override
    public void onClickAd() {
        Log.d(_TAG, "onClickAd");
    }
}

オートリフレッシュ（ローテーション）の実装

• 広告のオートリフレッシュ（ローテーション）はAd Generationの機能を使わずにDTB SDKの DTBAdRequest( DTBAdLoader)に設定してください。
  Ad Generationのローテーション及び、連携SDKのアドネットワークのローテーション設定はOFFにしてください。

loader.setAutoRefresh(45) // 45秒毎にリフレッシュを行う

loader.setAutoRefresh(45); // 45秒毎にリフレッシュを行う

• 自動更新を必ず停止してください。停止の推奨場所はActivityのonStop()およびonDestroy()です。実装によってはonPause()も推奨場所になります。自動更新処理を不適切に使用するとインプレッション数に矛盾が生じる恐れがあります。

loader.stop()

loader.stop();

注意

• 広告の自動更新処理を停止し、DTBAdLoaderで使用されているリソースを解放することは、重要です。広告の自動更新処理は、明示的に停止しない限り続行されます。その場合、想定外の挙動になり、またインプレッション数が少なくなります。
• loadAdを呼び出す前に自動更新のプロパティを設定します。loadAdを1回呼び出す際、DTBAdLoaderのインスタンスを1つだけ使用してください。また、stop()が呼び出さるとインスタンスを再使用することはできません。
• onSuccessや onFailureコールバック等で、Viewの上に重ねてViewを生成しないでください。新しいViewを作る場合、以前のViewをクリアするようにしてください。
• オートリフレッシュは60秒がデフォルト値であり、20秒未満で設定した場合、自動的に60秒に上書きされます。
• DTBAdRequest クラスの setAutoRefresh メソッドを利用せず、インスタンスの再生成などで独自にローテーションをおこなうことはお控えください
• 独自にローテーションをおこなうことが避けられない場合は、Amazon Publisher Services SDKに対してローテーションのための再リクエストであることを通知する実装が別途必要となりますので、弊社へお問い合わせ、またはAmazon社へお問い合わせください。

テストモード

テストモードを有効にするには、以下のコードを広告リクエストより前に実行してください。

AdRegistration.enableLogging(true)
AdRegistration.enableTesting(true)

AdRegistration.enableLogging(true);
AdRegistration.enableTesting(true);

注意

テスト広告は属性の資格がないため、本番ではテストコードを忘れずに削除してください。

通信の検証

通信の検証を行う場合は、下記の公式サイトを参考に検証を行ってください。

Sending Artifacts to APS for Verification (opens new window)
Mobile Integration Self-Check Guide (opens new window)