بدء استخدام Tizen (Samsung)

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

يدمج هذا الدليل حزمة PAL SDK في أحد تطبيقات Samsung (Tizen)، واطلب غير متكرر، وتسجيل مرات ظهور الإعلان.

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

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

إنشاء رقم Nonce

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

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

أدرِج سمة تبعية لحزمة تطوير البرامج (SDK) الخاصة بالتلفزيون المتّصل (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>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 storageConsent = true;
let playbackStarted = false;

/**
 * A placeholder for the publisher's own method of obtaining user
 * consent, either by integrating with a CMP or based on other
 * methods the publisher chooses to handle storage consent.
 * @return {boolean} Whether storage consent has been given.
 */
function getConsentToStorage() {
  return storageConsent;
}

/**
 * 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 `allowStorage` is false, but can be
  // changed once the appropriate consent has been gathered.
  const consentSettings = new goog.ctv.pal.ConsentSettings();
  consentSettings.allowStorage = getConsentToStorage();

  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 بطلب الإعلان

لاستخدام الرمز المؤقت الذي تم إنشاؤه، يجب إلحاق علامة إعلانك بالمَعلمة 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);
        
      })

تتبُّع أحداث التشغيل

وأخيرًا، عليك تنفيذ معالِجات أحداث مختلفة للّاعب. لأغراض الاختبار، يمكنك إرفاق هذه الإجراءات بأحداث النقر على الأزرار، ولكن في عملية التنفيذ الفعلية، سيتم بدء هذه الإجراءات من خلال أحداث المشغّل المناسبة:

/**
 * 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"

عليك ضبط خادم الإعلانات التابع لجهة خارجية لتضمين المفتاح العشوائي في طلب الخادم إلى "مدير إعلانات Google". في ما يلي مثال على علامة إعلان تم ضبطها داخل خادم إعلانات جهة خارجية:

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

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

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

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