導入獎勵廣告轉接程式

中介服務轉接程式會接收來自 Google Mobile Ads SDK 的訊息和要求，並與第三方聯播網 SDK 通訊，以便完成這些要求。

本指南適用於想要為 Google 行動廣告中介服務建構獎勵中介服務轉接程式的廣告聯播網。下方程式碼片段會用範例 SDK 進行示範。您可以在 Android中介服務專案中，找到專為這個範例 SDK 建構的轉接程式完整導入方式。本指南說明如何建構轉接程式。

定義轉接程式類別名稱和伺服器參數

透過 AdMob 中介服務平台中介服務的廣告聯播網，通常需要一或多個 ID 才能識別發布商。這些 ID 會以伺服器參數表示，在 AdMob UI 中設定中介服務的第三方廣告聯播網時，就會定義這些 ID。

在開發中介服務轉接程式之前，您必須將轉接程式類別名稱和其他必要參數提供給 Google，以取得廣告聯播網的存取權。

實作轉接程式類別

首先，實作轉接程式抽象類別：

...
import com.google.android.gms.ads.mediation.Adapter;
...

public class SampleAdapter extends Adapter {
 ...
}

這項變更可確保您的類別實作下列幾種方法。

回報版本號碼

轉接程式必須向 Google Mobile Ads SDK 回報轉接程式本身和第三方 SDK 版本。系統會使用 VersionInfo回報版本。

Google 的開放原始碼和版本化轉接程式採用 4 位數轉接程式版本配置，但 VersionInfo只接受 3 位數數字。如要解決這個問題，建議您將最後兩位數合併至修補程式版本，如下所示：

...
import com.google.android.gms.ads.VersionInfo;
...

public class SampleAdapter extends Adapter implements SampleRewardedAdListener {
  ...
  @Override
  public VersionInfo getVersionInfo() {
    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);
    }

    return new VersionInfo(0, 0, 0);
  }

  @Override
  public VersionInfo getSDKVersionInfo() {
    String versionString = SampleAdRequest.getSDKVersion();
    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);
    }

    return new VersionInfo(0, 0, 0);
  }
  ...
}

初始化轉接器

應用程式初始化 Google Mobile Ads SDK 後，透過 AdMob 使用者介面為應用程式設定的所有轉接程式都會叫用 initialize()。

List<MediationConfiguration> 引數可提供 AdMob UI 內為廣告聯播網設定的所有刊登位置相關資訊。請根據這些資訊初始化廣告聯播網 SDK。廣告聯播網 SDK 初始化後，請在 initialize() 呼叫中提供的 InitializationCompleteCallback 引數中叫用 onInitializationSucceeded() 或 onInitializationFailed() 方法，向 Google Mobile Ads SDK 回報初始化成功或失敗的結果。

...
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
import com.google.android.gms.ads.mediation.MediationConfiguration;
...

public class SampleAdapter extends Adapter {
  ...
  @Override
  public void initialize(
      Context context,
      InitializationCompleteCallback initializationCompleteCallback,
      List<MediationConfiguration> mediationConfigurations) {
    if (context == null) {
      initializationCompleteCallback.onInitializationFailed(
          "Initialization Failed: Context is null.");
      return;
    }

    // The Sample SDK doesn't have an initialization method, so this example
    // immediately reports a success callback.
    initializationCompleteCallback.onInitializationSucceeded();
  }
  ...
}

請求獎勵廣告

使用 loadRewardedAd() 方法請求獎勵廣告。保留 MediationAdLoadCallback 的參照，以便向 Google Mobile Ads SDK 回報成功或失敗的廣告載入。

MediationRewardedAdCallback 物件在叫用 onSuccess() 後即可使用，您稍後會使用此物件轉發其他廣告事件，例如點擊或獎勵。

...
import com.google.ads.mediation.sample.sdk.SampleAdRequest;
import com.google.ads.mediation.sample.sdk.SampleRewardedAd;
import com.google.ads.mediation.sample.sdk.SampleRewardedAdListener;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationRewardedAd;
import com.google.android.gms.ads.mediation.MediationRewardedAdCallback;
...

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...

  /**
   * A MediationAdLoadCallback that handles any callback when a Sample rewarded
   * ad finishes loading.
   */
  private MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> adLoadCallBack;

  /**
   * Represents a SampleRewardedAd.
   */
  private SampleRewardedAd sampleRewardedAd;

  /**
   * Used to forward rewarded video ad events to the Google Mobile Ads SDK..
   */
  private MediationRewardedAdCallback rewardedAdCallback;

  ...

  // Hold a reference to the MediationAdLoadCallback object to report ad load
  // events to the Google Mobile Ads SDK.
  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration mediationRewardedAdConfiguration,
      MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback>
          mediationAdLoadCallback) {
    adLoadCallBack = mediationAdLoadCallback;
    MediationRewardedAdConfiguration adConfiguration = mediationRewardedAdConfiguration;

    String adUnitId = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);

    sampleRewardedAd = new SampleRewardedAd(adUnitId);
    SampleAdRequest request = new SampleAdRequest();
    sampleRewardedAd.setListener(this);
    sampleRewardedAd.loadAd(request);
  }

  // Hold a reference to the MediationRewardedAdCallback object to report ad
  // lifecycle events to the Google Mobile Ads SDK.
  @Override
  public void onRewardedAdLoaded() {
    rewardedAdCallback = mediationAdLoadCallBack.onSuccess(this);
  }

  @Override
  public void onRewardedAdFailedToLoad(SampleErrorCode error) {
    mediationAdLoadCallBack.onFailure(error.toString());
  }
  ...
}

放送廣告

在 SDK 收到廣告載入成功的通知後，Google Mobile Ads SDK 隨時可以呼叫轉接程式的 showAd() 方法。轉接程式應會顯示獎勵廣告。如果廣告因任何原因無法顯示，請呼叫 onAdFailedToShow() 回呼。

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void showAd(Context context) {
    if (!(context instanceof Activity)) {
      rewardedAdCallback.onAdFailedToShow(
          "An activity context is required to show Sample rewarded ad.");
      return;
    }
    Activity activity = (Activity) context;

    if (!sampleRewardedAd.isAdAvailable()) {
      rewardedAdCallback.onAdFailedToShow("No ads to show.");
      return;
    }
    sampleRewardedAd.showAd(activity);
  }
  ...
}

向 Mobile Ads SDK 回報廣告事件

顯示廣告後，轉接程式應使用成功載入時提供的 MediationRewardedAdCallback 物件，根據 Google Mobile Ads SDK 回報合適的廣告生命週期事件。

一般來說，這些回呼是從廣告聯播網 SDK 觸發的回呼方法轉送。本範例會實作範例 SDK 回呼，並將其對應至 MediationRewardedAdCallback 中可用的回呼。

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void onAdRewarded(final String rewardType, final int amount) {
    RewardItem rewardItem =
        new RewardItem() {
          @Override
          public String getType() {
            return rewardType;
          }

          @Override
          public int getAmount() {
            return amount;
          }
        };
    rewardedAdCallback.onUserEarnedReward(rewardItem);
  }

  @Override
  public void onAdClicked() {
    rewardedAdCallback.reportAdClicked();
  }

  @Override
  public void onAdFullScreen() {
    rewardedAdCallback.onAdOpened();
    rewardedAdCallback.onVideoStart();
    rewardedAdCallback.reportAdImpression();
  }

  @Override
  public void onAdClosed() {
    rewardedAdCallback.onAdClosed();
  }

  @Override
  public void onAdCompleted() {
    rewardedAdCallback.onVideoComplete();
  }
  ...
}

應回報給 Google Mobile Ads SDK 的廣告事件如下：

廣告事件 說明
onAdOpened() 通知 Google Mobile Ads SDK 表示廣告將開啟。
onVideoStart() 通知 Google Mobile Ads SDK 有獎勵廣告已開始播放。
reportAdImpression() 通知 Google Mobile Ads SDK 表示廣告有一次曝光。
onVideoComplete() 通知 Google Mobile Ads SDK 獎勵廣告已播放完畢。
onUserEarnedReward() 通知 Google Mobile Ads SDK，指出使用者已獲得獎勵。
reportAdClicked() 通知 Google Mobile Ads SDK 已點擊廣告。
onAdClosed() 通知 Google Mobile Ads SDK 已關閉廣告。
onAdFailedToShow() 通知 Google Mobile Ads SDK 無法顯示廣告。