本頁面由 Cloud Translation API 翻譯而成。

出價轉接程式開發

本指南適用於需要建立出價轉接程式的廣告聯播網來參與 Google 中介服務內即時出價。如果發生以下情況：發布商，請參閱發布商中介服務操作說明。

出價轉接程式是整合作業的用戶端部分。轉接頭可讓廣告聯播網 SDK 與 Google Mobile Ads SDK 通訊載入您的出價工具放送的廣告。

轉接程式必須處理初始化、收集信號、載入廣告，以及傳遞廣告生命週期事件。本指南將逐步說明轉接頭的方式來處理這些作業

出價轉接程式的工作流程

初始化

要求/回應轉譯生命週期的詳細流程轉接器的設定檔，如下所示：

轉接程式會負責工作流程中的下列部分：

步驟 4-7：初始化轉接程式並回呼 Google Mobile Ads SDK
步驟 10-13：從廣告聯播網 SDK 收集要傳送至出價者參與即時出價請求，並轉交給 Google 行動服務廣告 SDK。
步驟 18-21：出價工具傳回得標出價時，您的出價工具回應載入完成後，請通知 Google Mobile Ads SDK 廣告載入的狀況
步驟 23 和後續機型：在廣告顯示時，通知 Google 行動廣告透過 SDK 追蹤曝光和點擊事件，以及其他發生的廣告事件廣告的放送生命週期期間

，瞭解如何調查及移除這項存取權。

實作出價轉接程式

如要建立 Google Mobile Ads SDK 的出價轉接程式，您必須擴充 RtbAdapter 抽象類別。後續章節說明 RtbAdapter 中的每個抽象方法。

getSDKVersionInfo()

您應該會傳回 SDK 的版本。這個版本會傳送到出價工具做為 OpenRTB 請求的一部分

這個方法需要您傳回 VersionInfo。以下範例說明建議將 SDK 的字串版本轉換為 VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

您應該會回傳轉接器的版本。這個版本會傳送到出價工具做為 OpenRTB 請求的一部分

Google 的開放原始碼和版本管理轉接器使用 4 位數轉接器版本架構，但 VersionInfo 僅允許 3 個數字。為解決這個問題，建議合併最後兩位數新增至修補程式版本，如下所示

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

逾時：30 秒

initialize() 方法是在轉接器中呼叫的第一個方法。是每個工作階段只會呼叫一次這個方法會提供 MediationConfiguration 物件，代表完整的此應用程式中已為您的廣告聯播網設定的刊登位置；你可以循環播放剖析每個刊登位置的憑證並將相關資料傳送至 SDK 進行初始化。

SDK 初始化並準備好接收廣告請求後，請叫用 InitializationCompleteCallback 的 onInitializationSucceeded() 方法。這個回呼會轉給應用程式發布者，讓他們知道即可開始載入廣告

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

逾時：1 秒

每次發布商請求廣告時，新的 RtbAdapter 例項就會並呼叫 collectSignals() 方法這是 RtbAdapter將會用於廣告請求、回應和廣告顯示生命週期collectSignals() 方法可讓您轉接程式，提供要透過裝置傳送給出價工具的信號 OpenRTB 要求。

已於背景執行緒呼叫 collectSignals()。 Google Mobile Ads SDK 同時要求所有轉接程式的信號參與出價的競價請尊重他人，並限制對 UI 執行緒的呼叫這段期間內。轉接程式或 SDK 需要收集的任何大量資料信號應在 initialize() 方法中完成並快取。

信號準備就緒後，請使用以下項目呼叫 onSuccess() 回呼：經過編碼的信號

以下是實作範例：

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

如果轉接程式無法收集信號，請呼叫 signalCallbacks.onFailure() 並附上說明發生錯誤的字串。

導入廣告載入方法

逾時：10 秒

如果您的出價工具傳回得標出價，Google Mobile Ads SDK 呼叫轉接程式以載入勝出的廣告，並傳送出價工具傳回您的 SDK 需要載入該廣告。

實際呼叫的載入方式會因廣告而異格式如下：

廣告格式	載入方法
橫幅	`loadBannerAd()`
插頁式廣告	`loadInterstitialAd()`
獎勵廣告	`loadRewardedAd()`

針對轉接程式支援的廣告格式導入這些方法。

系統會在使用者介面的執行緒上呼叫載入方法，和轉接程式來自您提供的信號。這個方法提供下列資料：參數：

MediationAdConfiguration，其中包含 SDK 需要的參數為得標出價載入廣告，例如出價回應和任何憑證也就是在 AdMob UI 中設定的發布商。
用來通知 Google Mobile Ads SDK 的 MediationAdLoadCallback 物件載入成功或失敗時。

SDK 載入廣告後，請呼叫 mediationAdLoadCallback.onSuccess()。在事件廣告載入失敗，請呼叫 mediationAdLoadCallback.onFailure() 並帶有說明發生的錯誤。

mediationAdLoadCallback.onSuccess() 方法需要您傳入是「廣告」物件Google 行動服務定義的介面廣告 SDK。這些廣告介面會要求您提供廣告的相關資訊。

MediationAdConfiguration還有getWatermark() 方法來傳回代表 PNG 圖片的 Base64 編碼字串。這張圖片都位於廣告上的透明重疊元素中。如需如何顯示浮水印的其他指引，請與 Google 聯絡。內含所顯示廣告的中繼資料，供發布商判斷顯示廣告的來源。

如果是橫幅，系統會要求你提供橫幅廣告檢視畫面。如果是插頁式廣告和獎勵廣告，您需要導入 show() 方法，以在安排在之後的時間點我們建議的最佳做法是讓課程達成以下目標：廣告載入作業也要負責導入這些廣告方法。

以下是 loadBannerAd() 的實作範例。注意事項轉接程式的實作方式將與之前的轉接程式不同並與不同的 SDK 整合

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

Relay 廣告展示生命週期事件

轉接程式的最終責任是通知 Google Mobile Ads SDK 任何展示生命週期事件，因此這些事件就會轉送至內容。發布商預期這些回呼會在任何特定時間發出放送廣告的廣告聯播網中回呼函式會盡可能妥當，在適當時機讓 Google Mobile Ads SDK 可以將其轉寄給發布商。

轉接器應視情況叫用下列事件 (如適用)：

所有格式通用
方法	致電時間
`reportAdClicked()`	廣告獲得點擊。
`reportAdImpression()`	廣告顯示了一次曝光。
`onAdOpened()`	廣告以全螢幕模式顯示。
`onAdClosed()`	已關閉全螢幕檢視。
`onAdLeftApplication()`	廣告造成使用者離開應用程式。
獎勵廣告
`onRewarded()`	使用者會收到獎勵，
影片回呼 (獎勵和原生廣告)
`onVideoStarted()`	廣告的影片已開始播放。
`onVideoCompleted()`	廣告影片播完。

轉接器獲得 MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> 物件傳回 mediationAdLoadCallback.onSuccess()。轉接器預期會保存在這個物件上，並用來叫用呈現事件所有費用。

這些事件通常是由您廣告聯播網的 SDK 所驅動。轉接程式的角色只是將廣告聯播網 SDK 的回呼對應至 Google Mobile Ads SDK。

以下範例將展示如何將回呼從 Google Mobile Ads SDK 的 SDK 廣告接聽程式：

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

原生廣告曝光追蹤的必要素材資源

Google Mobile Ads SDK 會在看到廣告。如果廣告聯播網 SDK 需要顯示特定素材資源為了顯示有效曝光，您的出價工具可以指出原生素材資源。接著，Google Mobile Ads SDK 會必要的原生素材資源在記錄曝光前顯示。

請參閱原生必要素材資源說明文件進一步瞭解如何在出價中指定額外素材資源回應。

顯示廣告錯誤

如果想用全螢幕格式 (如插頁式廣告和獎勵廣告) 的成效，就必須使用 MediationInterstitialAd 或MediationRewardedAd 。，Google Mobile Ads SDK 才會要求您的轉接程式顯示廣告。

Google Mobile Ads SDK 預期如果轉接程式成功載入廣告，廣告就可以放送了。也就是說每個節目呼叫都應產生一次曝光

不過，有時候可能無法顯示廣告。如果發生以下情況：就無法顯示廣告，請呼叫 onAdFailedToShow() 取消曝光的回呼。

下表說明展示回呼對全螢幕廣告格式的曝光記錄有何影響：

回撥電話	結果
onAdOpened()	`Impression recorded`
onAdFailedToShow()	`Impression failure¹`
數秒內均不含上述內容	`Impression recorded`

¹ 失敗曝光後，廣告聯播網不會收取曝光費用，但會會影響可計費事件費率調整項。請參閱出價要求信號可能不準確或不適當

以下模擬範例示範廣告的載入/顯示生命週期顯示通話可能會失敗。

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}