Amazon Publisher Services - Ad Generation Integration [iOS]

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

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

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

対応バージョン

• iOS 13.0
• Xcode 15.4
• Ad Generation SDK v2.26.1
• Amazon Publisher Services SDK v4.10.1（2024-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の導入

CocoaPodを使用する（推奨）

1. 以下の行をプロジェクトのPodfileに追加します。
   pod 'AmazonPublisherServicesSDK', '4.10.1'

2. pod installを実行します

手動でインストールする

• 下記のフレームワークを追加してください。
  • DTBiOSSDK.xcframework
  • AdSupport
  • CoreGraphics
  • CoreTelephony
  • SystemConfiguration
  • CoreLocation

APS向けのSKAdNetworkIDを追加する

Info.plist に対して、下記のIDを追加お願いいたします。

<key>SKAdNetworkItems</key>
<array>
 <dict>
   <key>SKAdNetworkIdentifier</key>
   <string>vhf287vqwu.skadnetwork</string>
 </dict>
</array>

amazon publisher services SKAdNetwork ID List (opens new window)

Ad Generation SDKの導入

• Ad Generation iOSSDKバナー導入マニュアルの[1. SDKをダウンロードする]をご参照ください。

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

AppDelegate.mのdidFinishLaunchingWithOptionsにて初期設定を行います。

import DTBiOSSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // アプリケーションキーを設定する
    DTBAds.sharedInstance().setAppKey("YOUR_APP_KEY")

    // アドネットワーク設定
    DTBAds.sharedInstance().setAdNetworkInfo(DTBAdNetworkInfo(networkName: DTBADNETWORK_AD_GENERATION))

    // Ad Generationのアドサーバーを利用するために下記を追加してください
    DTBAds.sharedInstance().mraidPolicy = CUSTOM_MRAID
    DTBAds.sharedInstance().mraidCustomVersions = ["1.0", "2.0"]

    // 位置情報を収集して活用する場合は下記を追加してください
    // DTBAds.sharedInstance().useGeoLocation = true

    // デバッグ時はログレベル変更とテストモードを有効化してください※アプリリリース時は呼び出さないでください
    // DTBAds.sharedInstance().setLogLevel(DTBLogLevelAll) // ログレベル
    // DTBAds.sharedInstance().testMode = true // テストモード

    return true
}

@import DTBiOSSDK;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // アプリケーションキーを設定する
    [[DTBAds sharedInstance] setAppKey: @"YOUR_APP_KEY"];

    // アドネットワーク設定
    DTBAdNetworkInfo *dtbAdNetworkInfo = [[DTBAdNetworkInfo alloc] initWithNetworkName: DTBADNETWORK_AD_GENERATION];
    [[DTBAds sharedInstance] setAdNetworkInfo: dtbAdNetworkInfo];

    // Ad Generationのアドサーバーを利用するために下記を追加してください
    [DTBAds sharedInstance].mraidPolicy = CUSTOM_MRAID;
    [DTBAds sharedInstance].mraidCustomVersions = @ [@"1.0", @"2.0"];

    // 位置情報を収集して活用する場合は下記を追加してください
    // [[DTBAds sharedInstance] setUseGeoLocation:YES];

    // デバッグ時はログレベル変更とテストモードを有効化してください※アプリリリース時は呼び出さないでください
    // [[DTBAds sharedInstance] setLogLevel:DTBLogLevelAll]; // ログレベル
    // [[DTBAds sharedInstance] setTestMode:YES]; // テストモード

    return YES;
}

DTB SDKの初期設定は必ずメインスレッド上で行う必要があります。

バナー広告

importとdelegate protocolの定義

import DTBiOSSDK
import ADG

class ViewController: UIViewController, DTBAdCallback, ADGManagerViewControllerDelegate

@import DTBiOSSDK;
@import ADG;

@interface ViewController () <DTBAdCallback, ADGManagerViewControllerDelegate>

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

// width,height,slotidの指定
var size = [DTBAdSize]()
size.append(DTBAdSize(bannerAdSizeWithWidth: 320, height: 50, andSlotUUID: "your_dtb_slot_id"))
let adLoader = DTBAdLoader.init()
adLoader.setAdSizes(size)
adLoader.loadAd(self)

// width,height,slotidの指定
DTBAdSize *size = [[DTBAdSize alloc] initBannerAdSizeWithWidth:320 height:50 andSlotUUID:@"your_dtb_slot_id"];
DTBAdLoader *adLoader = [DTBAdLoader new];
[adLoader setSizes:size, nil];
[adLoader loadAd:self];

広告リクエスト結果処理

• DTBSDKが生成するbid情報（DTBAdResponse）の有効期間は10分となります。
• DTBAdResponseパラメーターの付与以外は通常のAd Genrationの広告リクエストと同様です。

// Amazon広告リクエスト成功時
func onSuccess(_ adResponse: DTBAdResponse!) {
    // Amazon広告リクエスト成功時は
    // DTBAdResponseのパラメーターを付与した上でAd Generationの広告のリクエストを行います。
    self.loadADG(adResponse)
}

// Amazon広告リクエスト失敗時
func onFailure(_ error: DTBAdError) {
    // Amazon広告リクエスト失敗時は
    // DTBAdResponseのパラメーターを付与せずAd Generationの広告のリクエストを行います。
    self.loadADG(nil)
}

func loadADG(_ adResponse: DTBAdResponse?) {
    // ADGManagerViewControllerクラスのインスタンスとしてself.adgが定義されているものとする
    // self.adViewが広告表示領域であるとする。
    adg = ADGManagerViewController(locationID: "YOUR_ADGENERATION_AD_ID", adType: .adType_Sp, rootViewController: self)
    adg?.addAdContainerView(self.adView) // 広告Viewを配置するViewを指定

    // Amazon広告パラメーターのセット
    if let param = adResponse {
        adg?.addHeaderBiddingParams(withAmznAdResponse: param)
    }

    adg?.delegate = self
    adg?.loadRequest() // Ad Generation広告リクエスト
}

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
}

deinit {
    // インスタンスの破棄
    adg = nil
}

func adgManagerViewControllerReceiveAd(_ adgManagerViewController: ADGManagerViewController) {
    print("Received an ad.")
}

func adgManagerViewControllerFailed(toReceiveAd adgManagerViewController: ADGManagerViewController, code: kADGErrorCode) {
    print("Failed to receive an ad.")
    // エラー時のリトライは特段の理由がない限り必ず記述するようにしてください。
    switch code {
    case .adgErrorCodeNeedConnection, // ネットワーク不通
        .adgErrorCodeExceedLimit, // エラー多発
        .adgErrorCodeNoAd: // 広告レスポンスなし
        break
    default:
        adgManagerViewController.loadRequest()
    }
}

func adgManagerViewControllerDidTapAd(_ adgManagerViewController: ADGManagerViewController) {
    print("Did tap ad.")
}

// Amazon広告リクエスト成功時
- (void)onSuccess: (DTBAdResponse *)adResponse {
    // Amazon広告リクエスト成功時は
    // DTBAdResponseのパラメーターを付与した上でAd Generationの広告のリクエストを行います。
    [self loadAdg:adResponse];
}

// Amazon広告リクエスト失敗時
- (void)onFailure: (DTBAdError)error {
    // Amazon広告リクエスト失敗時は
    // DTBAdResponseのパラメーターを付与せずAd Generationの広告のリクエストを行います。
    [self loadAdg:nil];
}

- (void)loadAdg: (DTBAdResponse *)adResponse {
    // ADGManagerViewControllerクラスのインスタンスとしてself.adgが定義されているものとする
    // self.adViewが広告表示領域であるとする。
    self.adg = [[ADGManagerViewController alloc] initWithLocationID:@"YOUR_ADGENERATION_AD_ID"
                                                             adType:kADG_AdType_Sp
                                                 rootViewController:self];
    [self.adg addAdContainerView:self.adView]; // 広告Viewを配置するViewを指定

    // Amazon広告パラメーターのセット
    if (adResponse) {
        [self.adg addHeaderBiddingParamsWithAmznAdResponse:adResponse];
    }

    self.adg.delegate = self;
    [self.adg loadRequest]; // Ad Generation広告リクエスト
}

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
}

- (void)dealloc {
    // インスタンスの破棄
    self.adg.delegate = nil;
    self.adg = nil;
}

- (void)ADGManagerViewControllerReceiveAd:(ADGManagerViewController *)adgManagerViewController {
    NSLog(@"Received an ad.");
}

- (void)ADGManagerViewControllerFailedToReceiveAd:(ADGManagerViewController *)adgManagerViewController
                                             code:(kADGErrorCode)code {
    NSLog(@"Failed to receive an ad.");
    // エラー時のリトライは特段の理由がない限り必ず記述するようにしてください。
    switch (code) {
        case kADGErrorCodeNeedConnection:   // ネットワーク不通
        case kADGErrorCodeExceedLimit:      // エラー多発
        case kADGErrorCodeNoAd:             // 広告レスポンスなし
            break;
        default:
            [adgManagerViewController loadRequest];
            break;
    }
}

- (void)ADGManagerViewControllerDidTapAd:(ADGManagerViewController *)adgManagerViewController{
    NSLog(@"Did tap ad.");
}

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

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

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

[adLoader setAutoRefresh:45]; // 45秒毎にリフレッシュを行う

• 自動更新を必ず停止してください。自動更新を停止する際の推奨場所はviewDidDisappearです。自動更新処理を不適切に使用してしまうと、インプレッション数に矛盾の可能性が発生します。

adLoader.stop()

[adLoader stop];

注意

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

DTBAdLoaderの破棄

• DTBAdLoaderインスタンスが不要になったタイミングでnilのセットをしてください。

adLoader = nil

self.adLoader = nil;

テストモード

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

DTBAds.sharedInstance().setLogLevel(DTBLogLevelAll)
DTBAds.sharedInstance().testMode = true

[[DTBAds sharedInstance] setLogLevel:DTBLogLevelAll];
[[DTBAds sharedInstance] setTestMode:YES];

注意

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

通信の検証

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

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