此页面由 Cloud Translation API 翻译。

开始使用

借助 PAL，您可以在广告请求中以及广告播放期间发送 Google 广告信号。

本指南介绍了如何将 Android PAL SDK 添加到您的应用中。如需查看使用 PAL 生成随机数的示例应用，请从 GitHub 下载 Android 示例。

将 Android PAL SDK 添加为库

自版本 18.0.0 起，PAL SDK 托管在 Google 的 Maven 制品库中，可按如下方式添加到您的应用：

implementation 'com.google.android.gms:play-services-pal:22.1.0'build.gradle

或者，您也可以从 Google 的 Maven 制品库下载 PAL SDK，然后手动将其添加到应用中。

生成 nonce

nonce 是 PAL 使用 NonceLoader 类生成的单个加密字符串。PAL 要求每个流请求都附带一个唯一的一次性随机数。不过，您可以在同一视频流中为多个广告请求重复使用随机数。如需使用 PAL SDK 生成随机数，请进行以下更改以导入和设置 PAL，并创建一个用于生成随机数的函数：

通过执行以下操作来导入和设置 PAL：

导入 PAL 类：

import com.google.ads.interactivemedia.pal.ConsentSettings;
import com.google.ads.interactivemedia.pal.NonceLoader;
import com.google.ads.interactivemedia.pal.NonceManager;
import com.google.ads.interactivemedia.pal.NonceRequest;
import com.google.android.gms.tasks.OnFailureListener;
import com.google.android.gms.tasks.OnSuccessListener;
import java.util.HashSet;
import java.util.Set;
MainActivity.java

创建私有变量以存储 NonceLoader 和 NonceManager 实例：

private NonceLoader nonceLoader;
private NonceManager nonceManager;MainActivity.java

在 onCreate 方法中使用 ConsentSettings 实例初始化 NonceLoader 实例：

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  // 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 isStorageAllowed = getConsentToStorage();

  ConsentSettings consentSettings =
      ConsentSettings.builder().allowStorage(isStorageAllowed).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);

  adClickButton = findViewById(R.id.send_click_button);

  logView = findViewById(R.id.log_view);
  logView.setMovementMethod(new ScrollingMovementMethod());
}
MainActivity.java

在应用中，为每个用户会话创建一个 NonceLoader 类的实例。如果您的应用有多个页面或等效的结构，请为每个页面或等效的结构创建一个新的 NonceLoader 实例。通过使用同一 NonceLoader 实例，您可以使网页相关器 &correlator 在网页或用户在应用中的会话的整个生命周期内保持不变。您仍然可以控制流相关器 &scor，必须通过生成新的随机数来为每个新流重置该相关器。

同一视频流的所有广告请求必须共享相同的 NonceLoader 实例和视频流相关性标识符值，才能实现频次上限和竞争排除功能。

生成 nonce：

public void generateNonceForAdRequest(View view) {
  logMessage("Generate Nonce Request");
  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();

  nonceLoader
      .loadNonceManager(nonceRequest)
      .addOnSuccessListener(
          new OnSuccessListener<NonceManager>() {
            @Override
            public void onSuccess(NonceManager manager) {
              nonceManager = manager;
              String nonceString = manager.getNonce();
              logMessage("Nonce generated");
              logMessage(nonceString.substring(0, 20) + "...");
              Log.i(LOG_TAG, "Generated nonce: " + nonceString);

              // From here you would trigger your ad request and move on to initialize content.
              exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);

              adClickButton.setEnabled(true);
            }
          })
      .addOnFailureListener(
          new OnFailureListener() {
            @Override
            public void onFailure(Exception error) {
              logMessage("Nonce generation failed");
              Log.e(LOG_TAG, "Nonce generation failed: " + error.getMessage());
            }
          });
}
MainActivity.java

您只需为单个视频流播放中的所有广告请求提供一个随机数。出于测试目的，请在点击测试应用中的按钮时调用此函数。本指南中设置的 NonceRequest 参数是示例参数。根据您自己的应用特征设置参数。

此函数会异步生成随机数。您必须处理随机数请求的成功和失败情况。在 nonce 管理器可用后，请先使用 nonceManager.getNonce() 方法检索 nonce，然后再发出广告请求。

将随机数附加到广告请求

如需使用生成的随机数，请在发出广告请求之前，在广告代码中附加 givn 参数和随机数值：

// From here you would trigger your ad request and move on to initialize content.
exampleMakeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);MainActivity.java

跟踪播放事件

如需跟踪播放事件，您必须设置事件处理程序以向 Google 发送广告信号：

// Triggered when a user clicks-through on an ad which was requested using a PAL nonce.
public void sendAdClick(View view) {
  logMessage("Ad click sent");
  if (nonceManager != null) {
    nonceManager.sendAdClick();
  }
}

// In a typical PAL app, this is called when a user touch or click is detected,
// on the ad other than an ad click-through.
public void onVideoViewTouch(MotionEvent e) {
  if (nonceManager != null) {
    nonceManager.sendAdTouch(e);
  }
}

// In a typical PAL app, this is called when a content playback session starts.
public void sendPlaybackStart() {
  logMessage("Playback start");
  if (nonceManager != null) {
    nonceManager.sendPlaybackStart();
  }
}

// In a typical PAL app, this is called when a content playback session ends.
public void sendPlaybackEnd() {
  logMessage("Playback end");
  if (nonceManager != null) {
    nonceManager.sendPlaybackEnd();
  }
}
MainActivity.java

以下是您在实现中调用每个函数的时间：

sendPlaybackStart()：视频播放会话开始时
sendPlaybackEnd()：当视频播放会话结束时
sendAdClick()：观看者每次点击广告
sendTouch()：在每次与播放器的触摸互动时

出于测试目的，请将事件处理脚本方法附加到按钮点击事件。在生产实现中，设置应用以使播放器事件调用事件处理脚本方法。

（可选）通过第三方广告服务器发送 Google Ad Manager 信号

将第三方广告服务器设置为与 Google Ad Manager 搭配使用时，请参阅服务器的文档，以捕获并转发每个广告请求中的随机数。提供的示例是包含随机数参数的广告请求网址。nonce 参数从 PAL SDK 传播到您的中介服务器，然后再传播到 Ad Manager，从而实现更好的创收效果。

将第三方广告服务器配置为在向 Ad Manager 发出的服务器请求中包含随机数。以下是第三方广告服务器内配置的广告代码示例：

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

如需了解详情，请参阅 Google Ad Manager 服务器端实现指南。

Ad Manager 会查找 givn= 以识别随机数的值。第三方广告服务器需要支持自己的某个宏（例如 %%custom_key_for_google_nonce%%），并将其替换为您在上一步中提供的 nonce 查询参数。如需详细了解如何实现此目的，请参阅第三方广告服务器的文档。