شروع به کار با Samsung Tizen

برای دیدن برنامه نمونه‌ای که از PAL برای تولید یک نانس استفاده می‌کند، نمونه CTV Samsung Tizen را از GitHub بارگیری کنید.

این راهنما کیت توسعه نرم‌افزار PAL را در برنامه Samsung Tizen ادغام می‌کند، یک عدد یک‌بارمصرف درخواست می‌کند، و ظهور آگهی را ثبت می‌کند.

پیش‌نیازها

قبل‌از شروع این راهنما، باید یک برنامه Tizen پایه ایجاد کنید. می‌توانید از Tizen IDE برای راه‌اندازی برنامه استفاده کنید. برای اطلاعات بیشتر، این ویدیو را درباره شروع کار با Tizen ببینید.

تولید یک نانس

«نانس» رشته‌ای رمزگذاری‌شده و یکتا است که PAL بااستفاده از NonceLoader تولید می‌کند. «کیت توسعه نرم‌افزار PAL» نیاز دارد که هر درخواست جاری‌سازی جدید با یک نانس جدیداً تولیدشده همراه باشد. بااین‌حال، از اعداد یک‌بارمصرف می‌توان برای چندین درخواست آگهی در جریان یکسان استفاده کرد.

فایل HTML برای برنامه‌تان بسازید. وابستگی webapis.js را در فایل HTML خود بگنجانید. ‫PAL برای کار کردن به این وابستگی نیاز دارد. برای کسب اطلاعات بیشتر، به مستندات Samsung WebApi مراجعه کنید.

وابستگی به «کیت توسعه نرم‌افزار CTV PAL» را در فایل 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 برای تولید یک نانس ایجاد کنید. این مرحله شامل گردش کار 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();
});

عدد یک‌بارمصرف را به درخواست آگهی پیوست کنید

برای استفاده از نانس تولیدشده، برچسب آگهی‌تان را با پارامتر 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);
        
      })

اگر از 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 پیکربندی کنید.

سرور آگهی طرف سوم خود را پیکربندی کنید تا مقدار یک‌بارمصرف را در درخواست سرور به 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%%، پشتیبانی کند و آن را با پارامتر پُرسمان یک‌بارمصرف که در مرحله قبلی ارائه کردید جایگزین کند. اطلاعات بیشتر درباره نحوه انجام این کار باید در اسناد سرور آگهی طرف سوم دردسترس باشد.

فقط همین! اکنون باید پارامتر nonce را از کیت توسعه نرم‌افزار PAL، ازطریق سرورهای واسطه خود، و سپس به Google Ad Manager منتقل کنید. این کار باعث بهتر شدن درآمدزایی ازطریق Google Ad Manager می‌شود.