Aby zobaczyć przykładową aplikację, która używa PAL do generowania wartości nonce, pobierz przykład CTV Samsung Tizen z GitHub.
W tym przewodniku pokazujemy, jak zintegrować pakiet PAL SDK z aplikacją Samsung Tizen, wysłać żądanie nonce i zarejestrować wyświetlenia reklam.
Wymagania wstępne
Zanim zaczniesz korzystać z tego przewodnika, musisz utworzyć podstawową aplikację na Tizena. Możesz użyć środowiska Tizen IDE, aby skonfigurować aplikację. Więcej informacji znajdziesz w tym filmie o rozpoczynaniu pracy z Tizenem.
Wygeneruj nonce
„Nonce” to pojedynczy zaszyfrowany ciąg znaków wygenerowany przez PAL za pomocą NonceLoader.
Pakiet PAL SDK wymaga, aby każdemu nowemu żądaniu strumienia towarzyszyła nowo wygenerowana liczba jednorazowa. Jednak wartości nonce mogą być ponownie używane w przypadku wielu żądań reklam w ramach tego samego strumienia.
Utwórz plik HTML aplikacji. W pliku HTML umieść zależność webapis.js. PAL wymaga tej zależności do działania. Więcej informacji znajdziesz w dokumentacji Samsung WebApi.
Dodaj zależność dla pakietu CTV PAL SDK w pliku index.html. Wczytaj tag skryptu po tagu skryptu dla tagu webapis.js. Przykład znajdziesz w tym pliku: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>
Sygnały spamu PAL wymagają określonych uprawnień Tizen, aby działać prawidłowo. Utwórz plik config.xml z tymi deklaracjami uprawnień:
"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"
Przykład pliku config.xml znajdziesz w tym fragmencie kodu:
<?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>
Następnie utwórz plik JavaScript, aby wygenerować wartość nonce. Ten krok obejmuje proces PAL polegający na utworzeniu NonceLoader, utworzeniu NonceRequest, a następnie wysłaniu żądania nonce za pomocą 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();
});
Dołączanie wartości nonce do żądania reklamy
Aby użyć wygenerowanej liczby jednorazowej, przed wysłaniem żądań reklamy dołącz do tagu reklamy parametr givn i wartość liczby jednorazowej.
/**
* 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);
})
Śledzenie zdarzeń odtwarzania
Na koniec musisz wdrożyć różne procedury obsługi zdarzeń dla odtwarzacza. Na potrzeby testów możesz dołączyć je do zdarzeń kliknięcia przycisku, ale w rzeczywistym wdrożeniu będą one wywoływane przez odpowiednie zdarzenia odtwarzacza:
/**
* 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();
}
}
W swojej implementacji wywołuj funkcję sendPlaybackStart po rozpoczęciu sesji odtwarzania filmu. Funkcja sendPlaybackEnd powinna być wywoływana po zakończeniu sesji odtwarzania filmu. sendAdClick należy wywoływać za każdym razem, gdy użytkownik kliknie reklamę. sendAdTouch należy wywoływać przy każdej interakcji z odtwarzaczem za pomocą dotyku.
(Opcjonalnie) Wysyłanie sygnałów Google Ad Managera przez serwery reklamowe firm zewnętrznych
Skonfiguruj żądanie serwera reklam innej firmy w Ad Managerze.
Skonfiguruj serwer reklamowy firmy zewnętrznej tak, aby w wysyłanym do Ad Managera żądaniu uwzględniał wartość nonce. Oto przykład tagu reklamy skonfigurowanego na serwerze reklamowym firmy zewnętrznej:
'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'
Więcej informacji znajdziesz w przewodniku po implementacji po stronie serwera w Google Ad Managerze.
Ad Manager szuka symbolu givn=, aby zidentyfikować wartość nonce. Serwer reklamowy firmy zewnętrznej musi obsługiwać własne makro, np. %%custom_key_for_google_nonce%%, i zastąpić je parametrem zapytania nonce podanym w poprzednim kroku. Więcej informacji o tym, jak to zrobić, znajdziesz w dokumentacji serwera reklamowego firmy zewnętrznej.
To wszystko. Parametr nonce powinien być teraz propagowany z pakietu PAL SDK przez serwery pośredniczące do Google Ad Managera. Umożliwia to lepsze zarabianie dzięki Google Ad Managerowi.