廣告聯播網中介服務轉接程式開發

本指南適用於需要建立中介服務轉接程式的廣告聯播網。發佈商請參閱發佈商中介服務說明。

廣告聯播網轉接程式是廣告聯播網與 Google 行動廣告中介服務之間的通訊層。

轉接程式會負責導入 MediationBannerAdapter 以支援橫幅廣告，並導入 MediationInterstitialAdapter 支援插頁式廣告。它也必須在適當時機叫用 MediationBannerListener 和 MediationInterstitialListener 中的回呼，向 Google 行動廣告中介服務通知這些事件 (也可將其轉寄給開發人員)。

廣告聯播網範例

本指南說明如何建立「廣告聯播網範例」的轉接程式。「廣告聯播網範例」包含下列類別，這些也是大部分廣告聯播網提供的類別：

class SampleAdView {
    public SampleAdView(Context context);
    public void setSize(SampleAdSize size);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void destroy();
}

class SampleAdSize {
    public SampleAdSize(int width, int height);
    public int getWidth();
    public int getHeight();
}

class SampleAdRequest {
    public SampleAdRequest();
    public void setKeywords(Set<String> keywords);
    public void setTestMode(boolean useTesting);
}

class SampleAdListener {
    public void onAdFetchSucceeded();
    public void onAdFetchFailed(SampleErrorCode code);
    public void onAdFullScreen();
    public void onAdClosed();
}

enum SampleErrorCode {
    UNKNOWN,
    BAD_REQUEST,
    NETWORK_ERROR,
    NO_INVENTORY
}

class SampleInterstitial {
    public SampleInterstitial(Context context);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void show();
    public void destroy();
}

如要進一步瞭解這些類別，請參閱完整的 SDK 實作。

導入橫幅廣告轉接程式

如要導入支援橫幅廣告的轉接程式，請建立可導入 MediationBannerAdapter 的類別。

public class SampleAdapter implements MediationBannerAdapter {
    @Override
    public void requestBannerAd(
            Context context,
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View getBannerView() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

開始深入探討 MediationBannerAdapter 實作前，先來探討伺服器參數、中介服務額外功能，以及這些值如何傳遞至轉接程式。

伺服器參數

廣告聯播網可能需要一些 ID 才能識別發布商。舉例來說，「廣告聯播網範例」只需要一個廣告單元。這些必要參數會透過 requestBannerAd() 內的 serverParameters 套件提供。在開發期間，您可以假設套裝組合已填入您需要的金鑰：

private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

@Override
public void requestBannerAd(
        Context context,
        MediationBannerListener listener,
        Bundle serverParameters,
        AdSize adSize,
        MediationAdRequest mediationAdRequest,
        Bundle mediationExtras) {
    String adUnit = serverParameters.getString(SAMPLE_AD_UNIT_KEY);
    ...
}

AdMob 會傳送問卷給您，詢問您需要哪些伺服器參數才能請求及放送廣告。AdMob 就會根據該輸入的資料，在 AdMob UI 中設定聯播網。以下螢幕截圖顯示 Millennial Media 需要 APID，InMobi 需要 App ID。

AdMob 會在執行個體化轉接程式時，使用這項資訊填入 serverParameters 組合。

若要進一步瞭解發布商如何設定中介服務廣告聯播網，請參閱這篇文章。

其他指定目標參數

MediationAdRequest 包含一些常見的指定目標資訊，可用於指定廣告目標，例如：

中介服務額外功能

如果您的廣告聯播網支援 MediationAdRequest 未提供的指定資訊，應用程式開發人員就可以明確將 mediationExtras 組合傳遞到您的聯播網。中介服務舉例說明如何傳遞中介服務額外功能。

為方便開發人員傳送這項資訊，您可以在轉接程式中提供套件建構工具類別。假設您的聯播網支援傳送收入值您可在設定收入的轉接程式中加入建構工具類別：

public static final class BundleBuilder {
    private int income;

    public BundleBuilder setIncome(int income) {
        this.income = income;
        return this;
    }

    public Bundle build() {
        Bundle bundle = new Bundle();
        bundle.putInt("income", income);
        return bundle;
    }
}

這個類別提供簡潔的 API，方便開發人員為您的網路產生套件：

Bundle sampleAdapterBundle =
        new SampleAdapter.BundleBuilder().setIncome(100000).build();

requestBannerAd()

瞭解伺服器參數和中介服務額外功能後，就可以使用這些參數建立 MediationBannerAdapter。

轉接程式例項化後，系統就會立即呼叫 requestBannerAd() 方法。請您在這裡建立廣告檢視畫面和提出橫幅廣告請求。

導入「廣告聯播網範例」的 requestBannerAd() 看起來會像這樣：

public class SampleAdMobAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";
    private SampleAdView sampleAdView;

    @Override
    public void requestBannerAd(
            Context context, // May be an application context.
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleAdView = new SampleAdView(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleAdView.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleAdView.setSize(
                new SampleAdSize(adSize.getWidth(),adSize.getHeight()));

        sampleAdView.setAdListener(
                new SampleBannerEventForwarder(listener, this));

        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleAdView.fetchAd(request);
    }
}

請勿假設結構定義參數是 Activity 類型。視發布商導入方式而定，Google 行動廣告中介服務可能會將應用程式內容轉送至轉接程式。如果轉接程式無法處理應用程式結構定義，建議利用錯誤代碼 AdRequest.ERROR_CODE_INVALID_REQUEST 叫用 onAdFailedToLoad()。

MediationBannerListener 回呼

請將提供給您的 MediationBannerListener 儲存在 requestBannerAd() 中，以便將廣告事件轉寄回 Google 行動廣告中介服務。每次回呼都必須在廣告生命週期的適當時機叫用：

方法 聯絡時機
onAdLoaded() 橫幅廣告請求成功。
onAdFailedToLoad() 橫幅廣告請求失敗。
onAdClicked() 橫幅已點擊。
onAdOpened() 橫幅正在顯示全螢幕檢視畫面。
onAdClosed() 使用者按下橫幅後返回應用程式。
onAdLeftApplication() 橫幅造成使用者離開應用程式。

「廣告聯播網範例」轉接程式會建立名為 SampleBannerEventForwarder 的類別來處理事件轉送：

public class SampleBannerEventForwarder extends SampleAdListener {
    private MediationBannerListener mediationListener;
    private SampleAdapter adapter;

    public SampleBannerEventForwarder(
            MediationBannerListener listener, SampleAdapter adapter) {
        this.mediationListener = listener;
        this.adapter = adapter;
    }

    @Override
    public void onAdFetchSucceeded() {
        mediationListener.onAdLoaded(adapter);
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch(errorCode) {
            case UNKNOWN:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mediationListener.onAdClicked(adapter);
        mediationListener.onAdOpened(adapter);
        mediationListener.onAdLeftApplication(adapter);
    }

    @Override
    public void onAdClosed() {
        mediationListener.onAdClosed(adapter);
    }
}

請注意「廣告聯播網範例」轉接程式如何在同一回呼中傳送 onAdClicked、onAdOpened 和 onAdLeftApplication。即使聯播網的回呼可能與 Google 行動廣告要求的回呼不完全一致，轉接程式還是有責任提供合理的對應。

getBannerView

呼叫 MediationBannerListener.onAdLoaded() 後，中介服務會呼叫 getBannerView() 以在畫面上顯示廣告聯播網的橫幅檢視畫面。只要傳回您在 requestBannerAd() 中建立的橫幅檢視畫面即可：

@Override
public View getBannerView() {
    return sampleAdView;
}

活動生命週期事件

如果應用程式開發人員通知事件的中介服務，中介服務會通知 onPause() 和 onResume() 活動事件的轉接程式。請針對橫幅廣告執行所有必要的暫停和恢復操作：

@Override
public void onPause() {
}

@Override
public void onResume() {
}

廣告聯播網範例不含暫停或恢復呼叫，因此提供了空白的導入方式。

即將刪除轉接程式時，中介服務會盡力呼叫 onDestroy()。請在此執行所有必要的清除作業：

@Override
public void onDestroy() {
    if (sampleAdView != null) {
        sampleAdView.destroy();
    }
}

智慧型橫幅廣告

Google Mobile Ads SDK 支援智慧型橫幅廣告大小，這種廣告大小是完整寬度和可變高度 (視裝置大小而定)。

為了正確取得智慧型橫幅廣告的廣告大小，轉接程式應使用 adSize.getWidthInPixels(context) 取得寬度和 adSize.getHeightInPixels(context) (而非 adSize.getHeight()) 以取得高度。然後除以裝置密度：

int widthInPixels = adSize.getWidthInPixels(context);
int heightInPixels = adSize.getHeightInPixels(context);
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
int widthInDp = Math.round(widthInPixels / displayMetrics.density);
int heightInDp = Math.round(heightInPixels / displayMetrics.density);

接著，您就可以在發出廣告請求時，使用 widthInDp 和 heightInDp 做為大小。

大功告成！您現在已有可用的橫幅廣告中介服務轉接程式！本文將說明 SampleAdapter 的完整導入方式，供您參考。

導入插頁式廣告轉接程式

插頁式廣告的轉接程式導入方式與橫幅廣告類似。如要導入支援插頁式廣告的轉接程式，請建立可導入 MediationInterstitialAdapter 的類別：

public class SampleAdapter implements MediationInterstitialAdapter {
    @Override
    public void requestInterstitialAd(
            Context context,
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View showInterstitial() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

如果您的轉接程式也支援橫幅廣告，則可使用相同的轉接程式類別來實作這兩個介面。

請先瞭解伺服器參數和中介服務額外功能，再開始實作 MediationInterstitialAdapter。

伺服器參數 (插頁式)

請參閱「橫幅廣告伺服器參數」一節。

其他指定參數 (插頁式)

請參閱「橫幅廣告其他指定目標參數」一節。

中介服務額外功能 (插頁式)

請參閱「橫幅廣告中介服務額外功能」一節。

requestInterstitialAd

轉接程式例項化後，系統就會立即呼叫 requestInterstitialAd() 方法。請您在這裡建立插頁式廣告請求及發出插頁式廣告請求。

導入「廣告聯播網範例」的 requestInterstitialAd() 看起來會像這樣：

public class SampleAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(
            Context context, // May be an application context.
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleInterstitial = new SampleInterstitial(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleInterstitial.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleInterstitial.setAdListener(
                new SampleInterstitialEventForwarder(listener, this));

        // Make an ad request.
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleInterstitial.fetchAd(request);
    }
}

請勿假設結構定義參數是 Activity 類型！Google 行動廣告中介服務會轉送應用程式開發人員傳遞的內容，系統可能會傳遞應用程式內容。如果轉接程式無法處理應用程式結構定義，建議利用錯誤代碼 AdRequest.ERROR_CODE_INVALID_REQUEST 叫用 onAdFailedToLoad。

Mediation 插頁式 Listener 回呼

請將提供給您的 MediationInterstitialListener 儲存在 requestInterstitialAd 中，以將廣告事件轉寄回 Google 行動廣告中介服務。每個回呼都必須在廣告生命週期中的適當時機叫用：

方法 聯絡時機
onAdLoaded 插頁式廣告請求成功。
onAdFailedToLoad 插頁式廣告請求失敗。
onAdOpened 目前顯示的是插頁。
onAdClosed 插頁式廣告已關閉。
onAdLeftApplication 插頁廣告造成使用者離開應用程式。

showInterstitial

呼叫 MediationInterstitialListener.onAdLoaded() 後，應等到呼叫 showInterstitial() 後再顯示插頁。應用程式開發人員會決定顯示插頁式廣告的時機，可能是請求請求後幾分鐘的時間。

showInterstitial() 的實作方式非常簡單。只要顯示您的插頁廣告物件即可：

@Override
public void showInterstitial() {
    sampleInterstitial.show();
}

活動生命週期事件 (插頁式)

請參閱「橫幅廣告活動生命週期事件」一節。

導入活動生命週期事件後，您的中介服務轉接程式即可開始處理插頁式廣告！本文將說明 SampleAdapter 的完整導入方式，供您參考。

常見問題

轉接程式僅支援橫幅廣告或插頁式廣告，但不支援兩者時，該怎麼辦？

如果您的轉接程式僅支援橫幅廣告，則只需實作 MediationBannerAdapter 介面。如果您的轉接程式僅支援插頁式廣告，則只需導入 MediationInterstitialAdapter 介面。