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

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

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

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

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

إنشاء رقم خاص

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

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

أدرِج اعتمادية لحزمة تطوير البرامج (SDK) الخاصة بـ PAL على التلفزيون المتّصل (CTV) في ملف 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();
  });

  // 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" من خلال خوادم إعلانات تابعة لجهات خارجية

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

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

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

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

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

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