PodporaZnalostní báze

Plug-iny

Plug-iny rozšířují již tak rozsáhlé možnosti šablonovacího jazyka. Jeho součástí je rozsáhlé množství plug-inů, jež umožňují pokročilé operace od “dumpování” dat, přes matematické funkce, práci s datem a časem až po formátování. Jsou zde však i specifické plug-iny Mailkitu, které umožňují specifické operace přístupu a manipulace s daty a to jak interními, tak přístupu k datům z externích systémů..

use_dbi

Tento plug-in umožňuje připojit  SQL datové zdroje do šablon, aniž by bylo nezbytné datový zdroj k šabloně přiřadit. To může např. zjednodušit migraci šablon, či jejich distribuci, bez nutnosti manuálního zásahu do nastavení šablony, nebo využít napojení datového zdroje u kampaní, které nevyužívají chytré šablony ale Vizuálního tvůrce. Připojení datového zdroje pak lze provést dvěma způsoby:

  • s použitím názvu datového zdroje: [% 'jmeno_datoveho_zdroje' | use_dbi -%]
  • s použitím ID datového zdroje: [% 'ID_datoveho_zdroje' | use_dbi -%]

Další postup použití SQL datového zdroje pomocí plug-inu DBI je následně stejné jako pokud by zdroj byl k šabloně přiřazen v nastavení šablony. Kdybychom tedy chtěli použít datový zdroj Sortiment, který má ID 1234, příklad by vypadal takto:

[% '1234' | use_dbi -%]
[% USE dbh_sql = DBI (dbh = shared.DBI_DS_SQL_SORTIMENT) -%]
[% query_items = dbh_sql.prepare('SELECT * FROM ds_1234_nazev_tabulky ORDER BY RAND() LIMIT 5') %]
[% items = query_items.execute () -%]
[% FOREACH items -%]
    <pre>[% USE Dumper; Dumper.dump(items) -%]</pre>
[% END -%]

Tento ukázkový kód připojí SQL databázi datového zdroje s ID 1234 a následující příkazy vypíší 5 náhodných záznamů z tabulky. Pro účely vypsání dat je použit plug-in Dumper, který vypisuje datovou strukturu.

Events

Podobnou situací, jako výše uvedené připojení databáze, jsou i data získaná z Eventů. Tato data jsou automaticky k dispozici v datových strukturách remarketingových kampaní, jež na Eventy reagují, ale často se může hodit přístup k těmto datům z běžných kampaní.

Právě k tomu slouží plug-in Events, který umožňuje přistupovat k těmto datům. Data lze pomocí tohoto plug-inu získat následujícím způsobem:

[% USE Events(tag => 'cart', status='open', limit=> 5) -%]

Plug-in má 3 parametry:

  • tag – určuje tag Eventů, které nás zajímají
  • status – pro určení stavu eventů
  • limit – pro omezení počtu eventů příjemce, které se mají vrátit 

Jediným povinným parametrem je tag, bez jehož uvedení se vrátí pouze netagované události. V případě chybějícího parametru status je výchozí hodnotou “open” a pokud neuvedeme limit, bude výstup omezen na maximálně 20 posledních událostí daného příjemce.

Poté si můžeme nechat zobrazit obsah smyčkou FOREACH:

[% FOREACH Events.data -%]
    Date: [% modify_date -%]
    [% FOREACH EventItems -%]
        Name: [% name -%]<br>
    [% END -%]
[% END -%]

V tomto příkladu vypíšeme datum poslední změny události a následně názvy všech položek v dané události.

Protože eventy jsou vázané na konkrétního příjemce, tak i plug-in vždy vrátí data pouze pro aktuálního příjemce. Proto, pokud se podíváte na náhled šablony, nikdy neuvidíte žádná data – náhled šablony totiž nemá příjemce. Pro testování vaší implementace je proto nezbytné testovat v náhledu kampaně, ve kterém vyberete příjemce, o němž víte, že má v událostech odpovídající data. 

POZOR: I v případě, že nechceme vypisovat žádná data z eventu, jej musíme stále použít, protože jinak se nedostaneme k datům z položek. Pak by zápis vypadal takto:

[% FOREACH Events.data -%]
    [% FOREACH EventItems -%]
        Name: [% name -%]<br>
    [% END -%]
[% END -%]

Recombee

Jak již název napovídá, tento plug-in slouží k získávání rekomendací z nástroje Recombee. Tato doporučení pak pro individuální příjemce vrací v reálném čase – ať už se jedná o náhled kampaně, nebo odesílání. Doporučení se vrací v podobě pole se seznamem ID doporučených produktů. Produkty pak podle těchto ID lze získat z SQL datového zdroje a vložit do zprávy. Alternativně lze využít parametr returnProperties, který vrátí kompletní informace o produktech tak, jak je zná Recombee z vašeho produktového feedu a přímo vkládat do těla zprávy.

Při vkládání rekomencací je však vždy důležité myslet na to, že rekomendační systém nemusí vrátit pro daného příjemce žádná doporučení – např. proto, že daného příjemce zatím nezná nebo pro něj nemá dostatek dat. S dostatkem dat pak souvisí i variabilita počtu doporučení – uvedením počtu požadovaných doporučení se stanovuje horní limit, nikoliv fixní počet – může se tak snadno stát, že pro některé příjemce bude méně doporučených produktů a je proto důležité na to ve vaší šabloně myslet.

V neposlední řadě je pak nutné myslet i na to, že použití tohoto filtru ovlivňuje rychlost rozesílání, protože pro každého příjemce se musí vyžádat data z Recombee. Z toho vyplývá, že doporučení (rekomendaci) je dobré používat u kampaní s malými objemy a jasným cílením, jako je třeba opuštěný košík nebo kampaň, která je odeslána na malý segment příjemců. Naopak použití doporučení u hromadných kampaní, které se odesílají na desítky či stovky tisíc příjemců, doporučujeme důkladně zvážit přínosy a vliv na rychlost doručení.

Získání dat do šablony pak probíhá následovně:

[% USE Recombee(
    database => 'name', # required
    count => <int>, # desired recommendation (defaults to 1)
    scenario  =>  recombee scenario, # see recombee UI for parameter descriptions
   cascadeCreate => <boolean>,
   returnProperties => <string list>,
   filter => <string>,
   booster => <string>,
   logic => <string/object>,
   minRelevance => <string>,
   rotationRate => <decimal>,
   rotationTime => <decimal>,
) -%]


    [% FOREACH Recombee.data.recomms -%]
        <div><a href="[% values.URL -%]">[% values.PRODUCT -%]</a></div>
    [% END -%]

Jediným povinným parametrem je database pro uvedení názvu databáze v Recombee. Ostatní parametry pak odpovídají funkci Recommend Items to User jež je popsána v dokumentaci Recombee. Struktura dat vrácených plug-inem pak opět odpovídá struktuře dat z API Recombee.

Fetch

Častým požadavkem u kampaní je možnost do šablony vložit obsah, jež by byl aktuální v okamžiku odesílání pro daného příjemce. Nejčastějším případem jsou např. slevové kódy, kurzy měn, předpovědi počasí a podobně.

Právě k tomu slouží plug-in Fetch, který umožňuje načíst do šablony data z externí URL. Obsah získaný plug-inem je automaticky detekován podle typu obsahu (content-type) a v případě, že typ obsahu je ve formátu JSON (application/json), nebo XML (application/xml), pak proběhne automatické dekódování obsahu do datové struktury, ke které lze následně přistupovat jako ke strukturovaným datům. V případě, že nebude identifikován jeden z těchto formátů, bude obsah získaný z uvedené URL dostupný ve formě řetězce.

Fetch lze použít za těchto podmínek:

  • URL odpovědi nesmí být delší než 4 kB
  • automatický tvrdý timeout 1 vteřina na odpověď
  • URL musí být zabezpečená protokolem https a platným validním certifikátem serveru
  • maximálně jedno přesměrování URL

Tyto podmínky jsou dány jak nutností zabezpečení přenosu dat, tak i výkonovými požadavky. Tím, že Mailkit generuje zprávy obrovskou rychlostí, je nutné, aby server, ze kterého se získávají data, dokázal odpovídat na stovky až tisíce dotazů za vteřinu, protože pokud by server neodpověděl, e-mail by odešel bez dat, která by server měl poskytnout.

Plug-in se používá následovně:

[% USE Fetch(url => 'https://vasedomena.cz/zdroj.json', username=> 'jmeno', password=> 'heslo'); -%]

Jediným povinným parametrem je URL, ze které se mají získat data. V případě, že server vyžaduje autorizaci pomocí jména a hesla, je možné tyto údaje zadat v parametrech username a password. Plug-in vrací obsah ve struktuře content, tzn. v tomto případě Fetch.content.

V závislosti na formátu dat se může jednat o textový obsah u odpovědí, jež nejsou ve formátech JSON nebo XML (případně nebylo možné je dekódovat), nebo o obsah v podobě strukturovaných dat extrahovaných z formátů JSON nebo XML.

V případě chyb jsou tyto chyby dostupné v proměnné error. V případě chybných odpovědí ze serveru jsou k dispozici i proměnné code a message obsahující stavový kód odpovědi a její text.