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

Název	Hodnota	Popis
id	String, Node	Identifikátor HTML elementu ve stránce
zoneId	Number	Unikátní identifikátor zóny v SSP serveru
width	Number	Maximální šířka místa pro reklamu
height	Number	Maximální výška místa pro reklamu
minWidth	Number	Minimalní rozměr (šířka) reklamy
minHeight	Number	Minimalní rozměr (výška) reklamy
elements	Array	Pole prvků, kam lze vypsat reklamu, a jejich rozměrů
serviceId	String	Definuje Seznam Partner
contentId	String	Generuje příslušná služba, musí být zajištěna unikátnost
callback	Function	SSP zavolá tuto funkci, jakmile obdrží odpověď z SSP serveru
options	Object	Doplňující konfigurace zóny
options : section	String	Pro IM: sekce reklamy
options : collocation	String	Pro IM: klíčové slovo
options : passons	String	Pro IM: parametry předávané do banneru
options : flags	String	Pro IM: flagy pro šablony bannerů
options : jsonPreloadDisabled	Function	Pro typ reklamy json_url vypne automatické stažení JSON
options : infoCallback	Function	Zavolá se pro každou reklamní pozici poté, co se získají data z SSP
options : infoErrorCallback	Function	Zavolá se pro každou reklamní pozici, která je nesprávně nakonfigurovaná
options : noSize	Boolean	Pokud je nastaveno na true, SSP nebude vyžadovat rozměr u pozice
options : nativeTemplate	Number [1,2]	Definuje šablonu (template) pro danou pozici
options : nativeVersion	Number [0,1,2]	Definuje verzi native protokolu pro danou pozici
options : sfExpandZIndex	Number	Hodnota z-index pro expandující překrývající banner, implicitně 1
options : cid	Array	Pole id reklam které už byly použity (typu string a maximální délce 10)
options : disableScaling	Boolean	Pokud je nastaveno na true, SSP nemění velikost u neresponsivních reklam
options : tags	Array	Pole klíčových slov pro podporu dodatečného cílení na umístění v DSP
options : reloadCount	Number	Počet reloadů reklamní zóny
options : doNotParseVastData	Boolean	V rámci VAST callbacku definuje, zda se mají parsovat vastová `data`

Povinné položky pro konfiguraci pozice jsou:

zoneId
id nebo callback
width nebo height nebo oba

id

Identifiká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í:

HTML element má nenulové rozměry – jak šířku, tak výšku (nemusí se zadávat rozměry v konfiguraci)
HTML element má nulové rozměry (alespoň jedna z hodnot musí být zadána v konfiguraci)
Rozměry jsou zadané v konfiguraci a zároveň má HTML element nenulové rozměry (použijí se rozměry z konfigurace)
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.im.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.im.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().

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 povinný parametr

options : nativeVersion

Hodnota definuje, kterou verzi použít při řádosti o nativní reklamu

nativeVersion: 0 - defaultní verze (Xandr 1.0, Pubmatic 1.1)
nativeVersion: 1 - verze 1.1
nativeVersion: 2 - verze 1.2

options : reloadCount

Počet dosavadních reloadů dané reklamní zóny. Inkrementuje se, když opakovaně voláte getAds v rámci jednoho načtení stránky.

Přehled nastavení zóny

Nastavení objektu zóny​

id​

zoneId​

width a height​

Možné varianty chování:​

minWidth a minHeight​

elements​

serviceId​

contentId​

callback​

options : section​

options : collocation​

options : passons​

options : flags​

options : infoCallback​

options : infoErrorCallback​

options : noSize​

options : nativeTemplate​

options : nativeVersion​

options : reloadCount​