Výdejový script reklamy Home

Použití pro začátečníky (singlerequest použití)

Pro každou reklamní zónu voláme metodu getAds samostatně a předáváme jí objekt popisující jednu konkrétní zónu. Tento způsob výdeje nedoporučujeme, protože některé funkce SSP serveru (například multipozice) jsou při něm nedostupné.

Reklamní kód, který si partner vygeneruje v uživatelském rozhraní, má následující podobu (kód pro jednu zónu):

<div id="cnt-1234"></div>
<script src="https://ssp.seznam.cz/static/js/ssp.js"></script>
<script>
  sssp.getAds({
    zoneId: 1234,
    id: 'cnt-1234',
    width: 970,
    height: 210,
  });
</script>

Pozn.: cnt-xxxx – hodnota zoneId je v rozhraní nahrazena skutečným ID zóny (v příkladu 1234)

Kód lze libovolně měnit dle níže uvedené specifikace.

Multirequest použití

Multirequest použití umožňuje výdejovému skriptu SSP obsloužit všechny reklamní pozice na stránce najednou – odesláním jednoho requestu na SSP server. Pro partnera to znamená nadefinovat všechny objekty popisující reklamu v jednom poli a zavolat metodu getAds jen jednou. Volání musí být provedeno až poté, co se na stránce nacházejí všechny elementy, do kterých se má reklama vypsat.

<!-- příklad obsahující tři pozice na stránce (leader, sky, rectangle) -->
<script src="https://ssp.seznam.cz/static/js/ssp.js"></script>
<script>
  sssp.getAds([
    {
      zoneId: 1234,
      id: 'leader',
      width: 970,
      height: 210,
    },
    {
      zoneId: 5678,
      id: 'sky',
      width: 300,
      height: 600,
    },
    {
      zoneId: 9101,
      id: 'rectancle',
      width: 970,
      height: 310,
    },
  ]);
</script>

Přehled nastavení SSP výdeje

Chování výdeje reklamy je možné konfigurovat pomocí funkce sssp.config(), která na vstupu očekává konfigurační objekt.

Možné konfigurační položky:

protocol

viz tabulka

server

viz tabulka

version

viz tabulka

source

Pokud se nastaví na některou z hodnot uvedených v tabulce, pak je tato hodnota posílána společně s požadavkem o reklamu. Slouží ke zpřesnění informací o stránce, která o reklamu žádá.

Hodnota „hp_feed“ se musí posílat v případě, kdy se uživatel na stránku, která si říká o reklamu, dostal proklikem z newsfeedu na homepagi Seznam.cz.

adblock

viz tabulka

cookieDomain

viz tabulka

cookieExpiration

viz tabulka

preparePositionsCallback

Funkce se volá tehdy, pokud je v platnosti session zahájená příchodem uživatele proklikem z newsfeedu na homepagi Seznam.cz.

requestErrorCallback

Callbacková funkce, kterou SSP volá v případě selhání XHR požadavku na reklamní server (např. pro vlastní logování chyb apod.). Funkci jsou předány 2 parametry:

• errorName (string) - Popis chyby
• errorCode (number) - Číselný kód chyby XMLHttpRequest

callCallbackOnError

Defaultně nastaveno na false. Když je nastaveno na true callback funkce se provolá i při errových stavech SSP. Je potřeba pamatovat na to, že v případě standardního volání callback funkce obdrží dva parametry advert, data. Ovšem v případě chyby obdrží jen jeden parametr objekt chyby vrácený SSP serverem.

documentWriteOverride

Umožnuje vypnout přepsání nativního document.write. Pokud je přepsání zakázáno, reklamy vypisované přímo do stránky, obsahující volání document.write mohou stránku rozbít!

Poznámka: v některých případech není konfigurace přepisu document.write pomocí metody sssp.config možná (např. při nepředvídatelných asynchronních operacích, podmíněných konfiguracích apod.). Pokud s konfigurací výše vznikají problémy, je možné do objektu window definovat proměnnou SSSP_DW_FORCE_DISABLED = true, která zajistí, že SSP skript nikdy nativní document.write nepřepíše (tedy ani pokud je to explicitně definováno konfigurací).

ab

Slouží k zaznamenání vlastních variant AB testu (např. { homepageVariant: 'a' }). Do objektu je možné vložit více hodnot.

webId

Nastaví hodnotu webId. Pokud je specifikována hodnota, automaticky se spustí konfigurace CMP dialogu a může způsobit jeho zobrazení i bez volání funkce sssp.getAds.

test

Slouží k testování výdeje reklamy, nedochází ke kontrole URL při výdeji a není účtovaná cena za zobrazení Povolené hodnoty: true/false

• true - testovací režim
• false - provozní režim (výchozí)

Přehled nastavení zóny

Pro správnou funkčnost reklamní zóny se prosím vyvarujte nastavování CSS vlastností na kontejner reklamy (element s třídou adFull), které by mohly být v konfliktu se styly, které nastavuje SSP skript (zejména rozměry, pozicování, transformace apod). Pokud layout webu vyžaduje, aby byla reklama v takovém elementu umístěna, musí v něm být vnořena tak, aby nedědila přímo nastavené CSS.

Nastavení objektu zóny

Povinné položky pro konfiguraci pozice jsou: – zoneId – id nebo callback – width nebo height nebo oba

id

Idenfifikátor HTML elementu, do kterého se má vypsat reklama. Při vypsání reklamy musí mít element rozměry, reklama má totiž vždy nastavené rozměry 100% × 100%. Více viz width a height.

zoneId

Unikátní identifikátor reklamní zóny. Toto číslo je zóně přiřazeno automaticky při vygenerování reklamního kódu v partnerském rozhraní, kde ho lze také zpětně dohledat (stránka Reklamní kódy).

width a height

Definice rozměrů reklamní plochy. Tyto údaje se posílají na SSP server, který na jejich základě vydá banner o maximálních rozměrech, které se do plochy vejdou (tolerance +5 %, výdejový skript banner případně zmenší, aby se do plochy vešel celý). Musí být zadán alespoň jeden rozměr.

Pokud nejsou rozměry reklamní zóny zadané v konfiguračním objektu, výdejový skript SSP se je v požadavku pokusí nahradit rozměry HTML elementu, do kterého se má reklama vydat. V případě, že má HTML element nesprávné fyzické rozměry, požadavek o reklamu pro dotčenou zónu selže.

Typickým případem je situace, kdy je v konfiguračním objektu zadána pouze šířka (width), zatímco výška (height) se zjišťuje z HTML elementu. V takovémto případě musí mít element výšku (offsetHeight) nulovou, jinak se tato hodnota pošle SSP serveru.

Možné varianty chování:

1. HTML element má nenulové rozměry – jak šířku, tak výšku (nemusí se zadávat rozměry v konfiguraci)
2. HTML element má nulové rozměry (alespoň jedna z hodnot musí být zadána v konfiguraci)
3. Rozměry jsou zadané v konfiguraci a zároveň má HTML element nenulové rozměry (použijí se rozměry z konfigurace)
4. Rozměry nejsou zadané v konfiguraci ani je nelze zjistit z rozměrů HTML elementu (výdej se zastavuje a končí chybou)

Pokud má HTML element nulovou výšku, nastaví se tato podle výšky vydaného banneru.

minWidth a minHeight

Pokud je potřeba definovat minimální rozměr reklamy, kterou má SSP vrátit, lze nastavit tyto dva parametry.

Příkladem může být situace, kdy pozice podporuje formáty 970x210 (pro desktop) a 300x250 (pro mobilní zařízení). A je potřeba, aby pro desktop chodil pouze rozměr 970x210.

elements

Elements je pole HTML elementů ve stránce, do kterých je možné reklamu vypsat (platí pro jednu zónu). Banner se vydá do takového HTML elementu, jehož rozměry jsou stejné jako rozměry banneru nebo nejbližší větší. Pole HTML elementů není omezeno.

Definice objektu HTML elementů:

    {
        id: "xxx", // ID elementu
        width: 300,
        height: 250
    }

Příklad definice pro leaderboard a branding:

[
  {
    id: 'leader',
    width: 970,
    height: 210,
  },
  {
    id: 'branding',
    width: 2560,
    height: 1440,
  },
];

serviceId

Přiděluje jednotlivým službám Seznam Partner.

contentId

String generovaný službou. Musí být zajištěna unikátnost v rámci autora.

callback

Callback je funkce, kterou prohlížeč zavolá v okamžiku, kdy z SSP serveru dorazí reklama. Předají se jí dva parametry z odezvy: advert – objekt obsahující informace o reklamě a data – objekt s definicí zóny. Při zpracování je potřeba započítat všechny imprese, missy a visibilní imprese (viz definici objektu reklamy z SSP serveru). Pro tento účel je nutné provolat metodu sssp.served(ads.tracking.served).

V případě, že má položka iframe v odezvě hodnotu 1, musí být obsah položky advert.data zabalen do iframu. Při použití standardního výdeje zajišťuje tento krok výdejový skript ssp.js (data reklamy se vypíší do https://ssp.seznam.cz/static/html/reklama.html a URL se použije jako atribut src elementu iframe).

Při vykreslování reklamy vlastním callbackem je nutné zabalení do iframu provést v rámci této metody. Chcete-li při tom využít soubor https://ssp.seznam.cz/static/html/reklama.html a v něm zahrnuté JavaScripty, doporučujeme vám vytvořit si vlastní lokální kopie těchto souborů. V opačném případě byste riskovali, že pokud v budoucnu soubory upravíme, mohla by se reklama na vašem webu přestat zobrazovat. Pokud je typ reklamy code nebo iframe_url, lze pro vykreslení reklamy do stránky využít funkci writeAd(). Toto neplatí, je-li parametr documentWriteOverride nastavený na false!

    function callback (advert, data) {
        advert = {
            // odpoved ze serveru
            data: "kod banneru"
            type: "typ",
            width: 970,
            height: 310,
            dsp: "ADVERT",
            responsive:0,
            iframe:0,
            ...
        }

        data = {
            // definice pozice ze stranky
            zoneId: 123456
            id: "leader",
            width: 970,
            height: 310,
            ...
        }
    }

options : section

Sekce pro výdej banneru z IM.

// příklad sekce
options: {
  section: '/domaci/krimi';
}

options : collocation

Klíčová slova pro výdej banneru z IM.

// příklad klíčového slova
options: {
  collocation: 'praha-6 praha video';
}

options : passons

Hodnoty předávané do banneru IM. V banneru jsou dostupné jako __PASSON_klic__.

    // příklad passonu
    options: {
        passons: {cena:1000, urok:2}
    }

options : flags

Hodnoty, podle kterých se vybírají části šablony banneru v IM.

// příklad flagu
options: {
  flags: 'video ram';
}

options : infoCallback

Funkce infoCallback je určená k vypsání informací o reklamě (například do konzole nebo logu). Zavolá se pro každou reklamní pozici poté, co se získají data z SSP, ale předtím, než se zavolá callback (obsahuje surová, nezpracovaná data z SSP serveru, může tedy nastat případ, kdy jsou nekonzistentní položky data a type). K volání dojde bez ohledu na to, zda pozice obsahuje reklamu, či nikoliv, nebo zda došlo k chybě. Předávané parametry jsou objekty ad a data popisující pozici.

sssp.getAds({
  zoneId: 123456,
  id: 'elm-123456',
  callback: (ad, data) => {
    /* vypsani reklamy */
  },
  options: {
    infoCallback: (ad, data) => {
      // vypsani informaci o  reklame
      console.log(ad, data);
    },
  },
});

options : infoErrorCallback

Funkce infoErrorCallback je volána pro každou zónu, která není správně nakonfigurovaná a proto bude vyřazená z požadavku na reklamu.

sssp.getAds({
  zoneId: 123456,
  id: 'elm-123456',
  options: {
    infoErrorCallback: (position, errorMessage) => {
      console.log(`${errorMessage}: Wrong configuration for zoneID ${position.zoneId}.`);
    },
  },
});

options : noSize

Pokud je nastaveno na true, SSP nebude vyžadovat rozměr u pozice. Použití je primárně určeno pro video pozice.

options : nativeTemplate

Hodnota definuje, zda žádáme defaultní nebo rozšířenou šablonu pro nativní reklamu

• nativeTemplate: 1 - defaultní šablona pro nativní reklamu, parametr není třeba v requestu posílat
• nativeTemplate: 2 - rozšířená šablona pro nativní reklamu, pokud chci tuto variantu, je to povinny parametr

Popis odezev SSP serveru

Požadavek na SSP server se posílá metodou POST. Tělo požadavku je tvořeno JSON strukturou. Odpověď SSP serveru je rovněž JSON struktura sestávající z následujících položek:

ads

Pole všech reklam z SSP serveru

data

Obsahuje řetězec dat reklamy. V řetězci může být obsaženo:

• iframe_url – odkaz na kompletní HTML stránku, lze umístit přímo do iframe atributu src
• iframe – zdrojový HTML kód reklamy, lze vypsat do iframe se src atributem https://ssp.seznam.cz/static/html/[hostname]/reklama.html?url=[href]
• code – zdrojový HTML kód reklamy, lze vypsat přímo do stránky
• code_url – odkaz, na kterém je dostupný zdrojový HTML kód reklamy
• vast – textový řetězec, který reprezentuje reklamu ve VAST XML, lze parsovat jako XML dokument
• vast_url – odkaz, na kterém je dostupná reklama ve formě VAST dokumentu
• json – textový řetězec, který reprezentuje reklamu v JSON struktuře, lze parsovat jako JSON objekt pomocí JSON.parse
• json_url – odkaz, na kterém se nachází reklama v JSON struktuře
• empty – reklama nedorazila
• error – došlo k chybě při výdeji reklamy

width

Šířka banneru, jak ji zná SSP server.

height

Výška banneru, jak ji zná SSP server.

responsive

Flag označující, zda se reklama umí plně přizpůsobit HTML elementu, do kterého je vložena. Pokud je flag false, výdejový SSP skript automaticky zmenšuje kreativu tak, aby se do elementu vešla (pomocí CSS vlastnosti transform: scale).

dbgInfo

Debug informace ze SSP serveru pro interní použití.

dbgInfo : error

Chybové hlášení SSP.

zoneId

ID zóny, do které se reklama vydává.

dsp

Jméno DSP, používá se pro šablony.

tracking : served

Pole impressních a miss URL, pomocí kterých se měří počet vykreslení či nevydání reklamy do stránky. Je potřeba na všechny tyto URL provést hit (například vytvořením elementu img, kde URL použijeme jako hodnotu atributu src).

tracking : visible

Pole visibilních URL, pomocí kterých se měří počet zobrazení reklamy uživatelům (tedy situace, kdy se reklama nachází ve viewportu). Je potřeba na všechny tyto URL provést hit (například vytvořením elementu img, kde URL použijeme jako hodnotu atributu src). Visibilitu měří SSP automaticky, pokud je zadáno v konfiguraci pozice id elementu. Visibilita je měřena podle IAB standardu.

Příklad odpovědi SSP serveru

    // příklad odezvy SSP serveru
{ "ads" : [
// pole dat k reklamnim pozicim
     {
        "data" : "//sssp.cz/dataurl", // pokud reklama není, bude hodnotou prázdný řetězec
        "type" : "url", // pokud reklama není, bude empty
        "width" : 300,
        "height" : 300,
        "responsive" : false,
        "tracking" : {
            "served" : ["//sssp.cz/impress?1234"],
            "visible" : ["//sssp.cz/visibility?1234"]
        },
        "dbgInfo" : {}, // informace z DSP (id a další údaje dodané DSP)
        "zoneId" : 123
      }
   ]
}

AMP výdej

AMP výdej je realizován pomocí GitHub amphmtl.

Pomocí vložení callbacku AMPcallback do options ve volání getAds() říkáme AMP, že je reklama připravena k renderu AMP.

Definice pozic pomocí HTML tagů

K definování reklamních pozic lze využít také definici pozice přímo u elementu, do kterého se bude reklama vkládat. Stačí elementu nastavit atribut data-szn-ssp-ad, ve kterém se definuje pozice pomocí JSON formátu, tak jako při použití getAds metody pro jednu pozici. Takto lze nadefinovat všechny pozice ve stránce a následně na konci stránky zavolat metodu getAdsByTags, která nalezne všechny tyto elementy ve stránce a provede request na SSP server.

    <body>
        <script src="https://ssp.seznam.cz/static/js/ssp.js"></script>
        ...
        <div id="p1" data-szn-ssp-ad='{"zoneId": 77801, "width": 970}'></div>

        <div id="p2" data-szn-ssp-ad='{"zoneId": 52676, "width": 300}'></div>
        ...
        <script>
                sssp.getAdsByTags();
        </script>
        ...
    <body>

Asynchronní načítání SSP scriptu

Výdejový JavaScript ssp.js se bude načítat asynchronně, doplníme-li do příslušného HTML elementu script atribut defer. Asynchronní načítání přináší výhodu v podobě rychlejšího zobrazení celé stránky, zvláště pak v případě, kdy je element odkazující na výdejový JavaScript umístěn v její hlavičce. Aby nedošlo k chybě, je třeba metody z ssp.js ve stránce volat až ve chvíli, kdy je výdejový JavaScript kompletně načtený. Toho můžeme docílit například způsobem uvedeným v příkladu:

<head> ... <script defer src="https://ssp.seznam.cz/static/js/ssp.js" id="ssp-script"></script> ...
</head>

    <body>
        ...
        <div id="p1" data-szn-ssp-ad='{"zoneId": 77801, "width": 970}'></div>

        <div id="p2" data-szn-ssp-ad='{"zoneId": 52676, "width": 300}'></div>
        ...
        <script>
            var sspScript = document.getElementById('ssp-script');
            sspScript.addEventListener('load', function() {
                sssp.config({
                    // Konfigurace SSP
                });

                sssp.getAdsByTags();
            });
        </script>
        ...
    <body>

Podporován je i původní způsob přidávání funkcí do fronty pomocí pole window.ssspQ. Tento způsob doporučujeme používat jen v krajních případech, kdy nelze použít způsob výše – typicky pokud nemáte plnou kontrolu nad načtením SSP skriptu.

    <body>
        ...
        <div id="p1" data-szn-ssp-ad='{"zoneId": 77801, "width": 970}'></div>

        <div id="p2" data-szn-ssp-ad='{"zoneId": 52676, "width": 300}'></div>
        ...
        <script>
            (function () {
                window.ssspQ = window.ssspQ || [];
                var p = {source:"media", site:"novinky.cz"};
                window.sssp ? sssp.config(p) : ssspQ.push(function () { sssp.config(p) });
            })();
            (function () {
                window.ssspQ = window.ssspQ || [];
                window.sssp ? sssp.getAdsByTags() : ssspQ.push(function () { sssp.getAdsByTags() });
            })();
        </script>
        ...
    <body>

API pro detekci návštěvy z newsfeedu, algoritmus pro session, API pro vypnutí DOT

window._sspDoNotLoadDOT

Pokud je potřeba zakázat automatickou detekci a načítání dot-small.js, je možné nastavit do window proměnou _sspDoNotLoadDOT, které způsobí vypnutí kontroly existence dot-small.js. Toto použití je podmíněno tím, že daná stránka zajistí načtení a zkonfigurování dot-small.js před vložením ssp.js do stránky!

Algoritmus zobrazování Seznam reklamy

Příchod a prohlížení stránek

1. Uživatel klikne na odkaz na článek umístěný v newsfeedu na hlavní stránce Seznam.cz.
2. Tento odkaz (URL) má na konci parametry ve tvaru ?utm_source=www.seznam.cz&utm_medium=sekce-z-internetu#dop_ab_variant=1&dop_source_zone_name=hpfeed.sznhp.box&dop_vert_ab=722020&dop_vert_id=leg0&dop_req_id=OLWKUKB4Qyw-201912030607&dop_id=22.
3. Podle vámi preferované technologie (na serveru, nebo pomocí API v SSP skriptu) se vypne vaše reklama a zobrazí se reklama od Seznamu.
4. Do cookie (s expirací například 30 minut) na vašich stránkách uložíte informaci o tom, že uživatel přišel z hlavní stránky Seznam.cz. Po dobu platnosti cookie se uživateli vydává výhradně reklama od Seznamu.
5. Pokračuje-li uživatel v prohlížení stránek, prodlužuje tím platnost cookie.

Opuštění stránek a návrat

Pokud uživatel stránky opustí (například zavře panel nebo v prohlížeči zadá jiné URL) a opět se na web vrátí jinak než proklikem z hlavní stránky Seznam.cz, kontroluje se cookie:

• cookie neexistuje – stránky se chovají standardně a zobrazují vaši vlastní reklamu
• cookie existuje – proběhne kontrola hodnoty hostname v referreru stránky s hostname vašeho webu
• rozdílný hostname – uživatel přišel z jiné stránky a vydává se mu vaše reklama
• stejný hostname – uživatel přišel z jiné stránky vašeho webu a vydává se mu reklama od Seznamu

API pro detekci návštěvy z newsfeedu

K dispozici je rovněž API, které detekuje stavy, kdy se má vydat reklama od Seznamu.

Pokud je potřeba před vypsáním reklamy udělat přípravné kroky, lze zadat sssp.conf.preparePositionsCallback() funkci, která bude zavolána před vypsáním reklamy do stránky.

Ve stránce pak voláme metodu sssp.displaySeznamAds(), která vrací hodnoty true / false podle toho, zda se má, či nemá vypsat reklama od Seznamu.

<script src="https://ssp.seznam.cz/js/ssp.js"></script>
<script>
  sssp.conf.preparePositionsCallback = function () {
    // příkazy k provedení
  };

  if (sssp.displaySeznamAds()) {
    // zobrazuji Seznam reklamu
    sssp.getAds([{ zoneId: 1243, id: 'skyscraper' }]);
  } else {
    // vypsání původní reklamy, adForm, BBElements…
  }
</script>

Prerekvizity pro správnou funkčnost postupu výše:

• Zajištění dostupnosti funkcí poskytovaných objektem sssp, tj. například vložením SSP skriptu do hlavičky stránky Upozornění: Všechna nastavení musí být provedena pomocí sssp.config(), jiné zásahy nebo výměny mohou vést k chybám.
• Zachování parametrů v URL při první návštěvě uživatele z homepage

Session při přechodech mezi doménami

SSP – držení session při přechodech mezi doménami

• Na konec všech odkazů na webu partnera (zařazeného do newsfeedu nebo denního tisku), které směřují na jinou doménu (patřící do portfolia tohoto partnera), je třeba doplnit parametr szn-session a jeho hodnotu označující doménu webu, odkud odkaz vede.
• Stránka na partnerském webu musí při načtení ověřit, zda existuje UTM parametr nebo výše uvedený parametr, a v závislosti na tom nastavit session cookie i na odkazovaném webu.
• Kód, který je ve stránce nyní a řeší nastavení a držení session v rámci jedné domény, může zůstat nezměněn.

Příklad implementace:

<html>
  <head>
    <title>Web na domene abcd.cz</title>
  </head>
  <body>
    <a href="odkaz.html">odkaz v ramci webu</a>
    <a href="https://efgh.cz/odkazVen.html?szn-session=abcd.cz&utm_source=www.seznam.cz&utm_medium=sekce-z-internetu"
      >odkaz na jinou domenu (partnerskou)</a
    >
    <!-- je jedno, jak se parametr prida, jestli bude primo v html nebo doplneny pomoci JS -->
    <a href="https://www.google.com">odkaz na domenu ven (ne partnerskou)</a>
    <script>
      if (location.search) {
        const urlParams = new URLSearchParams(location.search);
        // zjistim, zda je v url UTM parametr nebo session parametr nebo existuje session cookie
        if (location.href.indexOf('szn-session') != -1 || urlParams.get('utm_medium')) {
          // pokud ano, pak i na domene efgh.cz nastavim session cookie s hodnotou utm_medium
          sssp.setSessionCookie(urlParams.get('utm_medium'));
        }
      } else if (sssp.existSessionCookie()) {
        // nebo pokud jiz existuje session cookie, pak i na domene efgh.cz nastavim stejnou session cookie
        const cookie = (document.cookie.match('(^|;) *' + 'sssp_session' + '=([^;]*)') || [])[2];
        const sessionData = JSON.parse(decodeURIComponent(cookie)).media;
        sssp.setSessionCookie(sessionData);
      }
      // nasleduje dalsi kod vyuzivajici existenci cookie a vkladajici reklamu
    </script>
  </body>
</html>

Nastavení Content Security Policy

Používáte-li na svém webu Content Security Policy (CSP; vysvětlení, o co se jedná, najdete například v tomto článku), je třeba zahrnout do výčtu domén, které váš web považuje za důvěryhodné, také domény související s reklamou od Seznamu. K tomuto účelu slouží soubor ads-csp.json, obsahující objekt se seznamem těchto domén pro CSP, který pravidelně aktualizujeme. Položky v objektu jsou nazvané podle direktiv CSP (například script-src). Hodnotou každé položky je pole důvěryhodných URL (oddělených čárkami).

Aby se reklama od Seznamu na vašem webu zobrazovala správně a abyste se vyhnuli potenciálnímu výpadku příjmů z reklamy, je nezbytné, abyste nastavili proces automatické aktualizace Vašich CSP direktiv, případně na endpoint ads-csp.json přímo navázali funkčnost Vašeho webserveru. Obsah endpointu se může změnit náhle bez varování.

Videoreklama VAST

VAST (Video Ad Serving Template) je specifikace definovaná a vydaná organizací Interactive Advertising Bureau, která stanoví standard komunikačních požadavků mezi reklamními servery a videopřehrávači za účelem prezentace videoreklamy. Pro výdej videoreklamy v tomto formátu slouží end point /v2/vast, který přijímá požadavky na výdej jedné nebo více reklam.

HTTP hlavičky

Server SSP čte následující hlavičky:

GET parametry

• ¹ detailní informace o požadavku na více zón jsou uvedeny v následující sekci
• ² obě hodnoty w a h musí být použity současně
• ³ způsob zápisu pole v parametrech dotazu
• ⁴ tato hodnota je předána pouze IM (Internet Media) DSP z důvodu zpětné kompatibility
• ⁵ doporučené parametry; pokud jeden z těchto parametrů nebo jedna hodnota z cookie chybí, vrátí ssp-server necílenou reklamu

Požadavek na více zón

V případě několika zón budou parametry požadavku na více zón (zadané ve sloupci Požadavek na více zón v tabulce výše) označeny postfixem -index, kde index je pořadové číslo zóny od 1 do celkového počtu zón (N). Parametry požadavku mohou tedy vypadat následovně:

?zoneId-1=136966&skippable-1=true&zoneId-2=136967&skippable-2=false

Všimněte si, že indexy nelze přeskočit, jinak budou vynechány. Z následujícího požadavku: zoneId-1=foo & zoneId-3=bar bude použito pouze zoneId-1=foo.

Parametry požadavku na více zón mají přednost před parametry pro jednu zónu (pokud budou použity, dojde k jejich vynechání). V případě jedné zóny použijte standardní parametry požadavku. Výsledek požadavku na více zón bude obsahovat více <Ad> tagů s pořadím atributu odpovídajícím indexu zóny.

Pole v parametrech požadavku

Pole v parametrech požadavku lze reprezentovat dvěma způsoby:

1. Opakováním parametru vícekrát ?protocols=1&protocols=2 ?videoFormats=video/mp4&videoFormats=video/webm

2. Poskytnutím seznamu hodnot oddělených čárkou ?protocols=2,3 ?videoFormats=video/mp4,video/webm

Všimněte si, že tato pravidla se nevztahují na parametry požadavku na více zón, které se řídí pravidly popsanými v tabulce výše.

Enum protokol

Definice konkrétních požadovaných protokolů.

Response

Response je v podobě validního VAST dokumentu vráceného s HTTP statusem 200. Pokud není k dispozici žádná reklama, která by se mohla zobrazit, pak se nevrátí žádná odpověď s HTTP statusem 200. Místo toho obsahuje odezva pole tagů se sledovací URL (v CDATA), kterou musí přehrávač zavolat.

Pokud selže validace požadavku, je vrácen stav HTTP 400. Pokud dojde k problému se zpracováním požadavku, pak SSP odpoví stavem HTTP 500.

Příklady

Požadavek (request) se všemi doporučenými parametry

GET /v2/vast?test=1&zoneId=136966&pvId=123&source=hp_feed&site=http://novinky.cz HTTP/1.1
Host: ssp.seznam.cz
Connection: keep-alive
Content-Length: 353
Pragma: no-cache
Cache-Control: no-cache
Origin: null
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3223.8 Safari/537.36
Content-Type: application/json; charset=UTF-8
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: cs,en-GB;q=0.9,en;q=0.8,sk;q=0.7,de;q=0.6
Cookie: euconsent=BOmWmGPOmWmGPD3ABBCSCj-AAAAqJAIIVEgKQoQI1JBBBgAAAC6IAACAAAQAAABAAAAAIAAACAAgAAAAAEAIAgAAICBABAAAAAAQgAAAAAAAAAAAAAAAAAAAAABCAAAIAAAAQAAAAAAAAA;sid=id=9078004996629498148|t=1546929159.958|te=1546929159.958|c=3D2842BE1FD884ED2F5B29458739AC4

Odezva (response) na požadavek se všemi doporučenými parametry

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.0">
    <Ad>
        <Wrapper>
            <VASTAdTagURI>
                <![CDATA[https://c-ko.seznam.cz/imp?k=39ed1282-bd4d-4caa-9c11-d06f30c40e3a]]>
            </VASTAdTagURI>
            <Impression>
                <![CDATA[https://ssp.seznam.cz/v2/impress?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&s=7_m_TzYPYI1mJ234gGvo]]>
            </Impression>
            <Error>
                <![CDATA[https://ssp.seznam.cz/v2/miss?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&s=lqY1kIJpcaF8CDxJ-b5f]]>
            </Error>
            <Creatives>
                <Creative>
                    <Linear>
                        <TrackingEvents>
                            <Tracking event="skip">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&t=vast_skip&s=hmO_dhOVAN4hvmXy1j_y]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&t=vast_Q1&s=wHi7jvWh7XQQStNtXBBb]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&t=vast_Q2&s=7in-BPt79YgO1RfY6uq3]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&t=vast_Q3&s=UnoeTniTJ2sbgBHaWVba]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=0e571c89-7824-4ab0-ac6f-7d7ba0037add&z=136966&i=0&sid=9679469369724687243&t=vast_Q4&s=s-52wf0U1U8Llp6AUbKW]]>
                            </Tracking>
                        </TrackingEvents>
                    </Linear>
                </Creative>
            </Creatives>
        </Wrapper>
    </Ad>
</VAST>

Požadavek (request) zahrnující více zón

GET /v2/vast?test=1&zoneId-1=149470&zoneId-2=149465&pvId=123&source=hp_feed&site=http://sport.cz&premium=true&rusId=1245636366 HTTP/1.1
Host: ssp.seznam.cz
Connection: keep-alive
Content-Length: 353
Pragma: no-cache
Cache-Control: no-cache
Origin: null
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3223.8 Safari/537.36
Content-Type: application/json; charset=UTF-8
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: cs,en-GB;q=0.9,en;q=0.8,sk;q=0.7,de;q=0.6

Odezva (response) na požadavek zahrnující více zón

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.0">
    <Ad id="2636455" sequence="1">
        <Wrapper>
            <AdSystem>
                <![CDATA[Seznam]]>
            </AdSystem>
            <VASTAdTagURI>
                <![CDATA[https://czgde.adocean.pl/_1571231529.2456562/ad.xml?id=qHo3.23NJ6lQbhaIehqtugo6ExmbPvJmY1mpJvTs1Nj.A7/nc=0/gdpr=0/gdpr_consent=/redir=]]>
            </VASTAdTagURI>
            <Error>
                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=err[ERRORCODE]]]>
            </Error>
            <Impression id="Impression">
                <![CDATA[https://i.seznam.cz/impress?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1]]>
            </Impression>
            <Extensions>
                <Type>
                    <![CDATA[ad]]>
                </Type>
            </Extensions>
            <Creatives>
                <Creative id="2636455" adId="2636455">
                    <UniversalAdId idValue="2636455">2636455</UniversalAdId>
                    <Linear skipoffset="00:00:05">
                        <TrackingEvents>
                            <Tracking event="creativeView">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=view]]>
                            </Tracking>
                            <Tracking event="start">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=start]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=Q1]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=Q2]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=Q3]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=Q4]]>
                            </Tracking>
                            <Tracking event="skip">
                                <![CDATA[https://i.seznam.cz/richmedia?spotId=2636455&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1&type=skip]]>
                            </Tracking>
                            <Tracking event="skip">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&t=vast_skip&test=1&s=N22WyQRPhJwi0JV_lFce]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&t=vast_Q1&test=1&s=BR73xzTV6-yIQq5P_UfT]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&t=vast_Q2&test=1&s=GauXes0mDh80OLhXlR0g]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&t=vast_Q3&test=1&s=spjHZVmdrpWDHgbgZkH0]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&t=vast_Q4&test=1&s=x7TqyqMrcIaFzzn0Qvm2]]>
                            </Tracking>
                        </TrackingEvents>
                        <VideoClicks>
                            <ClickTracking id="Seznam">
                                <![CDATA[https://i.seznam.cz/clickthru?spotId=2636455&redirectionType=noredir&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1]]>
                            </ClickTracking>
                        </VideoClicks>
                    </Linear>
                </Creative>
            </Creatives>
            <Impression>
                <![CDATA[https://ssp.seznam.cz/v2/impress?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&test=1&s=fWZvQEkq_YfjptYXZMjE]]>
            </Impression>
            <Impression>
                <![CDATA[https://i.seznam.cz/miss?zoneId=seznam.sport.videospot.sdeleni&count=1&r=4nB0fO9VEyuVpPNtRTSjlykXp10-2-1]]>
            </Impression>
            <Error>
                <![CDATA[https://ssp.seznam.cz/v2/miss?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149470&i=1&sid=9078004996629498148&test=1&s=x9g8kIRWIjInXw8rvHqf]]>
            </Error>
        </Wrapper>
    </Ad>
    <Ad sequence="2">
        <Wrapper>
            <VASTAdTagURI>
                <![CDATA[https://c-ko.seznam.cz/imp?k=0a4007c3-3fb7-40aa-a71a-974726ef47f0]]>
            </VASTAdTagURI>
            <Impression>
                <![CDATA[https://ssp.seznam.cz/v2/impress?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&test=1&s=NeGE_YQhyRPHP_csRoOJ]]>
            </Impression>
            <Impression>
                <![CDATA[https://i.seznam.cz/miss?zoneId=seznam.pack.sponzor.poradu&count=1&r=4nB0fO9VEyuVpPNtRTSjlykXp10-4-1]]>
            </Impression>
            <Impression>
                <![CDATA[https://i.seznam.cz/miss?zoneId=seznam.sport.sponzor.poradu&count=1&r=4nB0fO9VEyuVpPNtRTSjlykXp10-4-1]]>
            </Impression>
            <Error>
                <![CDATA[https://ssp.seznam.cz/v2/miss?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&test=1&s=J_V9786x7JHEXfKbZjYP]]>
            </Error>
            <Creatives>
                <Creative>
                    <Linear>
                        <TrackingEvents>
                            <Tracking event="skip">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&t=vast_skip&test=1&s=OdTQ4LocoKmm5Noi1cqm]]>
                            </Tracking>
                            <Tracking event="firstQuartile">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&t=vast_Q1&test=1&s=harBIOpJwdHRwX-7Tkvt]]>
                            </Tracking>
                            <Tracking event="midpoint">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&t=vast_Q2&test=1&s=yuBDXHeyMaNRJwo6AZoD]]>
                            </Tracking>
                            <Tracking event="thirdQuartile">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&t=vast_Q3&test=1&s=TdpfnIPMy0J8CMPh2_iF]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[https://ssp.seznam.cz/v2/event?r=8551ee2c-07f1-4e99-9f16-366bb1de2bca&z=149465&i=2&sid=9078004996629498148&t=vast_Q4&test=1&s=t8B0EaB6kCr8CbLS__fO]]>
                            </Tracking>
                        </TrackingEvents>
                    </Linear>
                </Creative>
            </Creatives>
        </Wrapper>
    </Ad>
</VAST>

Odezva (response), pokud není dostupná žádná reklama

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.0">
    <Error>
        <![CDATA[https://ssp.seznam.cz/v2/miss?r=5f5e7252-e15b-4b69-b39b-a6f34c8569c1&z=136966&i=0&sid=&s=p4SILLwtlr94IQpRMQmM]]>
    </Error>
</VAST>

Minimální curl příkaz

curl -v 'https://ssp.seznam.cz/v2/vast?test=1&zoneId=149465&pvID=123&source=hp_feed' \
 -H 'Referer: https://www.sport.cz/' \
 -H 'Origin: https://www.sport.cz' \
 -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36' \
 -H 'Cookie: sid=id=9078004996629498148|t=1546929159.958|te=1546929159.958|c=3D2842BE1FD884ED2F5B29458739AC4D'

Odezva na curl příkaz

*   Trying 77.75.77.43...
* TCP_NODELAY set
* Connected to ssp.seznam.cz (77.75.77.43) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/certs/ca-certificates.crt
  CApath: none
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305
* ALPN, server accepted to use h2
* Server certificate:
*  subject: C=CZ; L=Prague 5; O=Seznam.cz, a.s.; OU=System Support; CN=ssp.seznam.cz
*  start date: Oct  1 03:10:52 2019 GMT
*  expire date: Dec 30 03:10:52 2019 GMT
*  subjectAltName: host "ssp.seznam.cz" matched cert's "ssp.seznam.cz"
*  issuer: C=US; O=DigiCert Inc; OU=www.digicert.com; CN=Thawte RSA CA 2018
*  SSL certificate verify ok.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x5614b869fe80)
> GET /v2/vast?zoneId=149465&pvID=123&test=1 HTTP/2
> Host: ssp.seznam.cz
> Accept: */*
> Referer: https://www.sport.cz/
> Origin: https://www.sport.cz
> User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
> Cookie: sid=id=9078004996629498148|t=1546929159.958|te=1546929159.958|c=3D2842BE1FD884ED2F5B29458739AC4D
>
* Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
* We are completely uploaded and fine
< HTTP/2 200
< server: nginx
< date: Wed, 16 Oct 2019 13:27:04 GMT
< content-type: text/xml
< content-length: 1917
< vary: Accept-Encoding
< set-cookie: sid=id=9078004996629498148|t=1546929159.958|te=1546929582.269|c=CAD1ECBBD019E6FDBBCB707BA8CF4C17; Domain=.seznam.cz; Path=/; Expires=Thu, 07-Feb-2019 06:39:42 GMT
< access-control-allow-methods: GET, POST, OPTIONS
< access-control-allow-headers: content-type
< access-control-allow-credentials: true
< access-control-allow-origin: https://www.stream.cz
< content-type: text/xml
< content-length: 3136
< set-cookie: sid=id=9078004996629498148|t=1546929159.958|te=1571232424.239|c=80C542B5B7C5DB64C2F291A8B9730B29; Domain=.seznam.cz; Path=/; Expires=Fri, 15-Nov-2019 13:27:04 GMT
< p3p: CP="NON DSP COR TAI NOR UNI", policyref="/w3c/p3p.xml"
< vary: Origin
< cache-control: max-age=86400
< expires: Thu, 17 Oct 2019 13:27:04 GMT
<
* Connection #0 to host ssp.seznam.cz left intact
<?xml version="1.0" encoding="UTF-8"?><VAST version="4.0"><Ad><Wrapper><VASTAdTagURI><![CDATA[https://c-ng.seznam.cz/imp?k=43f4d19e-58a2-412b-9f78-9b0345ae5e51]]></VASTAdTagURI><Impression><![CDATA[https://ssp.seznam.cz/v2/impress?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&test=1&s=gyYvpeHF0U644gutgIh6]]></Impression><Impression><![CDATA[https://i.seznam.cz/miss?zoneId=seznam.pack.sponzor.poradu&count=1&r=IfPASHEUc97tm1pPX4c5V6gap10-2-1]]></Impression><Impression><![CDATA[https://i.seznam.cz/miss?zoneId=seznam.sport.sponzor.poradu&count=1&r=IfPASHEUc97tm1pPX4c5V6gap10-2-1]]></Impression><Error><![CDATA[https://ssp.seznam.cz/v2/miss?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&test=1&s=kHFrW9ZQNF416ZULz8gI]]></Error><Creatives><Creative><Linear><TrackingEvents><Tracking event="skip"><![CDATA[https://ssp.seznam.cz/v2/event?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&t=vast_skip&test=1&s=YhvBnkUIh9yHvcPYIzF-]]></Tracking><Tracking event="firstQuartile"><![CDATA[https://ssp.seznam.cz/v2/event?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&t=vast_Q1&test=1&s=L6sKsIljPRij9a2VQAMP]]></Tracking><Tracking event="midpoint"><![CDATA[https://ssp.seznam.cz/v2/event?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&t=vast_Q2&test=1&s=F3-Ph5HnH4SlQQo5cX7p]]></Tracking><Tracking event="thirdQuartile"><![CDATA[https://ssp.seznam.cz/v2/event?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&t=vast_Q3&test=1&s=XopbxBLiUUsJB2uL_40J]]></Tracking><Tracking event="complete"><![CDATA[https://ssp.seznam.cz/v2/event?r=0fbc9164-174a-4601-bf80-ee743da3bbbd&z=149465&i=0&sid=9078004996629498148&t=vast_Q4&test=1&s=hIpGagwIZbftakubLi-M]]></Tracking></TrackingEvents></Linear></Creative></Creatives></Wrapper></Ad></VAST>

Nativní reklama z Xandru

Požadavek na výdej nativní reklamy

Zápis požadavku na výdej nativní reklamy je stejný jako zápis pro jakoukoliv reklamu dodávanou jako data v objektu (JSON), například:

<div id="ssp-zone-12345"></div>

<script>
  sssp.getAds([
    {
      zoneId: 12345,
      id: 'ssp-zone-12345',
      width: 300,
      height: 250,
      callback: function (ads) {
        // JS pro zpracování dat, vykreslení reklamy a zobrazení měřicích pixelů
      },
    },
  ]);
</script>

Element div#ssp-zone-12345 je určený pro vykreslení reklamy callbackovou funkcí. Parametry width a height jsou v případě nativní reklamy bezpředmětné, ale kvůli validitě požadavku je třeba je uvádět (s libovolnými hodnotami) i v případě, kdy se do dané zóny vydává výhradně nativní reklama z Xandru. Pokud se střídá například s nativní reklamou z Skliku, použijí se rozměry nastavené v SSP rozhraní pro Sklik.
Výdej z Xandru v režimu nativní reklamy je podmíněný nastavením hodnoty „Typ média“ v základním nastavení zóny v SSP rozhraní na „Native“ (místo „Banner“). K tomuto nastavení je třeba mít oprávnění. Pokud typ sami změnit nemůžete, zašlete prosím tento požadavek na seznam.partner@firma.seznam.cz.

Struktura dat nativky z Xandru v bid requestu

V rámci bid requestu posílá backend SSP do Xandru níže uvedenou datovou strukturu JSON vyhovující specifikaci dle dokumentu OpenRTB Dynamic Native Ads API Specification Version 1.1 (iAB, 2016)¹.

Vždy požadujeme ("required": 1) dva obrázky:

1. ilustrační obrázek ("type": 3) s poměrem stran 1,91:1 a minimálními rozměry 880 × 460 px ("wmin": 880, "hmin": 460),
2. obrázek-ikonu ("type": 1) s poměrem stran 1:1 a minimálními rozměry 338 × 338 px ("wmin": 338, "hmin": 338).

Dále požadujeme dva textové řetězce:

1. nadpis o délce až 50 znaků ("len": 50),
2. popisek ("type": 2) o délce až 90 znaků ("len": 90).

{
 "native":{
  "ver":"1.1",
  "context":1,
  "contextsubtype":11,
  "plcmttype":1,
  "plcmtcnt":1,
  "assets":[
   {
    "id":1,
    "required":1,
    "img":{
     "wmin":880,
     "hmin":460,
     "type":3
    }
   },
   {
    "id":2,
    "required":1,
    "img":{
     "wmin":338,
     "hmin":338,
     "type":1
    }
   },
   {
    "id":11,
    "required":1,
    "title":{
     "len":50
    }
   },
   {
    "id":12,
    "required":1,
    "data":{
     "type":2,
     "len":90
    }
   }
  ]
 }
}

Příklad odezvy SSP obsahující nativní reklamu z Xandru (JSON)

Nativní reklama z Xandru se v odezvě SSP pozná podle specifické kombinace hodnot dvou položek:

• "type": "native"
• "dsp": "APPNEXUS"

{
  "requestId": "40e04ff7-fc73-45e2-a0ed-e05b8f1532d8",
  "ads": [
    {
      "data": "data odezvy z Xandru (viz níže)",
      "type": "native",
      "width": 0,
      "height": 0,
      "responsive": 1,
      "tracking": {
        "served": [
          "https://ssp.seznam.cz/v1/impress?r=40e04ff7-fc73-45e2-a0ed-e05b8f1532d8&z=179421&i=0&sid=16788573327959960715&s=3w_nrajmuDQ1KvIDOgbz"
        ],
        "visible": [
          "https://ssp.seznam.cz/v1/visibleimpress?r=40e04ff7-fc73-45e2-a0ed-e05b8f1532d8&z=179421&i=0&sid=16788573327959960715&s=rVqe0xLnPC_lXwLcFfPd"
        ]
      },
      "zoneId": 123456,
      "zoneName": "nativka.xandr",
      "dsp": "APPNEXUS",
      "iframe": 0
    }
  ]
}

Příklad dat odezvy z Xandru (hodnota položky data)

Stejné položky bid requestu a odezvy lze poznat podle totožné hodnoty identifikátoru id.

Obrázky:

1. ilustrační obrázek ("id": 1) s poměrem stran 1,91:1 dodán v rozměrech 1 200 × 627 px,
2. obrázek-ikona ("id": 2) s poměrem stran 1:1 dodán v rozměrech 338 × 338 px.

Textové řetězce:

1. nadpis ("id": 11) dodán v maximální délce 50 znaků (může být kratší),
2. popisek ("id": 12) dodán v maximální délce 90 znaků (může být kratší).

Položka link.url obsahuje URL cílové stránky s měřením prokliku, pole imptrackers pak URL průhledných obrázků 1×1 px pro měření zobrazení (obecně 0..n URL). Položka jstracker může obsahovat JS pro měření imprese. Měření impresí oběma způsoby je ekvivalentní, stačí tedy buď provolat URL v poli imptrackers, nebo provést skript z pole jstracker.

{
  "native": {
    "assets": [
      {
        "id": 1,
        "img": {
          "url": "https://s1.adform.net/Banners/Elements/Files/87415/7980265.jpg?bv=1",
          "w": 1200,
          "h": 627,
          "ext": {
            "appnexus": {
              "prevent_crop": 0
            }
          }
        }
      },
      {
        "id": 2,
        "img": {
          "url": "https://s1.adform.net/Banners/Elements/Files/87415/7980264.jpg?bv=1",
          "w": 338,
          "h": 338,
          "ext": {
            "appnexus": {
              "prevent_crop": 0
            }
          }
        }
      },
      {
        "id": 11,
        "title": {
          "text": "Kadeřnictví nedaleko centra je plné lidských osudů"
        }
      },
      {
        "id": 12,
        "data": {
          "value": "Otevřeně a s nadsázkou s vámi hrdinky seriálu Kadeřnictví sdílí své životní výhry i prohry"
        }
      }
    ],
    "link": {
      "url": "https://fra1-ib.adnxs.com/click?sZL1Thzy-T8mGVVFpJ_3P3sUrkfheoQ_JhlVRaSf9z…"
    },
    "imptrackers": [
      "https://fra1-ib.adnxs.com/it?an_audit=0&referrer=http%3A%2F%2Fwww.seznam.cz&e=wqT_3QLRC_BM0QUAAAM…",
      "https://fra1-ib.adnxs.com/ot?ps=d718f9945eccdaf75de9983304bd7ad7746b07c8&pe=wqT_3QJeAAAAAwDqAAZL1Thzy…"
    ],
    "jstracker": "<script type=\"text/javascript\" async=\"true\" src=\"https://cdn.adnxs.com/v/s/191/trk.js#v;vk=appnexus.com-omid;tv=native1-18hs;dom_id=%native_dom_id%;st=0;d=1x1;vc=iab;vid_ccr=1;tag_id=18409182;cb=https%3A%2F%2Ffra1-ib.adnxs.com%2Fvevent%3Fan_audit%3D0%26referrer%3Dhttp%253A%252F%252Fwww.seznam.cz%26e%3DwqT_3QLRC_.%26s%3D78c867ac1a90814473f7b562d10e064c31cdec67;ts=1595321514;cet=0;cecb=\">"
  }
}

Zdroje

[1] OpenRTB Dynamic Native Ads API Specification Version 1.1. Iab.com [online]. New York: IAB, 2016 [cit. 2020-08-04]. Dostupné z: https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf.

Měření spenttime pro vlastní monetizaci

Pokud jako partner s vlastní monetizací reklamního prostoru nemáte na svém webu nasazenou reklamu od Seznamu, je třeba do zdrojového kódu svého webu vložit skript https://ssp.seznam.cz/static/js/ssp.js, který zajistí měření času stráveného uživatelem návštěvou stránky (článku).
Skript ve výchozí konfiguraci měří čas strávený uživatelem na konkrétním článku na webu partnera pouze tehdy, pokud uživatel na stránku s článkem přijde proklikem přes odpovídající odkaz v newsfeedu na Seznam.cz, a to po dobu platnosti session uživatele po takovém prokliku.

Vložení skriptu do stránky

Skript není třeba nijak konfigurovat. Pro správné měření spenttime stačí, když se nachází na správném místě zdrojového kódu stránky. Následující kód vložte do HTML hlavičky všech stránek s články, tj. mezi tagy <head> a </head>:

<script type="text/javascript" src="https://ssp.seznam.cz/static/js/ssp.js"></script>

Příklad správného vložení skriptu

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, width=device-width" />
    <title>Partnerská stránka</title>
    <script type="text/javascript" src="https://ssp.seznam.cz/static/js/ssp.js"></script>
  </head>
  <body>
    ...
  </body>
</html>

Specifika Single-Page Application (SPA)

V případě jednostránkového webu (SPA), kdy je veškerý obsah řízen jednou stránkou a směrování je řešeno čistě uvnitř webové aplikace, je třeba dodatečně informovat SSP.

Nastavení PageViewId

Pro nastavení správné hodnoty měření PageViewId je třeba zavolat window.sssp.setPageViewId() při každé změně obsahu. Díky tomu můžeme v rozhraní SSP zobrazit správná data ohledně počtu monetizovaných PageView.

Vkladání tlapiček k reklamním pozicim

window.sssp.getPawHTML(ad)

Po zavolání metody vrátí se HTML element tlapičky obsahující také proklikové url. V případě, kdy reklama z SSP serveru bude obsahovat DSP typ Sklik, OGAR & ONEGAR metoda vrátí null.

Příklad použití

JavaScript soubor

// reklama z SSP serveru
const ad = sssp.getAds({
  zoneId: 123456,
  id: 'elm-123456',
});

// HTML element tlapičky
const pawHTML = window.sssp.getPawHTML(ad);

window.sssp.appendPawToElement(ad, element)

Vytváří HTML element tlapičky a následně ho vkládá do zvoleného HTML elementu. V případě DSP typu Sklik, OGAR & ONEGAR a/nebo nevalidního HTML elementu, konání metody se zastaví.

Příklad použití

HTML soubor

<!--HTML element, kam by měla být vložena tlapička-->
<div id="element"></div>

JavaScript soubor

// HTML element, kam vložíme tlapičku
const element = document.querySelector('element');

// reklama z SSP serveru
const ad = sssp.getAds({
  zoneId: 123456,
  id: 'elm-123456',
});

// vkladání tlapičky do HTML elementu
window.sssp.appendPawToElement(ad, element);

DSP setting

Umožní nastavení DSP pomocí query v url adrese.

Příklad multirequestu

Nastavení url query parametru

Request payload

{
  "zones": [
    {
      //"zoneId", které se shoduje s ssp_zoneId-1 hodnotou v url
      "zoneId": 60725,
      // "width" modifikovaná na základě ssp_width-1=3000 argumentu v url
      "width": 3000,
      "height": 210,
      "minWidth": 0,
      "minHeight": 0,
      "contentId": "",
      "options": {},
      // vložený klíč preview
      "preview": {
        //vložený klíč a hodnota na základě ssp_adType-1=adType1 argumenu v url
        "adType": "adType1",
        //vložený klíč a hodnota na základě ssp_dsp-1=Ogar argumenu v url
        "dsp": "Ogar",
      },
    },
    {
      //"zoneId", které se shoduje s ssp_zoneId-2 argumentem v url
      "zoneId": 47629,
      // "width" modifikovaná na základě ssp_width-2=4000 argumentu v url
      "width": 4000,
      // "width" modifikovaná na základě ssp_height-2=4000 argumentu v url
      "height": 4000,
      "minWidth": 0,
      "minHeight": 0,
      "contentId": "",
      "options": {},
      // vložený klíč previews obsahujíci hodnoty z url argumentu
      "preview": {
        //vložený klíč a hodnota na základě ssp_adType-2=adType2 argumenu v url
        "adType": "adType2",
        //vložený klíč a hodnota na základě ssp_dsp-2=Onegar argumenu v url
        "dsp": "Onegar",
      },
    // ostatní zóny nejsou modifikovány, protože jejich "zoneId" není zadáno v url argumentu ssp_zoneId-"číslo"
    {
      "zoneId": 47629,
      },
    },
  ];
}

Příklad single requestu

Request payload

{
  "zones": [
    {
      //"zoneId", které se shoduje s ssp_zoneId argumentem v url
      "zoneId": 60725,
      // "width" modifikovaná na základě ssp_width=3000 argumentu v url
      "width": 3000,
      "height": 210,
      "minWidth": 0,
      "minHeight": 0,
      "contentId": "",
      "options": {},
      // vložený klíč previews obsahujíci hodnoty z url argumentu
      "preview": {
        //vložený klíč a hodnota na základě ssp_adType=adType argumenu v url
        "adType": "adType",
        //vložený klíč a hodnota na základě ssp_dsp=Ogar argumenu v url
        "dsp": "Ogar",
      },
    },
    // ostatní zóny nejsou modifikovány, protože jejich "zoneId" není zadáno v url argumentu ssp_zoneId-"číslo"
    {
        "zoneId": 47629,
    },
  ];
}