Datové zdroje

Jednou z nejvýkonnějších vlastností platformy Mailkit je podpora pro externí datové zdroje. Datové zdroje mohou pomoci automatizovat mnoho různých činností – od aktualizací seznamů příjemců, získávání dynamického obsahu, načítání produktových informací až po řízení rozesílek.

Abyste mohli začít automaticky aktualizovat vaše seznamy příjemců a obsah vašich kampaní, je nutné nejprve nastavit vaše datové zdroje. Mailkit v současné době podporuje datové zdroje ve formátech XML, RSS, JSON a CSV.

Některé formáty však mají omezené využití, např. formát RSS může být využit pouze pro získávání obsahu do šablony, zatímco CSV pouze pro aktualizaci seznamu příjemců. Datové zdroje ve formátu XML jsou nejuniverzálnější a mohou být použity jak pro aktualizaci seznamu příjemců, tak pro předávání obsahu do šablon, plnění SQL databáze produkty nebo řízení rozesílky.

Správa datových zdrojů se nalézá v hlavním menu Profil –> Datové zdroje, kde naleznete jednotlivé datové zdroje rozdělené do skupin Aktivní (aktivně užívané), Nepoužito (zdroje, které nebyly delší dobu použity) a Všechny.

• Datový zdroj k aktualizaci seznamu příjemců
• Jak připravit datový zdroj
• Import datového zdroje
• Použití XML&RSS datových zdrojů v šablonách
• Produktový datový zdroj
• Datový zdroj rozesílky (delivery feed)

Použití datových zdrojů k aktualizaci seznamu příjemců

Nový seznam příjemců můžete snadno vytvořit (nebo aktualizovat existující seznam) pomocí datového zdroje ve formátu XML, JSON nebo CSV. Výrazně doporučujeme dát přednost formátům XML a JSON před CSV, neboť první dva jsou tzv. strukturované formáty a tak jsou méně náchylné k chybám, zatímco drobná změna v souboru CSV může vést k nekonzistentním datům a promíchání údajů.

Začněte kliknutím na tlačítko Přidat datový zdroj a zobrazí se vám dialogové okno, jehož obsah se bude průběžně aktualizovat tak, jak budete vybírat jednotlivá nastavení.

• Název – název datového zdroje. Pokud bude datový zdroj sloužit pro seznam příjemců, dostane seznam příjemců shodné jméno (pokud nebude ze seznamu vybrán jiný existující seznam příjemců). V případě, že datový zdroj bude sloužit pro získávání obsahu, pak tento název bude použit pro adresování zdroje v šablonách.
• Popis – popis datového zdroje (pro vaši orientaci).
• Zdroj – URL adresa, na které se nalézá XML či RSS, jež má sloužit jako datový zdroj. Výrazně doporučujeme, abyste brali v potaz i bezpečnost datového zdroje a zajistili, že nebude přístupný neautorizovaným osobám a používali šifrování pomocí protokolu https kdykoliv se jedná o zdroj, který může obsahovat citlivé údaje.
• Typ – typ datového zdroje. Možnosti jsou CSV, RSS, XML, SQL, JSON a Google BigQuery. Na základě této volby se vám následně zobrazí další možnosti nastavení.
• Cíl (dostupné pouze pro XML zdroje) – umožňuje vybrat, jakým způsobem budou data použita. Možnosti jsou Šablona, Seznam příjemců a Rozesílka.
• Seznam příjemců (dostupné pouze pro zdroje seznamu příjemců CSV, JSON, XML) – umožňuje vám vybrat seznam příjemců, který bude aktualizován, případně založit nový seznam – ten bude pojmenovaný stejně jako datový zdroj. Pokud vyberete položku “*Unsubscribe emails”, budou příjemci vloženi do seznamu odhlášených příjemců a nebude možné na ně posílat žádná sdělení kromě transakčních zpráv.
• Autorizace – zaškrtněte v případě, že přístup k datovému zdroji vyžaduje autorizaci jménem a heslem.
• Plánovaná aktualizace – umožňuje nastavit časový plán aktualizace datového zdroje. Nezapomeňte, že nestačí, aby systém prováděl aktualizaci, ale je nezbytné, aby i samotná data byla se stejnou (nebo vyšší) frekvencí aktualizována.
• Automaticky aktualizovat – zvolte, pokud chcete, aby došlo k aktualizaci před odesláním kampaně. Nezapomeňte však, že aktualizace opozdí samotné rozesílání kampaně o čas nezbytný ke zpracování datového zdroje. (POZOR, funkce automatické aktualizace bude k 1. 11. 2022 vypnuta)
• Poslední aktualizace – informace o datu poslední aktualizace datového zdroje.

Nastavení vašeho datového zdroje budou uložena kliknutím na tlačítko Uložit. Datový zdroj pak bude připraven k dalšímu kroku – v případě datového zdroje pro seznam příjemců je potřeba nastavit přiřazení jednotlivých polí z datového zdroje k záznamům příjemce.

Jak připravit datový zdroj

Datový zdroj nemá pevně definovanou strukturu, ale musí dodržovat základní pravidla. Datové zdroje seznamu příjemců mohou být ve strukturovaných formátech XML a JSON nebo nestrukturovaném CSV. Datové zdroje musí být v kódování UTF-8 a zcela validní v souladu s odpovídajícím standardem – upozorňujeme na nutnost ošetřit správné zakódování znaků jako &, <, >, diakritiky a speciálních znaků. V případě formátu CSV je pak nutná velká opatrnost, neboť se jedná o nestrukturovaný formát, ve kterém může snadno dojít k přidání, záměně či posunu sloupců a systém tuto změnu nebude schopen poznat.

Soubor datového zdroje musí být vystaven na URL dostupné ze serverů Mailkitu a zabezpečen proti přístupu třetích stran, neboť se jedná o citlivé údaje. Zabezpečení je možné realizovat buď pomocí omezení přístupu pouze z IP adres Mailkitu (síť 185.136.200.0/22), nebo HTTP autentifikací pomocí jména a hesla.

Aktualizace seznamů příjemců pomocí datových zdrojů je tzv. přírůstková (rozdílová), tzn. noví příjemci jsou přidáni, příjemci, u kterých došlo ke změně, jsou aktualizováni. Pokud jsou v datovém zdroji i příjemci, kteří již v seznamu příjemců jsou a zároveň u nich nedošlo k žádné změně (tzn. údaje v seznamu příjemců shodují s údaji v datovém zdroji), jsou tito příjemci při aktualizaci přeskočeni. Proto v rámci zefektivnění automatické aktualizace seznamů příjemců pomocí datových zdrojů doporučujeme používat tzv. přírůstkové datové zdroje, tedy takové, kdy datový zdroj pro aktualizaci obsahuje pouze nové příjemce a příjemce, u kterých došlo ke změně.

Protože každý klient využívá jiný informační systém s jinými možnostmi, systém datových zdrojů je postaven maximálně univerzálně a nepředepisuje specifickou strukturu požadovaných dat. Necháváme tedy na klientech, jak pojmenují jednotlivé větve struktury a ty následně napárují k polím příjemce dle vlastních potřeb. Na datové zdroje se však vztahují jistá technická omezení:

1. Plně validní XML, JSON nebo CSV
2. V XML formátu nejsou podporovány attributy (např. first_name="Jana" gender="f" country="cz")
3. Doporučené kódování znaků UTF-8
4. Nepoužívat znak "," jako oddělovač pro více hodnot, ale použít znak "|"
5. Unikátním identifikátorem záznamu a zároveň jediným povinným polem je e-mailová adresa. Pokud bude více záznamů s totožnou e-mailovou adresou, dojde k jejich vzájemnému přepsání

Pro jednodušší přípravu vašeho datového zdroje jsme připravili orientační ukázky datových zdrojů a základních údajů obvyklých v oblasti e-commerce.

XML

<?xml version="1.0" encoding="utf-8"?>
<contacts>
  <contact>
    <email>email@sample.com</email>
    <client_id>ID</client_id>
    <first_name>Jméno</first_name>
    <last_name>Příjmení</last_name>
    <gender>m</gender>
    <mobile>+420xxxyyyzzz</mobile>
    <street>Ulice</street>
    <city>Město</city>
    <zip>12345</zip>
    <state>Kraj</state>
    <country>Země</country>
    <birthdate>DD.MM.RRRR</birthdate>
    <reg_date>DD.MM.RRRR</reg_date>
    <first_sale>DD.MM.RRRR</first_sale>
    <last_sale>DD.MM.RRRR</last_sale>
    <last_active>DD.MM.RRRR</last_active>
    <top_category>|ID|ID|ID|</top_category>
    <top_brands>|ID|ID|ID|</top_brands>
    <top_products>|ID|ID|ID|</top_products>
    <bonus_points>123</bonus_points>
  </contact>
</contacts>

JSON

[
	{
		"email":"email@sample.com",
		"client_id":"ID",
		"first_name":"Jméno",
		"last_name":"Příjmení",
		"gender":"m",
		"mobile":"+420xxxyyyzzz",
		"street":"Ulice",
		"city":"Město",
		"zip":"12345",
		"state":"Kraj",
		"country":"Země",
		"birthdate":"DD.MM.RRRR",
		"reg_date":"DD.MM.RRRR",
		"first_sale":"DD.MM.RRRR",
		"last_sale":"DD.MM.RRRR",
		"last_active":"DD.MM.RRRR",
		"top_category":"|ID|ID|ID|",
		"top_brands":"|ID|ID|ID|",
		"top_products":"|ID|ID|ID|",
		"bonus_points":"123"
	}
]

Jak již bylo uvedeno výše, jediným povinným údajem je e-mail a všechny další údaje jsou nepovinné, nicméně důležité. Obecně platí pravidlo "čím více, tím lépe", ale také "nic se nesmí přehánět". Do datového zdroje by tak mělo přijít maximum dostupných údajů o příjemcích, které je možné pro vaše současné, ale i budoucí e-mailové kampaně využít. V této ukázce jsou následující údaje a jejich role:

• email – bez e-mailu není kam e-maily posílat, takže zcela jednoznačně nutný údaj. Pokud však váš systém vygeneruje datový zdroj obsahující záznamy o všech klientech včetně těch, na které nemáte e-mailový kontakt nic se neděje – Mailkit tyto záznamy bude tiše ignorovat stejně, jako záznamy s adresami v neplatném formátu.
• client_id – interní identifikátor zákazníka, např. klientské číslo, nebo číslo zákaznické karty
• first_name a last_name – jméno a příjmení zákazníka, které je velice důležité nejen pro případné oslovení v e-mailu, ale má vliv i na doručitelnost zpráv, neboť se používá v adrese příjemce. Jméno a příjmení v odeslaném e-mailu místo čisté adresy i lépe působí a pro některé antispamové filtry je indikací vztahu k příjemci. Pokud váš systém nedokáže generovat odděleně jméno a příjmení, je možné využít párování na pole Celé jméno (Fullname), které provede rozdělení do polí Jméno a Příjmení (jméno musí být první).
• gender – pohlaví příjemce vám může posloužit nejen při oslovení, ale i např. pro segmentaci nebo jednoduché rozesílání duálních variant vašich kampaní – jiný design pro ženy a jiný pro muže. Hodnota pohlaví musí být ve tvaru m pro muže a f pro ženy. Důležitost znalosti pohlaví příjemce je často velice podceňována a přitom je ho možné snadno získat i automatizovanými metodami už při registraci, např. použitím služby genderize.io
• mobile – mobilní telefon příjemce (musí být uveden v mezinárodním formátu bez mezer – tj. +420XXXYYYZZZ) může posloužit k realizaci SMS kampaní a zvýšit tak váš zásah u příjemců, kteří nereagují na vaše e-mailové kampaně.
• street, city, zip, state, country – ulice, město, psč, kraj, země jsou všechno údaje, které mohou sloužit k segmentaci kampaní, ale i personalizaci. Můžete tak např. v e-mailech příjemcům nabízet vyzvednutí zboží na nejbližší prodejně či pobočce pošty.
• birthdate – datum narození vám umožní realizovat kampaně s narozeninovými bonusy, narozeninová přání, atp. Formát data by měl odpovídat formátu, který budete následně využívat a pro výpočet výročí je nutné, aby obsahoval nejen den a měsíc, ale i rok.
• reg_date a first_sale – datum registrace a prvního nákupu vašeho zákazníka ve vašem e-shopu vám umožní realizovat výroční kampaně či segmentovat příjemce podle těchto dat. Formát data by měl odpovídat formátování, které budete následně používat v kampaních
• last_sale a last_active – znalost data posledního nákupu a poslední aktivity je důležitá pro vaše reaktivační kampaně, kampaně s dotazy na spokojenost a další poprodejní kampaně. Formát data by měl odpovídat formátování, které budete následně používat v kampaních
• top_category, top_brand a top_products – nejoblíbenější kategorie, značky a produkty vám poslouží k segmentaci ale i k automatizaci obsahu vašich kampaní. V kombinaci s datovým zdrojem produktů pak umožní zcela automatizovaně vkládat do vašich kampaní personalizované produkty odpovídající zájmům příjemce z datového zdroje produktů.
• bonus_points – pokud máte bonusový program pro vaše klienty, je dobré jim stav bodů ukazovat v e-mailech a připomínat tak jejich výhody a možnosti jejich čerpání

Samozřejmě toto je jen část možných údajů a každá firma má jiná data a každý obor je specifický – právě proto Mailkit pracuje s datovými zdroji maximálně univerzálně a případné jejich rozšíření nebude mít vliv na funkčnost. Naopak – pokud začnete se základními údaji v datovém zdroji a až později jej obohatíte o další, stačí pouze u datového zdroje nechat nově Zobrazit strukturu a provést párování nových větví struktury.

Import dat z datového zdroje

Jakmile máte nastavený datový zdroj, je nutné přiřadit jednotlivé větve zdroje k polím kontaktu. Pro přiřazení hodnot nebo zobrazení současného přiřazení klikněte na tlačítko Zobrazit strukturu. V tomto okamžiku dojde k analýze datového zdroje a zobrazí se jeho struktura a dostupná pole. Po přiřazení všech požadovaných polí klikněte na tlačítko Uložit. Po přiřazení polí je možné manuálně spustit import dat kliknutím na tlačítko Import. V případě, že tento zdroj byl nastaven, aby použil nový seznam příjemců, dojde k jeho založení (se stejným názvem jako má datový zdroj) a data z datového zdroje budou na pozadí importována.

Pokud jste u vašeho datového zdroje nastavili plánované aktualizace, bude probíhat pravidelná aktualizace podle tohoto plánu. V případě, že jste zvolili automatickou aktualizaci, dojde k aktualizaci vždy před rozesíláním kampaně, která využívá daný datový zdroj. Nezapomeňte však, že tato aktualizace může zpozdit odeslání vaší kampaně i o několik minut, které může zabrat aktualizace datového zdroje. Obecně doporučujeme dát přednost plánované aktualizaci před automatickou.

Použití XML & RSS datových zdrojů v šablonách

Nastavení XML & RSS datových zdrojů pro použití v šablonách je velmi podobné jako pro použití v seznamech příjemců, ale bez nutnosti přiřazování významů jednotlivých polí. Hodnoty jsou určeny řetězcem jmen v šabloně, proto je snadné nastavit jakýkoliv XML či RSS zdroj.

[% FOREACH data.DS_RSS_EXAMPLE -%]
<div>
	<a href="[% URL -%]"><img src="[% ENCLOSURE -%]" alt="[% TITLE -%]"></a>
	<a href="[% URL -%]">[% TITLE -%]</a>[% DESCRIPTION -%]
</div>
[% END -%]

Výše je uvedený příklad kódu šablony, pro kterou je použit RSS datový zdroj pojmenovaný EXAMPLE. Příkaz FOREACH vytváří smyčku pro parsování a nalezení všech záznamů. Každý ze standardních RSS tagů je snadno řešen a vložen do HTML kódu, což umožňuje výstup dat do šablony. Více informací viz. Šablony e-mailů.

Produktové datové zdroje

Datové zdroje je možné využít i pro přenos produktové nabídky do Mailkitu a následné použití produktových informací v kampaních. Právě zde se pak projevuje síla datových zdrojů a programovatelných šablon, která umožňuje kombinovat data z vícero zdrojů a zcela automatizovaně tak personalizovat obsah na míru jednotlivým příjemcům.

Pro produktové informace je možné použít kterýkoliv z běžných formátů produktových feedů pro srovnávače Heureka, Zboží, Google a další, nebo generovat vlastní feed s potřebnými informacemi. Protože produktové feedy jsou velice rozsáhlé a je důležitá rychlost práce s daty v nich obsaženými, tyto datové zdroje se přenášejí přímo do SQL databáze a i tak je s nimi možné pracovat.

Pro nastavení produktového datového zdroje zvolte typ datového zdroje SQL a pokračujte v nastavování datového zdroje. Pro rozsah dat vyberte jednu z možností:

• Full dataset – při aktualizaci datového zdroje jsou veškerá původní data v SQL databázi Mailkitu nahrazena aktuálně dostupnými daty z URL datového zdroje (původní obsah je smazán a nahrazen novým)
• Incremental dataset – na URL, ze které probíhá aktualizace datového zdroje, můžete vystavit feed, který obsahuje pouze nové nebo změněné položky. Při aktualizaci jsou poté nové položky vloženy a změněné aktualizovány, ostatní položky zůstávají v SQL databázi v Mailkitu beze změny.

V případě použití jednoho ze standardních formátů produktových feedů nejsou k dispozici žádné další možnosti nastavení.

V případě, že vyberete jako zdrojový formát “Vlastní formát dat”, budete muset provést další nastavení. Kliknutím na “Zobrazit strukturu” provede systém analýzu, na jejímž základě je u každého údaje stanoven datový typ a délka nejdelšího záznamu. Stanovení datových typů a délky záznamů (u typů char a varchar) probíhá vždy na základě analýzy prvních 100 položek v datovém zdroji.

Datové typy:

• tinyint – celá čísla (-128 až 127)
• smallint – celá čísla (-32768 až 32767)
• mediumint – celá čísla (-8388608 až 8388607)
• int – celá čísla (-2147483648 až 2147483647)
• bigint – celá čísla (-9223372036854775808 až 9223372036854775807)
• varchar – textový typ pro údaje s rozdílnou délkou (názvy produktů, popisky, URL, ...)
• char – textový typ vhodný zejména pro údaje s pevnou délkou nebo přibližně stejnou délkou (např. PSČ, kódy produktů, atd.)
• decimal – desetinná čísla
• boolean

Pozornost věnujte především datovým typům char a varchar, kde je délka nejdelšího záznamu stanovena na základě analýzy prvních 100 položek v datovém zdroji, jak bylo uvedeno výše. Pokud se v dalších položkách vyskytne záznam, jehož délka bude větší než je nastavená hodnota, bude daný záznam při zpracování zkrácen! 

Je tedy potřeba, aby nastavená hodnota odpovídala minimálně délce nejdelšího záznamu v celém SQL datovém zdroji. Berte v úvahu i budoucí aktualizace těchto datových zdrojů, aby nastavená délka byla vždy dostatečná pro všechny záznamy. Tato délka by však nikdy neměla být zbytečně vysoká, neboť to následně může ovlivnit celkový počet sloupců, který muže v SQL datovém zdroji existovat.

Důležité také je, aby v datovém zdroji u všech položek byla všechna pole (i kdyby pro danou položku byla prázdná). Pokud by totiž u prvních 100 položek nějaké pole chybělo, nebylo by detekováno a zpracováno a tudíž by nebylo možné s ním pracovat.

Pro další práci s datovým zdrojem je dále potřeba nastavit primární klíč (unikátní identifikátor položky), případně definovat až 7 indexovaných polí.

Jakmile potřebná nastavení pro strukturu dokončíte, stačí je uložit, případně nastavit autorizaci či plánovanou aktualizaci, a nakonec provést import dat.

V případě potřeby se neváhejte obrátit na zákaznickou podporu, která vám pomůže s nastavením produktového feedu a jeho následným využitím.

Datový zdroj rozesílky

Datové zdroje rozesílky (delivery feedy) jsou speciální datové zdroje, jež slouží k předání strukturovaných informací pro realizaci rozesílky kampaně. Zatímco obvykle kampaň využívá stanovený seznam příjemců, na který probíhá její rozesílka dle nastavených pravidel, v případě datového zdroje rozesílky je kampaň rozesílána pouze na adresy uvedené v datovém zdroji. Jedná se o alternativu k API volání mailkit.sendmail_mass, tzn. způsob, jak do Mailkitu dostávat vysoce strukturovaná data, např. z personalizačních systémů či CRM, jež se mají při odesílání kampaně zpracovat. Tyto feedy pak musí mít striktně definovanou strukturu ve formátu XML, která je velice podobná struktuře API volání mailkit.sendmail_mass.

<?xml version="1.0"?>
<deliveryFeed>
  <feedItem>
    <recipient>
      <email>recipient email (povinné)</email>
      <first_name>Jméno (volitelně)</first_name>
      <last_name>Prijmeni (volitelně)</last_name>
      <gender>M (volitelně)</gender>
      ... další standardní pole příjemce
    </recipient>
    <subject>subject (volitelně)</subject>
    <message_data>static message content (volitelně)</message_data>
    <attachment>
      <file_url>url (volitelně)</file_url>
      <file_url>url (volitelně)</file_url>
      <file_url>url (volitelně)</file_url>
    </attachment>
    <content>
      <!-- XML structured values (volitelně) example    -->
    </content>
  </feedItem>
</deliveryFeed>

Údaje o příjemcích v datovém zdroji rozesílky mají přednost před údaji o příjemci uloženými v seznamu příjemců a nahradí tyto hodnoty v průběhu doručování. Datový zdroj rozesílky tak může nejen řídit rozesílku, ale zároveň i sloužit jako cesta k aktualizaci seznamu příjemců.