開始使用

第一步是在應用程式中加入 Android PAL SDK。

新增 Android PAL SDK 做為程式庫

自 18.0.0 版起,PAL SDK 是由 Google 的 Maven 存放區代管 如何加入應用程式:

app/build.gradle

...
dependencies {
    implementation 'com.google.android.gms:play-services-pal:20.2.0'
    ...
}

或者,您可以從 Google 的 Maven 存放區下載 PAL SDK,然後手動新增至應用程式中。

產生 Nonce

一個「nonce」是 PAL 使用 NonceLoader 產生的單一加密字串。 PAL SDK 規定每個新的串流請求都必須搭配新的 產生的 Nonce不過,您可以在同一個區段中,為多個廣告請求重複使用 Nonce 同一個串流。如要使用 PAL SDK 產生 Nonce,請變更 MyActivity.java。如果想查看使用 PAL 產生 Nonce 的範例應用程式, 下載 Android 範例 GitHub

您必須先匯入 PAL SDK,請建立一些要儲存的私有屬性 NonceLoaderNonceManager,然後初始化 NonceLoader。

建議您只為 的 NonceLoader 類別建立一個執行個體 除非應用程式有多個頁面或同等項目,否則每個使用者工作階段 建構項目這樣一來,網頁的網頁關聯元件 (&correlator) 或使用者在應用程式中的工作階段,就不會在整個生命週期中有所變動。您仍可控制串流關聯元件 (&scor),並應為每個新的串流重設一次。

同一個串流的所有廣告請求應共用相同的 NonceLoader 和 將 Correlator 值用於展示頻率上限和競爭排除 這些功能的正常運作

import android.app.Activity;
import android.os.Bundle;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;

import java.util.HashSet;
import java.util.Set;

public class MainActivity extends Activity {
...
  private NonceLoader nonceLoader;
  private NonceManager nonceManager = null;
  private ConsentSettings consentSettings;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // The default value for allowStorage() is false, but can be
    // changed once the appropriate consent has been gathered. The
    // getConsentToStorage() method is a placeholder for the publisher's own
    // method of obtaining user consent, either by integrating with a CMP or
    // based on other methods the publisher chooses to handle storage consent.

    boolean isConsentToStorage = getConsentToStorage();

    videoView = findViewById(R.id.video_view);
    videoView.setOnTouchListener(this::onVideoViewTouch);

    consentSettings = ConsentSettings.builder()
            .allowStorage(isConsentToStorage)
            .build();

    // It is important to instantiate the NonceLoader as early as possible to
    // allow it to initialize and preload data for a faster experience when
    // loading the NonceManager. A new NonceLoader will need to be instantiated
    //if the ConsentSettings change for the user.
    nonceLoader = new NonceLoader(this, consentSettings);
    ...
  }

接下來,請建立函式來觸發 Nonce 產生。只需要一個 Nonce 。為了測試,您可以在點選測試應用程式中的按鈕時呼叫這個函式。此處設定的 NonceRequest 參數是範例參數。請將 根據您的應用程式特性建立預測參數

這個函式會以非同步方式觸發 Nonce 產生,因此您必須 實作 AsyncTask 來處理 Nonce 要求成功或失敗:

public void generateNonceForAdRequest() {
  Set supportedApiFrameWorksSet = new HashSet();
  // The values 2, 7, and 9 correspond to player support for VPAID 2.0,
  // OMID 1.0, and SIMID 1.1.
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest = NonceRequest.builder()
      .descriptionURL("https://example.com/content1")
      .iconsSupported(true)
      .omidPartnerVersion("6.2.1")
      .omidPartnerName("Example Publisher")
      .playerType("ExamplePlayerType")
      .playerVersion("1.0.0")
      .ppid("testPpid")
      .sessionId("Sample SID")
      .supportedApiFrameworks(supportedApiFrameWorksSet)
      .videoPlayerHeight(480)
      .videoPlayerWidth(640)
      .willAdAutoPlay(true)
      .willAdPlayMuted(false)
      .build();
  NonceCallbackImpl callback = new NonceCallbackImpl();
  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(callback)
      .addOnFailureListener(callback);
}

private class NonceCallbackImpl implements OnSuccessListener<NonceManager>, OnFailureListener {
  @Override
  public void onSuccess(NonceManager manager) {
    nonceManager = manager;
    String nonceString = manager.getNonce();
    Log.i("PALSample", "Generated nonce: " + nonceString);
    // from here you would trigger your ad request and move on to initialize content
  }

  @Override
  public void onFailure(Exception error) {
    Log.e("PALSample", "Nonce generation failed: " + error.getMessage());
  }
}

建立 Nonce 管理員後,您隨時可以使用 nonceManager.getNonce() 擷取 Nonce。

將 Nonce 附加至廣告請求

如要使用產生的 Nonce,請以 givn 參數附加廣告代碼, 再提出廣告請求

/**
 * The ad tag for your ad request, for example:
 * https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external\
 * /single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1\
 * &cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
 *
 * For more sample ad tags, see
 * developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
 */
private static final String DEFAULT_AD_TAG = "Your ad tag";
...
@Override
public void onSuccess(NonceManager manager) {
  nonceManager = manager;
  String nonceString = manager.getNonce();
  Log.i("PALSample", "Generated nonce: " + nonceString);
  // Append the nonce to the ad tag URL.
  makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
}

追蹤播放事件

最後,您需要為播放器實作各種事件處理常式。適用對象 可以將這些點擊事件附加至按鈕點擊事件 則是由相關的玩家事件所觸發:

public void sendAdClick() {
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

public void sendPlaybackStart() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

public void sendPlaybackEnd() {
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}

public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendTouch(e);
  }
}

以下是實作中呼叫每個函式的時機:

  • sendPlaybackStart():影片播放工作階段開始的時間
  • sendPlaybackEnd():影片播放工作階段結束時
  • sendAdClick():每次觀眾點按廣告時
  • sendTouch():每次與播放器互動時

(選用) 透過第三方廣告伺服器傳送 Google Ad Manager 信號

設定第三方廣告伺服器,以便與 Google Ad Manager 搭配使用時,請參閱 傳送至伺服器的說明文件,擷取及轉送每則廣告中的 Nonce 值 請求。提供的示例為含有 Nonce 參數的廣告請求網址 包含。Nonce 參數會從 PAL SDK 傳播,並經由 中介服務伺服器及 Ad Manager 提供更優異的營利成效

設定第三方廣告伺服器,將 Nonce 加入伺服器的 向 Ad Manager 發出請求以下是 第三方廣告伺服器:

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

詳情請參閱 Google Ad Manager 伺服器端導入指南

Ad Manager 會尋找 givn= 來識別 Nonce 值。第三方廣告 必須支援自己的某些巨集,例如 %%custom_key_for_google_nonce%%,並替換成 Nonce 查詢參數 您提供的虛擬機器進一步瞭解如何完成這項作業 相關資訊。