Samsung Tizen 使用入门

如需查看使用 PAL 生成 Nonce 的示例应用，请从 GitHub 下载联网电视 Samsung Tizen 示例。

本指南将 PAL SDK 集成到 Samsung Tizen 应用中，请求 Nonce 并注册广告展示次数。

前提条件

在开始学习本指南之前，您需要创建一个基本的 Tizen 应用。您可以使用 Tizen IDE 来设置应用。如需了解详情，请观看有关 Tizen 入门的视频。

生成 Nonce

“nonce”是 PAL 使用 NonceLoader 生成的单个加密字符串。PAL SDK 要求每个新的流请求都附带新生成的随机数。不过，在同一视频流中，随机数可能会重复用于多个广告请求。

为您的应用创建一个 HTML 文件。在 HTML 文件中添加 webapis.js 依赖项。PAL 需要此依赖项才能正常运行。如需了解详情，请参阅 Samsung WebApi 文档。

在 index.html 文件中添加 CTV PAL SDK 的依赖项。在 webapis.js 的脚本标记之后加载脚本标记。如需查看示例，请参阅以下 index.html 文件。

<!DOCTYPE html>
<html>
<head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
 <script src="$WEBAPIS/webapis/webapis.js"></script>
 <script src="//imasdk.googleapis.com/pal/sdkloader/pal_ctv.js"></script>
 <script src="app.js"></script>
</head>
<body>
  <header>
    <hgroup>
      <h1>Samsung Tizen app for PAL sdk</h1>
    </hgroup>
  </header>
  <div id="placeholder-video"></div>
</body>
</html>

PAL 垃圾信号需要某些 Tizen 权限才能正常运行。创建一个包含以下权限声明的 config.xml 文件：

• "http://tizen.org/privilege/internet"
• "http://tizen.org/privilege/system"
• "http://tizen.org/privilege/telephony"
• "http://tizen.org/privilege/tv.inputdevice"
• "http://developer.samsung.com/privilege/network.public"
• "http://developer.samsung.com/privilege/productinfo"

如需查看示例 config.xml 文件，请参阅以下代码段：

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns:tizen="http://tizen.org/ns/widgets" xmlns="http://www.w3.org/ns/widgets" id="http://yourdomain/BasicProject" version="1.0.0" viewmodes="maximized">
    <tizen:application id="PACKAGE_STRING.BasicProject" package="PACKAGE_STRING" required_version="2.3"/>
    <content src="index.html"/>
    <feature name="http://tizen.org/feature/screen.size.normal.1080.1920"/>
    <icon src="icon.png"/>
    <tizen:metadata key="http://tizen.org/metadata/app_ui_type/base_screen_resolution" value="extensive"/>
    <name>BasicProject</name>
    <tizen:privilege name="http://tizen.org/privilege/internet"/>
    <tizen:privilege name="http://tizen.org/privilege/system"/>
    <tizen:privilege name="http://tizen.org/privilege/telephony"/>
    <tizen:privilege name='http://tizen.org/privilege/tv.inputdevice'/>
    <tizen:privilege name="http://developer.samsung.com/privilege/network.public"/>
    <tizen:privilege name="http://developer.samsung.com/privilege/productinfo"/>
    <tizen:profile name="tv-samsung"/>
    <tizen:setting screen-orientation="landscape" context-menu="enable" background-support="disable" encryption="disable" install-location="auto" hwkey-event="enable"/>
    <access origin="*" subdomains="true"/>
</widget>

然后，创建一个 JavaScript 文件来生成 Nonce。此步骤包括创建 NonceLoader、创建 NonceRequest，然后使用 NonceLoader.loadNonceManager() 请求 Nonce 的 PAL 工作流程。

let videoElement;
let nonceLoader;
let managerPromise;
let nonceManager;
let playbackStarted = false;

/**
 * Initializes the PAL loader.
 */
function init() {
  const videoElement = document.getElementById('placeholder-video');
  videoElement.addEventListener('mousedown', onVideoTouch);
  videoElement.addEventListener('touchstart', onVideoTouch);
  videoElement.addEventListener('play', function() {
    if (!playbackStarted) {
      sendPlaybackStart();
      playbackStarted = true;
    }
  });
  videoElement.addEventListener('ended', sendPlaybackEnd);
  videoElement.addEventListener('error', function() {
    // Handle video error.
    sendPlaybackEnd();
  });

  // PAL automatically determines whether limited ads apply based on the TCF
  // data found on the page. You can optionally use the `forceLimitedAds`
  // parameter to manually enable limited ads regardless of the TCF data.
  const consentSettings = new goog.pal.ConsentSettings();

  nonceLoader = new goog.ctv.pal.NonceLoader(consentSettings);

  generateNonce();
}

/**
 * Generates a nonce with sample arguments and logs it to the console.
 *
 * The NonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
function generateNonce() {
  const request = new goog.ctv.pal.NonceRequest();
  request.adWillAutoPlay = true;
  request.adWillPlayMuted = false;
  request.continuousPlayback = false;
  request.descriptionUrl = 'https://example.com';
  request.iconsSupported = true;
  request.playerType = 'Sample Player Type';
  request.playerVersion = '1.0';
  request.ppid = 'Sample PPID';
  request.sessionId = 'Sample SID';
  // Player support for VPAID 2.0, OMID 1.0, and SIMID 1.1
  request.supportedApiFrameworks = '2,7,9';
  request.url = 'https://developers.google.com/ad-manager/pal/ctv';
  request.videoHeight = 480;
  request.videoWidth = 640;

  managerPromise = nonceLoader.loadNonceManager(request);
  managerPromise
      .then(function(manager) {
        nonceManager = manager;
      })
      .catch((error) => {
        // Handle nonce generating error.
      });
}

window.addEventListener("load", function(event) {
  init();
});

将 Nonce 附加到广告请求

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

注意： 如果您之前使用 paln 参数提供过 Nonce，我们强烈建议您迁移到 givn 并停止发送 paln。如果同时包含这两个参数，则无法确定使用哪个随机数。

  /**
   * 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 https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
   */
  const DEFAULT_AD_TAG = "Your ad tag";

  ...

  managerPromise = nonceLoader.loadNonceManager(request);
  managerPromise
      .then(function(manager) {
        nonceManager = manager;
        
        // Append the nonce to the ad tag URL.
        makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
        
      })

如果您要请求并呈现 Google 广告，则必须呈现AdChoices图标和叠加层。

跟踪播放事件

最后，您需要为播放器实现各种事件处理程序。出于测试目的，您可以将这些附加到按钮点击事件，但在实际实现中，这些将由相应的播放器事件触发：

/**
 * Informs PAL that an ad click has occurred. How this function is
 * called will vary depending on your ad implementation.
 */
function sendAdClick() {
  if (nonceManager) {
    nonceManager.sendAdClick();
  }
}

/**
 * Handles the user touching on the video element, passing it to PAL.
 * @param {!TouchEvent|!MouseEvent} touchEvent
 */
function onVideoTouch(touchEvent) {
  if (nonceManager) {
    nonceManager.sendAdTouch(touchEvent);
  }
}

/** Informs PAL that playback has started. */
function sendPlaybackStart() {
  if (nonceManager) {
    nonceManager.sendPlaybackStart();
  }
}

/** Informs PAL that playback has ended. */
function sendPlaybackEnd() {
  if (nonceManager) {
    nonceManager.sendPlaybackEnd();
  }
}

在您的实现中，应在视频播放会话开始后调用 sendPlaybackStart。当视频播放会话结束时，应调用 sendPlaybackEnd。每次观看者点击广告时，都应调用 sendAdClick。应在每次与播放器的触摸互动时调用 sendAdTouch。

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

配置第三方广告服务器向 Ad Manager 发送的请求。

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

配置第三方广告服务器，以在服务器向 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%%），并将其替换为您在上一步中提供的随机数查询参数。如需详细了解如何实现此目的，请参阅第三方广告服务器的文档。

大功告成！现在，您应该已将随机数参数从 PAL SDK 通过中介服务器传播到 Google Ad Manager。这样一来，您就可以通过 Google Ad Manager 更好地创收。