بدء استخدام نظام التشغيل Samsung Tizen

للاطّلاع على نموذج تطبيق يستخدم PAL لإنشاء رقم خاص، نزِّل مثال Samsung Tizen على التلفزيون المتّصل (CTV) من GitHub.

يتضمّن هذا الدليل دمج حزمة PAL SDK في تطبيق Samsung Tizen، وطلب رقم خاص، وتسجيل مرّات ظهور الإعلانات.

المتطلبات الأساسية

قبل البدء في هذا الدليل، عليك إنشاء تطبيق Tizen أساسي. ويمكنك استخدام Tizen IDE لإعداد التطبيق. لمزيد من المعلومات، يمكنك مشاهدة هذا الفيديو حول البدء باستخدام Tizen.

إنشاء رقم خاص

"الرقم الخاص" هو سلسلة مشفّرة واحدة يتم إنشاؤها بواسطة PAL باستخدام NonceLoader. تتطلّب حزمة تطوير البرامج (SDK) الخاصة بـ PAL أن يكون كل طلب بث جديد مصحوبًا برقم عشوائي جديد تم إنشاؤه. ومع ذلك، يمكن إعادة استخدام الأرقام العشوائية لطلبات إعلانات متعددة ضمن البث نفسه.

أنشِئ ملف HTML لتطبيقك، وتضمين التبعية webapis.js في ملف HTML. تتطلّب PAL هذه التبعية لكي تعمل. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Samsung WebApi.

أدرِج ملحقًا لحزمة تطوير البرامج (SDK) الخاصة بـ 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" من خلال خوادم إعلانات خارجية

اضبط طلب خادم الإعلانات التابع لجهة خارجية في "إدارة إعلانات Google".

اضبط خادم الإعلانات من جهة خارجية لتضمين الرقم الخاص في طلب الخادم إلى &quot;إدارة الإعلانات&quot;. في ما يلي مثال على علامة إعلان تم إعدادها داخل خادم إعلانات من جهة خارجية:

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

لمزيد من التفاصيل، اطّلِع على دليل تنفيذ &quot;مدير إعلانات Google&quot; من جهة الخادم.

يبحث "مدير إعلانات Google" عن givn= لتحديد قيمة الرقم العشوائي. يجب أن يتيح خادم الإعلانات التابع لجهة خارجية استخدام بعض وحدات الماكرو الخاصة به، مثل %%custom_key_for_google_nonce%%، وأن يستبدلها بمَعلمة طلب البحث الخاصة برقم الاستخدام لمرة واحدة التي قدّمتها في الخطوة السابقة. يجب أن تتوفّر معلومات إضافية حول كيفية تنفيذ ذلك في مستندات خادم الإعلانات التابع لجهة خارجية.

هذا كل شيء! من المفترض أن تكون قد تمكّنت الآن من نشر مَعلمة nonce من PAL SDK، من خلال خوادمك الوسيطة، ثم إلى إدارة إعلانات Google. يتيح ذلك تحقيق الربح بشكل أفضل من خلال &quot;مدير إعلانات Google&quot;.