開始使用 Samsung Tizen

如要查看使用 PAL 生成隨機值的範例應用程式，請從 GitHub 下載 CTV Samsung Tizen 範例。

本指南說明如何將 PAL SDK 併入 Samsung Tizen 應用程式、要求 Nonce，以及註冊廣告曝光。

必要條件

開始閱讀本指南前，請先建立基本的 Tizen 應用程式。您可以使用 Tizen IDE 設定應用程式。如需更多資訊，請觀看這部Tizen 入門影片。

產生 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 檔案來產生隨機碼。這個步驟包括 PAL 工作流程，也就是建立 NonceLoader、建立 NonceRequest，然後使用 NonceLoader.loadNonceManager() 要求隨機值。

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();
  });

  // The default value for the `allowStorage` parameter is false. You must
  // set this value to true to let PAL determine whether limited ads applies
  // based on the TCF data. You can optionlly use the `forceLimitedAds`
  // parameter to enable limited ads regardless of the TCF data.
  const consentSettings = new goog.pal.ConsentSettings();
  consentSettings.allowStorage = true;

  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();
});

將隨機碼附加至廣告請求

如要使用產生的隨機碼，請先在廣告代碼中附加 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 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);
        
      })

追蹤播放事件

最後，您需要為播放器導入各種事件處理常式。為了測試，您可以將這些事件附加至按鈕點擊事件，但在實際導入時，這些事件會由適當的播放器事件觸發：

/**
 * 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 的請求。

設定第三方廣告伺服器，在伺服器向 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 提高營利。