Integrace s Klaviyo

Aplikace Skloňování jmen automaticky synchronizuje výsledky skloňování do Klaviyo profilů. Oslovení jsou pak dostupná jako profilové vlastnosti a lze je použít v libovolné Klaviyo šabloně, flow nebo kampani.

Předpoklady

Před nastavením integrace si připravte:

• Public API Key — dostupný v Klaviyo v sekci Account → Settings → API Keys
• Private API Key — vytvořte nový klíč se scopem Profiles: Full access ve stejné sekci

Upozornění

Private API Key nikdy nesdílejte veřejně ani ho nevkládejte do klientského kódu. Slouží výhradně pro komunikaci ze serveru aplikace do Klaviyo.

Nastavení integrace

1. V administraci Shopify otevřete aplikaci Skloňování jmen.
2. Přejděte do sekce Integrace.
3. Zadejte Klaviyo API klíč (public) a Klaviyo privátní API klíč z Klaviyo.
4. Klikněte na Připojit Klaviyo.

Po uložení bude aplikace synchronizovat oslovení do Klaviyo při každém zpracování zákazníka.

Synchronizované vlastnosti profilu

Po úspěšné integraci najdete v Klaviyo profilu zákazníka tyto tři vlastnosti:

Vlastnost Klaviyo	Popis	Příklad
Czech addressing	Křestní jméno v 5. pádu	Jane
Czech last name	Příjmení v 5. pádu	Nováku
Gender	Gramatický rod — male, female, nebo unknown	male

Upozornění

Aplikace zapisuje pouze tyto tři vlastnosti. Žádná vlastnost s kompletním oslovením neexistuje — Czech addressing obsahuje samotné křestní jméno. Celé oslovení si v šabloně složte z Czech addressing a Czech last name.

Upozornění

Pokud aplikace neumí vyskloňovat křestní jméno zákazníka, nezapíše do Klaviyo žádnou z těchto vlastností — ani Gender. Stejně tak u zákazníků, kteří zatím nebyli zpracováni. Každá šablona proto musí mít smysluplnou variantu bez jména.

Použití v Klaviyo šablonách

Poznámka

Klaviyo používá šablonovací jazyk Django, nikoliv Liquid. Podmínky se zapisují jako {% if %} / {% elif %} / {% else %} / {% endif %} — Liquidový tag {% elsif %} v Klaviyo nefunguje.

Základní oslovení

V Klaviyo email editoru použijte syntaxi pro profilové vlastnosti:

{% if person|lookup:'Czech addressing' %}
  {{ person|lookup:'Czech addressing' }}
{% endif %}

Pokud vlastnost neexistuje — zákazník nebyl dosud zpracován, nebo jeho jméno nelze vyskloňovat — podmínka celý blok přeskočí a nezobrazí nic.

Oslovení s fallbackem

Nebezpečí

Do fallbacku nikdy nevkládejte first_name. Tato proměnná obsahuje jméno v 1. pádu, takže vznikne „Dobrý den, Lenka” místo „Dobrý den, Lenko”. Fallback se přitom uplatní právě u zákazníků, pro které aplikace skloňovaný tvar nemá — a pro ty žádný správný 5. pád k dispozici není. Jediný bezpečný fallback je pozdrav bez jména.

{% if person|lookup:'Czech addressing' %}
  Dobrý den, {{ person|lookup:'Czech addressing' }},
{% else %}
  Dobrý den,
{% endif %}

Genderové oslovení

Po „Vážený pane” a „Vážená paní” následuje příjmení, tedy vlastnost Czech last name. Křestní jméno (Czech addressing) patří do neformálního pozdravu.

{% if person|lookup:'Czech last name' %}
  {% if person|lookup:'Gender' == 'male' %}
    Vážený pane {{ person|lookup:'Czech last name' }},
  {% elif person|lookup:'Gender' == 'female' %}
    Vážená paní {{ person|lookup:'Czech last name' }},
  {% else %}
    Dobrý den, {{ person|lookup:'Czech addressing' }},
  {% endif %}
{% elif person|lookup:'Czech addressing' %}
  Dobrý den, {{ person|lookup:'Czech addressing' }},
{% else %}
  Dobrý den,
{% endif %}

Použití v subject line

Klaviyo podporuje podmínky i v předmětu emailu. I tady potřebujete variantu bez jména:

{% if person|lookup:'Czech addressing' %}{{ person|lookup:'Czech addressing' }}, váš balíček je na cestě{% else %}Váš balíček je na cestě{% endif %}

Výsledek: Jane, váš balíček je na cestě — a Váš balíček je na cestě u zákazníka, kterému jméno vyskloňovat nelze.

Zpoždění synchronizace

Poznámka

Synchronizace do Klaviyo probíhá s 3–5minutovým zpožděním po vytvoření zákazníka. Toto zpoždění je způsobeno interní frontou zpracování a nelze ho zkrátit.

Pokud testujete funkčnost, počkejte prosím 5 minut po vytvoření zákazníka, než budete kontrolovat Klaviyo profil.

Zpoždění se týká pouze nově vytvořených zákazníků. Aktualizace existujících zákazníků se synchronizují ve stejném časovém rámci.

Omezení integrace

• Bez retry mechanismu — pokud synchronizace selže (výpadek Klaviyo API), data nejsou automaticky znovu odeslána. Zákazník bude aktualizován při příštím spuštění webhooku (tj. při další aktualizaci v Shopify).
• Pouze nové a aktualizované zákazníky — historičtí zákazníci nejsou hromadně synchronizováni. Doplňují se postupně při každém nákupu nebo úpravě profilu.
• Propojení přes email — synchronizace páruje Shopify zákazníka s Klaviyo profilem podle emailové adresy. Zákazníci bez emailu nejsou synchronizováni.
• Nevyskloňovatelná křestní jména — pokud aplikace neumí vyskloňovat křestní jméno zákazníka, do Klaviyo se nesynchronizuje nic. Nezapíše se ani Czech last name, ani Gender.

Ověření funkčnosti

Po nastavení integrace:

1. V administraci Shopify otevřete zákaznický profil a uložte ho (i bez změny).
2. Počkejte 5 minut.
3. V Klaviyo přejděte na Audience → Profiles a vyhledejte zákazníka.
4. Zkontrolujte, zda jsou u profilu přítomny vlastnosti Czech addressing, Czech last name a Gender.

Tip

Pokud vlastnosti nejsou přítomny ani po 10 minutách, zkontrolujte správnost API klíčů v nastavení aplikace. Nejčastější chybou je záměna Public a Private klíče.

Ověřujte na zákazníkovi s běžným českým jménem. U nevyskloňovatelného jména se vlastnosti nezobrazí nikdy — to není chyba nastavení.

Segmentace v Klaviyo

Vlastnost Gender lze využít i pro segmentaci:

• Segment žen: Gender is female
• Segment mužů: Gender is male
• Zákazníci s oslovením: Czech addressing is set

Tyto segmenty jsou pak použitelné pro cílení kampaní, A/B testy různých oslovení nebo pro flow s podmíněnými větvemi.

---

Potřebujete další pomoc? Napište nám na integrace@soundsgood.agency.