开始使用

第一步是将 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 的示例应用，请从 GitHub 下载 Android 示例。

您首先需要导入 PAL SDK，创建一些私有属性来存储 NonceLoader 和 NonceManager，然后初始化 NonceLoader。

除非应用有多个页面或等效结构，否则我们建议您仅为应用中的每个用户会话创建一个 NonceLoader 类实例。这样一来，在网页的生命周期内或用户在应用中的会话期间，页面 Correlator (&correlator) 保持不变。您仍然可以控制数据流 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。出于测试目的，您可以在点击测试应用中的按钮时调用此函数。

此函数以异步方式触发 Nonce 生成操作，因此您需要实现 AsyncTask 来处理 Nonce 请求成功或失败：

public void generateNonceForAdRequest() {
  Set supportedApiFrameWorksSet = new HashSet();
  supportedApiFrameWorksSet.add(2);
  supportedApiFrameWorksSet.add(7);
  supportedApiFrameWorksSet.add(9);

  NonceRequest nonceRequest = NonceRequest.builder()
      .descriptionURL("https://example.com/content1")
      .iconsSupported(true)
      .omidVersion("1.0.0")
      .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(true)
      .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 参数和 Nonce 值。

注意 ：如果您之前使用 paln 参数提供了 Nonce，我们强烈建议您迁移到 givn 并停止发送 paln。如果这两个参数都包括在内，则关于使用哪个 Nonce 的行为无法确定。

/**
 * 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，从而实现更高的创收效果。

注意 ：如果您使用多个第三方解决方案（例如，第三方 SSAI 服务器调用了其他第三方广告服务器），您需要确保将 PAL SDK 的加密 Nonce 转发给每个第三方。

配置您的第三方广告服务器，以在服务器向 Ad Manager 发出的请求中添加 Nonce。以下是在第三方广告服务器内配置的广告代码的示例：

'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 查询参数。如需详细了解如何实现此操作，请参阅第三方广告服务器的文档。