PAL を使用してノンスを生成するサンプルアプリについては、GitHub から CTV Samsung Tizen のサンプルをダウンロードしてください。
このガイドでは、PAL SDK を Samsung Tizen アプリケーションに組み込み、ノンスをリクエストして、広告のインプレッションを登録します。
前提条件
このガイドを開始する前に、基本的な Tizen アプリを作成する必要があります。Tizen IDE を使用してアプリを設定できます。詳しくは、Tizen のスタートガイドの動画をご覧ください。
ノンスを生成する
「ノンス」とは、PAL が NonceLoader を使用して生成する単一の暗号化された文字列です。PAL SDK では、新しいストリーム リクエストごとに、新たに生成されたノンスを付加する必要があります。ただし、同じストリーム内の複数の広告リクエストでノンスを再利用することは可能です。
アプリの HTML ファイルを作成します。HTML ファイルに webapis.js 依存関係を含めます。PAL が機能するには、この依存関係が必要です。詳細については、Samsung WebApi のドキュメントをご覧ください。
index.html ファイルに CTV PAL SDK の依存関係を含めます。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>
次に、nonce を生成する JavaScript ファイルを作成します。このステップには、NonceLoader の作成、NonceRequest の作成、NonceLoader.loadNonceManager() を使用した nonce のリクエストという PAL ワークフローが含まれます。
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 を 1 回呼び出す必要があります。sendPlaybackEnd は、動画再生セッションが終了したときに呼び出す必要があります。sendAdClick は、視聴者が広告をクリックするたびに呼び出す必要があります。sendAdTouch は、プレーヤーとのすべてのタッチ操作で呼び出す必要があります。
（省略可）第三者広告サーバー経由で Google アド マネージャーのシグナルを送信する
アド マネージャーに対するサードパーティ広告サーバーのリクエストを設定します。
アド マネージャーへのサーバーのリクエストに nonce を含めるように、第三者広告サーバーを設定します。第三者広告サーバー内で設定された広告タグの例を次に示します。
'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'
詳しくは、Google アド マネージャーのサーバーサイド実装ガイドをご覧ください。
アド マネージャーは givn= を探して、ノンス値を特定します。第三者広告サーバーは、%%custom_key_for_google_nonce%% などの独自のマクロをサポートし、前のステップで指定した nonce クエリ パラメータに置き換える必要があります。この方法について詳しくは、第三者広告サーバーのドキュメントをご覧ください。
これで、これで、PAL SDK から仲介サーバーを経由して Google アド マネージャーに nonce パラメータが伝播されるようになります。これにより、Google アド マネージャーで収益化を促進できます。