开始使用

第一步是将 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:22.0.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 和广告串相关值，以便频次上限和竞争排除功能正常运行。

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