Integrace Mailchimp s eWay-CRM

Integrace Mailchimp s eWay-CRM slouží k automatické synchronizaci kontaktů a vybraných marketingových údajů.

Obsah

• K čemu integrace slouží
• Jaká data se synchronizují
  
  • Vlastní pole
• Co připravit před spuštěním
  
  • API key
  • Audience ID
  • HASH
  • Synchronizace uživatelských polí
• Konfigurační soubor
• První spárování existujících kontaktů
• Jak funguje synchronizace v provozu
• Omezení a doporučení

K čemu integrace slouží

Integrace je navržená tak, aby se nové nebo upravené kontakty z eWay-CRM propsaly do příslušného seznamu kontaktů (audience) v Mailchimpu, včetně běžných kontaktních údajů, vybraných vlastních polí a kategorií (v Mailchimpu označované jako tagy).

Jaká data se synchronizují

Do Mailchimpu se dá kontakt vytvořit teprve ve chvíli, kdy má vyplněný e-mail a je u něj zvolená cílová audience.

Ve výchozím rozsahu se do Mailchimpu přenáší e-mailová adresa, jméno, příjmení, telefon a adresa. Mailchimp má při vytvoření audience standardně připravené tzv. merge fields FNAME, LNAME, ADDRESS a PHONE; další údaje je možné doplnit jako vlastní pole. Typickou součástí mapování bývá také název firmy, datum narození, stav odběru newsletteru a kategorie kontaktu. Merge fields v Mailchimpu slouží pro uložení vlastních údajů o kontaktu a je možné je následně použít pro personalizaci i segmentaci.

Pole v eWay-CRM	Pole v Mailchimpu	Poznámka
E-mail	email_address	Povinné pole a identifikátor kontaktu
Jméno	FNAME	Standardní merge field
Příjmení	LNAME	Standardní merge field
Telefon	PHONE	Standardní merge field
Adresa firmy	ADDRESS	V Mailchimpu je to jedno strukturované pole
Firma	COMPANY	Musí existovat odpovídající merge field
Datum narození	BIRTHDAY	Volitelné, datumový formát
Nezasílat newsletter	status	Typicky subscribed / unsubscribed
Kategorie kontaktu	tags	Slouží pro štítkování a segmentaci

Vlastní pole

U vlastních polí je potřeba hlídat datové typy. Mailchimp podporuje například text, číselná pole (number), výběrové pole (radio), seznam (dropdown), datum (date), narozeniny (birthday), adresa (address), PSČ (zip), telefon (phone), url a imageurl.

Specifika polí jsou:

• u radio a dropdown polí musí hodnoty v eWay-CRM odpovídat hodnotám v Mailchimp
• u data Mailchimp validuje konkrétní formáty
• u narozenin očekává formát MM/DD
• při synchronizaci adresy přes vlastní pole, je možné ji poskládat z více vlastních polí, která si Mailchimp skládá do jednoho pole

Co připravit před spuštěním

Před prvním spuštěním doporučujeme vyexportovat kontakty z Mailchimpu a uložit si zálohu.

Aby integrace fungovala, připravte si v Mailchimpu API key a Audience ID pro každou audience, kterou chcete používat. API key má plný přístup k účtu, proto jej ukládejte stejně opatrně jako heslo.

V eWay-CRM si připravte API uživatele - viz článek Jak vytvořit API uživatele.

API key

API key si vygenerujete ve chvíli, kdy kliknete na ikonu vašeho uživatele v horním rohu Mailchimp účtu, vyberete Profile a následně zvolíte Extras a API keys.

Zde si pomocí možnosti Create a Key vytvořte nový klíč, který budete používat pro nastavení konfiguračního souboru Mailchimp aplikace v eWay-CRM. Tento klíč si zkopírujte.

Následně je třeba jej vložit do konfigurace Mailchimp aplikace - viz dále. 

Audience ID

Druhá nezbytné hodnota je Audience ID, která určuje do jaké audience kontakt náleží - v Mailchimp je možné mít více audience.

Zde je třeba přejít do záložky Audience, kliknout na tři tečky nad seznamem kontaktů a vybrat možnost Audience settings. 

 

Zde už stačí jen vykopírovat hodnotu v poli Audience ID.

Tuto hodnotu je třeba zadat do konfiguračního souboru Mailchimp aplikace (viz dále), ale zároveň je třeba vytvořit v modulu Kontakty uživatelské pole v eWay-CRM. Musí se jednat o pole typu Seznam, jehož název je volitelný, ale hodnota/hodnoty v seznamu musí mít stejnou hodnotu jako Audience ID, které jste si vykopírovali. Pokud chcete, aby se pole vyplňovalo automaticky při zakládání kontaktu, je vhodné nastavit položku seznamu jako výchozí.

HASH

Kromě pole pro Audience ID je také třeba vytvořit pole pro HASH, kam se uloží hodnota, která jednoznačně identifikuje kontakt proti kontaktu v Mailchimp a nebude docházet ke vzniku duplicit, stejně jako bude možné synchronizovat ke kontaktu do Mailchimp úpravy.

Toto pole musí splňovat následující:

• je vytvořeno v modulu Kontakty
• jeho typ je Odkaz
• název pole je volitelný

Synchronizace uživatelských polí

Pokud chcete synchronizovat další vlastní údaje, ujistěte se, že v příslušné audience existují odpovídající pole. To znamená:

• mám vytvořené pole určitého typu v eWay-CRM
• mám vytvořené pole stejného nebo podporovaného typu v Mailchimp

Při vytváření pole v Mailchimp se pak zadává tzv. Merge Tag, který identifikuje pole pro API komunikaci. Merge Tag zadáváte v poli Default merge tag value (v tomto případě by to bylo GROUPTEXT). 

Každé takové propojení je třeba nastavit v konfiguračním souboru - viz dál.

Konfigurační soubor

Aplikace Mailchimp Connector, která umožňuje synchronizaci kontaktů mezi eWay-CRM a Mailchimp, obsahuje soubor , který je třeba nastavit před prvním spuštěním. Údaje v konfiguračním souboru vypadají takto - jsou u nich uvedeny vysvětlivky:

<mailchimpConnector>
    <mailchimpConfig
        apiKey="API KEY" /> - API key, které jste si vykopírovali z Mailchimpu
    <crmConnection
        url="ADRESA VAŠÍ WEBOVÉ SLUŽBY eWay-CRM"          - tvar s https://
        userName="UŽIVATELSKÉ JMÉNO API UŽIVATELE"        - uživatelské jméno, které se zobrazuje v Centru pro správu u vašeho API uživatele
        password="" />                                    - ponechává se prázdné, pokud jste si heslo sami nezvolili
    <fields>
        <contactModule
            mailchimpAudienceFieldName="af_XX"            - databázový název pole, které jste si vytvořili v eWay-CRM - viz Audience ID
            mailchimpSubscriberHashField="af_XY"          - databázový název pole, které jste si vytvořili v eWay-CRM - viz HASH
            birthdayFieldName="af_XZ">                    - volitelné pole v případě, že chcete kopírovat narozeniny (af_XZ je třeba nahradit skutečným databázovým polem, které jste si na kontaktu vytvořili v eWay-CRM, musí být typu Datum)

            <customFields>
                <field customFieldName="af_XA" mailchimpMergeFieldTag="TEXTMF" />    - jako první se zadává databázový název pole v eWay-CRM, poté Merge Tag, který jste zadali při vytváření pole v Mailchimpu
                <field customFieldName="af_XB" mailchimpMergeFieldTag="NUMBERMF" />  - vložíte tolik záznamů, kolik uživatelských polí chcete synchronizovat
            </customFields>
        </contactModule>
    </fields>
</mailchimpConnector>

Na základě této konfigurace pak dojde i k nastavení jednotlivých triggerů, které jsou součástí aplikace.

První spárování existujících kontaktů

Po nasazení integrace je vhodné jednorázově spárovat existující kontakty v eWay-CRM s jejich protějšky v Mailchimpu podle e-mailové adresy. Smyslem této úlohy je doplnit ke kontaktům subscriber hash a vazbu na audience tak, aby další změny už probíhaly automaticky. Mailchimp používá jako identifikátor kontaktu MD5 hash z e-mailové adresy převedené na malá písmena, takže právě e-mail je pro počáteční párování rozhodující.

Prvotní párování dává smysl spouštět až ve chvíli, kdy jsou hotové audience, mapování polí i import kontaktů na obou stranách. Pokud máte kontakt pouze v Mailchimpu a v eWay-CRM vůbec neexistuje, je potřeba jej nejdříve dostat do eWay-CRM a teprve potom párovat. Po dokončení prvotního spárování už další změny probíhají automaticky na základě triggerů.

Jak funguje synchronizace v provozu

Za provozu jsou synchronizovány tyto úpravy:

Synchronizace z eWay-CRM do Mailchimpu:

• vytvoření kontaktu
• editace kontaktu s tím, že jsou do Mailchimpu synchronizovány pouze provedené změny na synchronizovaných polích
• odhlášení nebo odmazání kontaktu

Při odstranění kontaktu v eWay-CRM se kontakt odebere z příslušné audience. Je dobré vědět, že Mailchimp rozlišuje odhlášení, archivaci člena a trvalé smazání:

• odhlášení (unsubscribe) v eWay-CRM odhlásí kontakt i v Mailchimp
• odhlášení (unsubscribe) v eWay-CRM odhlásí kontakt i v Mailchimp
• smazání kontaktu v eWay-CRM permanentně smaže kontakt v Mailchimp
• odebrání audience v eWay-CRM povede k archivování kontaktu v Mailchimp

Synchronizace z Mailchimpu do eWay-CRM:

• synchronizuje se odhlášení kontaktu

Omezení a doporučení

Nejdůležitější omezení souvisí s tím, jak Mailchimp identifikuje kontakt. Protože API používá MD5 hash z e-mailové adresy jako kanonický identifikátor člena, není vhodné synchronizovat více různých kontaktů se stejnou e-mailovou adresou do stejné audience. V praxi platí jednoduché pravidlo: jedna e-mailová adresa by měla odpovídat jednomu kontaktu v jedné audience.

Pokud nepotřebujete oddělené audiences z obchodních nebo právních důvodů, zvažte jednodušší model s jednou hlavní audience a členěním přes tagy a segmenty. Mailchimp tento přístup doporučuje. Pokud ale opravdu potřebujete více audiences, integrace to podporuje přes pole pro výběr audience v eWay-CRM.

Pro rozšiřování synchronizace o další vlastní pole platí dvě praktická doporučení. Za prvé vždy nejdřív ověřte kompatibilitu datových typů na obou stranách, zejména u seznamů, datumů, URL a adres. Za druhé počítejte s tím, že adresa v Mailchimpu je jedno strukturované pole, zatímco v eWay-CRM bývá rozdělená do více samostatných položek, takže její mapování vyžaduje zvláštní konfiguraci.