Práce s Sklik API

• Aktuálně dostupné protokoly Sklik API Drak
• Dostupné třídy metod API Sklik Drak
• Základní metody
• Důležité novinky o Sklik API
• Znalostní báze
• Přihlašování a uživatelé
• Reporty
• Dostupnost statistik
• Statistiky za aktuální den
• Vlastní seznamy uživatelů v API
• Propojení s Firmy.cz
• Nastavení komunikace pro práci s klíčovými slovy

Aktuálně dostupné protokoly Sklik API Drak

S API rozhraním je možné komunikovat pomocí dvou protokolů:

• XML-RPC – Z uživatelské pohledu se jedná o značně komplikovanější protokol, který ve většině jazycích nemá velkou podporu nativních knihoven. Tento protokol máte také problém s velkými čísly. Viz komplikace s klíčovými slovy.

• JSON – Jedná se modernější protokol. Práce s ním je mnohem snadnější a z naší strany je preferovanější variantou.

Dostupné třídy metod API Sklik Drak

• Ads – Správa reklam a jejich přehledy.
• Api – Informace o aktuálně používané verzi API.
• Autotagging – Nastavení automatického tagování proklikové URL o informace o zdroji reklamy.
• Banners [Obsahová síť] – Správa bannerů a jejich přehledy.
• Campaigns – Správa kampaní a jejich přehledy.
• Client – Informace o uživateli, včetně účtů, které spravuje.
• Contextnetwork [Obsahová síť] – Obsahové sítě (CZ, SK).
• Conversions – Správa konverzních kódů.
• Group – Správa sestav a jejich přehledy.
• Images – Správa obrázku (pro použití v bannerech nebo kombinované reklamě).
• Intends[Sestava|Obsahová síť] – Správa zájmů o koupi včetně vyloučení a jejich přehledy.
• Interests[Sestava|Obsahová síť] – Správa zájmů včetně vyloučení a jejich přehledy.
• Keywords – Správa klíčových slov včetně vylučujících a jejich přehledy.
• Partner – Správa inzerentských ploch (určeno pro členy Seznam.cz Partner).
• Patterns [Sestava|Obsahová síť] – Správa umístění reklamy v obsahové síti.
• Productsets – Přehledy produktových skupin (v rámci produktových kampaní).
• Queries[Vyhledávací síť] – Přehledy vyhledávacích dotazů.
• Retargeting – Nastavení retargetingu.
• Sharedbudgets – Správa sdíleného rozpočtu.
• Sitelinks[Vyhledávací síť] – Správa Sklik Odkazů s jejich přehledy.
• Themes [Sestava|Obsahová síť] – Nastavení zobrazování na tematických webech.

Základní metody

• create – Vytvoření nové entity.
• check – Identická struktura jako metoda create. Je možné si ověřit, že bude vytvořeno vše v pořádku.
• remove – Smazání entity.
• restore – Obnovení smazané entity do stavu před smazání. Pokud byla entita pozastavena, restore tento status nezmění.
• update – Upravuje parametry entity. Pokud jde o změnu samotného obsahu reklam, update ji neupraví, ale vytvoří novou entitu (a původní smažou). Nová entita prochází stejným schvalovacím procesem jako při nově vytvořené.
• createReport – První část dvoufázového čtení reportů. Zde definujete výběr dat.
• readReport – Samotné čtení reportů, musí následovat po createReport.

Důležité novinky o Sklik API

O všech důležitých událostech (výpadcích, změnách nebo připravovaných novinkách) nyní budeme informovat i prostřednictvím Sklik API newsletteru. Stačí zanechat e-mail a nic důležitého vám neuteče.

Přihlášením k odběru novinek nám udělujete souhlas se zpracováním osobních údajů.

Znalostní báze

Changelog

Připravili jsme pro vás veřejný changelog. V něm naleznete všechny provedené změny na rozhraní, včetně oprav chyb a přidávání nových funkcí.

Dodržujeme verzovací standard Major.Minor.Patch.

Changelog

Statusy entit

Status (aktivní, pozastavená, smazaná) je přiřazen pouze dané entitě. Ovšem vliv má na všechny nižší entity pod ní spadající.

Například pokud pozastavíte vybranou kampaň (změníte status u kampaně jako pozastavená), všechny sestavy i reklamy si zachovají původní status, ale zároveň respektují status nadřazené entity – kampaně. Proto se všechny reklamy v dané kampani chovají jako pozastavené a nebudou se zobrazovat. Při dotazu pomocí API vám však budou hlásit, že mají status aktivní.

Práce s časem

Rozhraní využívá pro parametry data standardní formát datetime. Ten nabízí možnost zadávat nejen datum, ale i konkrétní čas.

Obecně se dá říct, že vynecháním času ve struktuře datetime nic nezkazíte. I na webovém rozhraní lze pracovat pouze s přesností na dny a je to nejnižší granularita, kterou v práci s účty garantujeme.

• Datetime u createReportu vrací statistiky vždy za celý den. Zahrnují oba dny, které nastavují rozmezí.

• Datetime u nastavení začátku a konce kampaní je naopak možné naplánovat na minutu přesně, tuto přesnost však nijak negarantujeme. Jak se kampaně chovají při nastavení pouze datumu: v nastavený den se kampaň spustí i ukončí na začátku dne (o půlnoci).

{"dateFrom" : datetime.strptime("1.1.2017", "%d.%m.%Y"),
"dateTo" : datetime.strptime("23.11.2018", "%d.%m.%Y")}

Přihlašování a uživatelé

Způsoby přihlášení

API Drak nabízí možnost přihlášení přes API token, pomocí kterého se přihlásíte přes metodu client.loginByToken. API token získáte v rozhraní Sklik.cz v záložce Nastavení účtu.

Přihlášení pomocí tokenu je nejbezpečnější. Odděluje přístup k API a vašemu účtu. Umožňuje věnovat přístup k API dalším lidem ve firmě, nebo třetím stranám, aniž byste museli prozrazovat svoje heslo. Je také možné vygenerovat nový token a tím zabránit přístupu všem, kteří nemají token stávající.

p.client.loginByToken("0x577ab56fd48c7...@seznam.cz")

Uživatelé

Než někomu dávat API klíč, je z důvodu snadné správy přístupů a tím vyšší bezpečnosti vhodnější udělit přístup. Postupujte dle nápovědy. Pro reporting statistik bez možnosti cokoliv měnit je vhodný přístup Reportér statistik. Pokud je třeba přes API kampaně upravovat nebo jakékoliv položky v účtu přidávat, je potřeba aby měl uživatel schválený přístup na úrovni Správce kampaní.

Uživatel s přiděleným přístupem se do API přihlásí pomocí svých přístupových údajů. Aby mohl editovat a pracovat s vaším účtem, musí při volání každé metody vkládat parametr user.userId (ID vašeho účtu). Pokud nebude tento parametr vyplněn, bude API přistupovat k aktuálně přihlášenému účtu, i když v něm nebudou žádné kampaně.

Získání userId

Metoda client.get vrací všechny informace o vlastním účtu i účtech spojených s ním. Reponse vrací ID vlastního účtu user.userId a ID všech spojených účtů foreignAccounts[].userId

Reporty

O získávání veškerých statistik účtu se stará dvojice metod createReport a readReport. Více o práci s reporty zjistíte na našem Seznam blogu.

createReport

Vytvoří přehled dat, které je s pomocí návratové hodnoty reportId možné číst readReportem. Přehled je po vytvoření dále neměnný a zachovává se u něj pořadí dat.

Příklad createReportu a odpovědi server

 p.campaigns.createReport({'session': '10XEBV...AzNWM=', 'userId': 11111},{
                "statisticsConditions": [{
                       "columnName":"clicks",
                       "operator": "GT",
                       "intValue": 10
                }],
                "dateFrom": datetime.strptime("01.05.2018", "%d.%m.%Y"),
                "dateTo": datetime.strptime("31.05.2018", "%d.%m.%Y")
        })

{'status': 200, 'totalCount': 19, 'session': '10XEP...NWM=', 'reportId': 'bqr...cmVv)75ed284', 'statusMessage': 'OK'}

readReport

Slouží ke čtení vytvořeného přehledu (createReport). Parametry je možné pouze omezit data (sloupce, řádky), ale není možné provádět žádné filtry jako omezení podle kampaní, hodnoty dat a jiné. Výjimkou je allowEmptyRows, která vynechává nulové záznamy (toto vynechávání je defaultně povoleno).

Stránkování

U reportů často nastává situace, že záznamů je velké množství. Aby nedošlo k přetížení sítě, je server nastaven na omezené množství přenesených dat. Tento limit serveru zjistíte jako chybovou návratovou hodnotu u chyby typu 413, která se vrátí, pokud tento limit překročíte. Standardně u reportů je nastavena na hodnotě 5 tisíc řádků.

p.campaigns.readReport({'session': '10XEBV...AzNWM=', 'userId':11111},'bqr...cmVv)75ed284', {
                        "offset":0, 
                        "limit":1000, 
                        "allowEmptyStatistics": False,                        
                        "displayColumns": ["name",'totalMoney', 'clickMoney', 'totalClicks', 'impressions', 'clicks']
                })

Jak stránkovat

Pro stránkování slouží parametry limit a offset (stejné vlastnosti jako SQL dotazy). Limit udává maximální množství záznamů, které chcete získat. Hodnotu můžete nastavit libovolně, pouze vrchní hranice je určena serverem (viz výše).

Offset slouží jako stránkovač. Hodnota říká, od jakého záznamu chceme záznamy číst.

Granularita

Limit ovlivňuje i granularita (výpis dat po dnech, týdnech, měsících, kvartálech a rocích). V takovém případě je maximální limit podílem počtem dnů.

p.campaigns.createReport({'session': '10XEBV...AzNWM=', 'userId': 11111},{                
                'dateFrom': datetime.strptime("01.05.2018", "%d.%m.%Y"),
                'dateTo': datetime.strptime("31.05.2018", "%d.%m.%Y") 
                },
                {'statGranularity': 'daily'}
        )

parametr allowEmptyStatistics

Výstupy může značně ovlivnit parametr allowEmptyStatistics. Ten je v základu nastaven na hodnotě false. To znamená, že při posílání záznamů server vynechává nulové řádky. Avšak při počítání limitů a offsetů se tyto nulové záznamy započítávají, jen se neposílají uživateli. Proto může nastat situace, že při nastavení limitu 200, server vrátí jenom 150 záznamů. 50 chybějících jsou nevypsané nulové záznamy.

Více o přístupu ke statistikám na našem blogu – Jak správně používat limit a offset v metodách pro statistické reporty v API Drak

Dostupnost statistik

Statistiky za aktuální den jsou pouze orientační. V průběhu dne mohou vznikat v datech nepřesnosti, které mohou čísla zkreslovat. Z tohoto důvodu na konci každého dne spouštíme script, který data znova přepočítá a případně opraví. Tento script většinou doběhne kolem 4:00h hodiny ráno. Ve výjimečných případech se script opozdí, nebo je přerušen chybou, která potřebuje zásah ze strany vývoje.

Na API Drak je k dispozici nová metoda – stats.status. Tato metoda k dotazovanému datu vrací informaci o stavu statistik. Můžete se tak informovat nejen na uplynulý den, ale i několik dnů zpět.

Metoda vrací pro každý den tři možné stavy:

• preparing: Říká, že data se ještě nezačala přepočítávat, nebo právě přepočítávání probíhá
• complete: Data pro daný den jsou finální a již dále se nebudou měnit
• error: Při přepočítávání nastal problém. Čas, jak dlouho se bude problém odstraňovat, není možné bohužel říct. Vždy záleží na důvodu vzniku. Proto prosím mějte trpělivost.

Metoda stats.status dává informaci o stavu dat na naší straně. Tedy zde platí pro všechny účty shodně. Není možné, aby pro např. účet A byla data complete, a zároveň pro účet B měla data error, nebo se teprve připravovala.

Statistiky za aktuální den

Jak získat aktuální statistiky

Přístup k aktuálním statistikám je možné stejnou cestou jako dosavadní statistické reporty. Pomocí metody createReport vytvoříte report (nastavíte patřičné hodnoty). Data následně přečtete metodou readReport. Statistiky za aktuální den získáte rozšířením datového rozptylu o dnešní den (a to buď pouze do atributu dateTo – pokud chcete data historická a aktuální, nebo do obou – dateTo a dateFrom, pokud požadujete pouze aktuální den). Navíc je třeba zapnout parametr includeCurrentDayStats v metodě createReport ve struktuře displayOptions.

Interpretace získaných dat

• V první řadě je třeba zdůraznit, že data mohou obsahovat procentuální nepřesnosti. Jedná se o rychlá data, která neprošly přepočty a kontrolou a mohou se tedy mírně lišit oproti skutečnosti. Velikost odchylky a zda vůbec nastala, není nijak daná a jedná se pouze o výsledek zanesení chyb, které způsobují systémy při rychlém zpracovávání dat. Odchylka se pohybuje většinou do 5% celkové hodnoty.
• Data jsou absolutní inkrement od začátku dne. Není tedy možné zjistit statistiky za určité časové okno, ale pouze data od začátku dne.
• Data přibývají skokově a to přibližně každou hodinu. Doba započtení dat není pevně stanovená. Není tedy možné sledovat přesně hodinu po hodně, ale pouze přibližný trend nad entitami v průběhu dne.
• Data se mohou časově lištit oproti webovému rozhraní. Z důvodu rozdílných přístupů k databázím, bývají časové prodlevy mezi zobrazením nového přírůstku na webu a v API rozdílné.

Vlastní seznamy uživatelů v API

Přes API Drak lze s vlastním seznamem uživatelů pracovat pomocí metod zažínající notací retargeting.emails, kde většina metod i funkcí vychází z klasického retargetingového seznamu.

Specifická práce, oproti klasickým seznamům, je pak při nahrávání či mazání emailových adres pomocí metod addEmail a removeEmail. Na těchto metodách není nastavený limit na počet entit. Je tedy možné zde nahrát více než 5000 emailů v rámci jednoho volání. Avšak u větších requestů nemůže systém garantovat stabilitu a může docházet k výpadkům či selháním u přenosu. Je tedy doporučené využívat metody s omezením na řádově nižší desítky tisíc emailů.  

Zpracování fronty, návratový http stav 406 a diagnostika rus_process_is_already_running

Rozhraní API Drak pro přidávání a odebírání nových emailů je primárně určeno pro pravidelné aktualizace seznamů. Tedy přidání emailu hned, jakmile jej získáte, nebo pravidelný denní update. Vytvářet přes API inicializační seznamy v řádech několik desítek či statisíců emailů, může být poměrně touto formou, poměrně komplikované.  

Jakmile zavoláte poprvé metodu addEmail nebo removeEmail, spustí se jeho zpracování a daný seznam se zamkne. A to do doby, než se zpracování tohoto seznamu dokončí. Dokud zpracování běží, pak API Drak vrací status 406 se zprávou rus_process_is_already_running. Délka zpracování pak závisí na počtu emailů a kapacitách na serveru. Průměrně zpracováváme 90 emailů za sekundu, ale délka zpracování může být až 1s na email.

Propojení s Firmy.cz

Nastavení spojení

Stejně jako v rozhraní Skliku je možné i prostřednictvím API propojit kampaně s Firmy.cz (a následně i jednotlivé inzeráty). Rozšíření inzerátu o adresu

Spojení s Firmy.cz je potřeba nejdříve nastavit na úrovni kampaně. V metodě campaigns.create v poli campaigns je třeba vyplnit strukturu premise.

ID – ID dle katalogu Firmy.cz. Toto ID lze zjisti například z URL adresy vaší firmy. Pro firmu Seznam.cz je ID 155088. Její URL adresa je – https://www.firmy.cz/detail/155088-seznam-cz-praha-smichov.html

Nastavení jednotlivých poboček lze nastavit buď jako defaultId taktéž v campaigns.create, nebo pak až na úrovni vytváření reklam v metodě ads.create kde v poli ads je třeba vyplnit premiseId.

Opět zde zadáváte ID jednotlivých poboček. Toto id zjistíte stejně jako id celé firmy. Stačí si kliknout na seznam poboček a podívat se na její URL. Brněnská pobočka Seznam.cz má ID 429645 a její URL je https://www.firmy.cz/detail/429645-seznam-cz-brno-styrice.html

p.campaigns.create({'session': '10XEBV...AzNWM=', 'userId': 11111}
    [{'status': 'active', 
        'dayBudget': 3000, 
        'name': 'Name of new campaigns2', 
        'targetDevices': {'mobile': True, 'other': True, 'tablet': True, 'desktop': True},
        'type': 'fulltext',
        'adSelection': 'weighted',
        'premise': {
                'id': 155088,
                'defaultMode': 'one',
                'defaultId': 429645
                }
        }])

p.ads.create({'session': '10XEBV...AzNWM=', 'userId': 11111}
        [{
                'adType':'eta',
                'headline1': 'Text of headline1',
                'headline2': 'Text of headline2',
                'description': 'Some description',
                'finalUrl':'http://www.napoveda.sklik.cz',
                'premiseMode':'one',        
                'premiseId': 429645,        
                'groupId': 78288473,
        }])

Nastavení komunikace pro práci s klíčovými slovy

Počet klíčových slov, které u nás evidujeme, překročil hranici 2 mld. a protože každému klíčovému slovu přiřazujeme unikátní identifikátor, tato hodnota přesáhla hranice základního 4 bytového INT (základní celočíselný datový typ). Dosažení hranice není pro náš systém komplikací, avšak vytváří nutnost provést úpravu v nastavení protokolu XML-RPC, který ke komunikaci s API Drak využíváte.

Situace vzniká pouze při používání XML-RPC protokolu, pokud v dotazu nebo následné odpovědi se vyskytují ID klíčových slov, které mají hodnotu vyšší (2147483647). Tyto ID se začaly přiřazovat všem klíčovým slovům od pátku 16. 11. 2018.

Jelikož je problém spojen s protokolem, který používáte ke komunikaci s naším API Sklik, musí dojít ke změně na vaší straně. Změny se mohou lišit v závislosti na jazyce a používané knihovně. Nabízíme 3 postupy, které je možné využít při řešení nynější situace.

Zvýšit verzi XML-RPC

Protokol je ze základu nastaven na verzi 1.0 a v ní je možné využít jenom datový typ , který bohužel má již zmíněný limit. Zvýšením verze protokolu na 2.1 se tento problém odstraní. Struktura dat zůstává úplně stejná.
Změnu verze protokolu nastavíte v hlavičce komunikace přidáním protocolVersion.

<?xml version="1.0"?>            
            <!--protocolVersion="2.1"-->
            <methodCall>

Povolit pro protokol enabledForExtensions.

Některé knihovny pro práci s XML RPC mohou mít nastavení, které umožňují rozšířený datový typ. Tohle nastavení se většinou jmenuje jako enabledForExtensions.

Začít používat syntaxi JSON.

Samotný protokol XML RPC má s takto velkými čísly problém a proto může být nejrozumnější variantou začít používat lépe škálovatelný a modernější JSON. Ne vždy je přechod tak jednoduchý, ale například u Pythonu při používání externích knihoven se jedná o malé úpravy.

Kontaktování technické podpory

Pokud jste narazili na nějaký problém, který se vám nedaří odstranit, doporučujeme kontaktovat naši podporu. Prosíme vás vždy o přiložení základních informací, které s problémy kolem API potřebujeme:

• ID (nebo e-mail) účtu, se kterým pracujete
• Požadavek na server
• Odpověď serveru
• Čas – čím přesnější čas výskytu situace zašlete, tím spíše usnadníte její rychlé vyřešení.