เริ่มต้นใช้งาน Samsung Tizen

หากต้องการดูแอปตัวอย่างที่ใช้ PAL เพื่อสร้าง Nonce ให้ดาวน์โหลดตัวอย่าง CTV Samsung Tizen จาก GitHub

คู่มือนี้จะรวม PAL SDK เข้ากับแอปพลิเคชัน Samsung Tizen, ขอ ค่า Nonce และลงทะเบียนการแสดงโฆษณา

ข้อกำหนดเบื้องต้น

ก่อนเริ่มคู่มือนี้ คุณต้องสร้างแอป Tizen พื้นฐานก่อน โดยใช้ Tizen IDE เพื่อตั้งค่าแอป ดูข้อมูลเพิ่มเติมได้ในวิดีโอการเริ่มต้นใช้งาน Tizen

สร้าง Nonce

"Nonce" คือสตริงที่เข้ารหัสรายการเดียวซึ่ง PAL สร้างขึ้นโดยใช้ NonceLoader PAL SDK กำหนดให้คำขอสตรีมใหม่แต่ละรายการต้องมาพร้อมกับ Nonce ที่สร้างขึ้นใหม่ อย่างไรก็ตาม สามารถนำ Nonce ไปใช้ซ้ำกับคำขอโฆษณาหลายรายการภายในสตรีมเดียวกันได้

สร้างไฟล์ HTML สำหรับแอปของคุณ โดยใส่ทรัพยากร Dependency webapis.js ในไฟล์ HTML PAL ต้องใช้ทรัพยากร Dependency นี้จึงจะทำงานได้ ดูข้อมูลเพิ่มเติมได้ที่ เอกสารประกอบเกี่ยวกับ Samsung WebApi

รวมทรัพยากร Dependency สำหรับ CTV PAL SDK ไว้ในไฟล์ index.html โหลดแท็กสคริปต์ตามแท็กสคริปต์สำหรับ 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 ขั้นตอนนี้รวมถึงเวิร์กโฟลว์ 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();
  });

  // 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 กับคำขอโฆษณา

หากต้องการใช้ Nonce ที่สร้างขึ้น ให้ต่อท้ายแท็กโฆษณาด้วยพารามิเตอร์ givn และค่า 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 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

กำหนดค่าเซิร์ฟเวอร์โฆษณาบุคคลที่สามให้รวม Nonce ไว้ในคำขอของเซิร์ฟเวอร์ที่ส่งไปยัง Ad Manager ต่อไปนี้เป็นตัวอย่างแท็กโฆษณาที่กำหนดค่าไว้ภายในเซิร์ฟเวอร์โฆษณาบุคคลที่สาม

'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 ที่คุณระบุในขั้นตอนก่อนหน้า ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการนี้ได้ในเอกสารประกอบของเซิร์ฟเวอร์โฆษณาของบุคคลที่สาม

เท่านี้ก็เรียบร้อย ตอนนี้คุณควรมีพารามิเตอร์ Nonce ที่ส่งต่อจาก PAL SDK ผ่านเซิร์ฟเวอร์ตัวกลาง แล้วไปยัง Google Ad Manager ซึ่งจะช่วยให้สร้างรายได้ได้ดีขึ้นผ่าน Google Ad Manager