V určité chvíli tým přestane vytvářet odkazy ručně. Produkt potřebuje odkaz ke sdílení pro každého uživatele, CMS má při publikování článku vytvořit krátkou URL, nástroj pro kampaně chce sledovaný odkaz pro každou kreativu. Integrace pro vývojáře k vytváření sledovatelných odkazů s vlastní doménou udělá ze zkracovače funkci, kterou vaše systémy volají.
Tento návod prochází integraci od začátku do konce: co rozhodnout, než začnete psát kód, jak funguje ověřování a volání pro vytvoření odkazu, jak udělat odkazy sledovatelné, aniž byste rozbili atribuci, které okrajové případy přesměrování vás potrápí, kam patří webhooky a jak vše otestovat. Jako příklad slouží API LinkPilotu, stejný postup platí pro většinu platforem.
Nejdřív rozhodněte o architektuře
Čtyři rozhodnutí, udělaná jednou, ušetří většinu přepracování.
- Které systémy odkazy vytvářejí a při jaké události: publikování, akce uživatele, uložení záznamu kampaně.
- Která pole volající ovládá. Obvykle cílovou adresu a štítky, někdy koncovku odkazu. Doménu jen výjimečně, ta má být nastavením pracovního prostoru nebo klienta.
- Jak se data kampaně promítnou do sledování. Kampaň, kanál a umístění ve vašem systému se stanou štítky odkazu a parametry UTM cílové adresy. Rozhodněte o tomto převodu a dejte ho do jedné funkce.
- Přímý odkaz, deep link, nebo náhradní stránka. Odkaz do mobilní aplikace potřebuje webovou náhradu pro lidi, kteří aplikaci nemají. Rozhodněte, zda to řeší zkracovač, nebo cílová stránka.
Zapište si to. Integrace je hlavně lepidlo a lepidlo má být nudné.
Ověřování pomocí klíčů s omezeným rozsahem
API LinkPilotu ověřuje požadavky klíči typu bearer, které začínají
lp_live_. Vytvoříte je v řídicím panelu a jsou dostupné v každém
tarifu včetně Free. Každý klíč patří k jednomu pracovnímu prostoru,
takže integrace agentury používá jeden klíč pro každý pracovní prostor
klienta a odkazy už z principu skončí na správném místě.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me vrací pracovní prostor, tarif, limity, aktuální využití
a rozpočet požadavků klíče. Volejte ho při spuštění a limity
zapisujte do vlastních logů, abyste se o stropu dozvěděli dřív než
kampaň.
S klíčem zacházejte jako s produkčními přihlašovacími údaji: uložte ho do správce tajných údajů, nikdy do repozitáře ani do balíčku pro frontend, a když ho musíte předat někomu, kdo integraci staví, pošlete ho přes jednorázový tajný odkaz. Předání a rotaci popisuje návod ke klíčům API.
Vytvoření odkazu
Volání pro vytvoření přijímá cílovou adresu a několik volitelných polí.
curl -X POST https://uselinkpilot.com/api/v1/links \
-H "Authorization: Bearer lp_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/launch?utm_source=newsletter&utm_medium=email&utm_campaign=oct-launch",
"slug": "oct-launch-email",
"domain": "go.example.com",
"title": "October launch, newsletter",
"tags": ["oct-launch", "email"]
}'
Odpověď obsahuje ID odkazu, krátkou URL a metadata, která jste
poslali. ID si uložte k vlastnímu záznamu, budete podle něj odkaz
později číst, upravovat nebo mazat. GET /links vypisuje odkazy od
nejnovějších se stránkováním pomocí kurzoru ({ data, next_cursor })
a GET /links/{id} a DELETE /links/{id} pracují s jedním odkazem.
Několik pravidel, díky kterým integrace zůstane poctivá:
- Cílovou URL sestavujte v kódu i se značkami UTM, z polí kampaně. Ručně psané značky se časem rozcházejí. Pravidla nastavuje příručka k UTM.
- Koncovky odkazů nechte generovat platformu, pokud je nebude číst člověk. Když je nastavujete sami, odvoďte je z kampaně, kanálu a umístění, malými písmeny se spojovníky, a konflikt řešte přidáním krátké přípony a jedním novým pokusem.
- Vytváření udělejte idempotentní. Každé vytvoření svažte s ID
vlastního záznamu, aby opakovaný pokus po vypršení časového limitu
našel existující odkaz a nevytvořil druhý. Pokud platforma klíč
idempotence nenabízí, zkontrolujte před vytvořením v
GET /linkssvůj štítek nebo koncovku. - Hromadné vytváření je smyčka s postupným zpomalováním. Dodržujte
rozpočet požadavků z
/me, při 429 zpomalte a každé selhání zapište do logu i se záznamem, ke kterému patřilo.
Pro skripty a místní nástroje obaluje stejná volání CLI linkpilot
z npm a server @uselinkpilot/mcp je zpřístupňuje AI agentům. Obojí
je open source na GitHubu pod TetraCoreHQ.
Sledovatelné odkazy bez rozbité atribuce
Každé kliknutí na odkaz vytvořený přes API se zaznamená stejně jako u odkazu z řídicího panelu: čas, zdroj odkazu (referrer), zařízení, prohlížeč, země, region, označení bota a místo IP adresy hash se solí. Tak získáte počet kliknutí na úrovni odkazu. Atribuce na cílovém webu ale dál závisí na tom, zda URL dorazí neporušená.
- Zachovejte parametry dotazu i po přesměrování. Otestujte odkaz kontrolou přesměrování a ověřte, že výsledná URL značky UTM obsahuje.
- Vyhněte se řetězcům. Krátký odkaz, který přesměruje na další přesměrování, ztrácí parametry i rychlost. Odkazujte přímo na cílovou stránku.
- Rozhodněte, co sbíráte. Země a zařízení jsou souhrnné statistiky. Odkaz pro jednoho uživatele spojený se záznamem zákazníka je osobní údaj. Moderní průvodce sledováním odkazů uvádí, co se zaznamenává a co záměrně ne.
- Nastavte očekávání v produktu. Počet kliknutí není počet konverzí. Zobrazujte obojí s popisky.
Okrajové případy přesměrování
- Ověření cílové adresy. Ještě před vytvořením odkazu odmítněte cílové adresy bez HTTPS, vlastní doménu zkracovače a vše, co je na seznamu blokovaných. Otevřené přesměrování pod vaší značkou je nástroj pro phishing.
- Odkazy s vypršelou platností, vypnuté nebo neexistující. Náhradní stránku určete a nastavte při vytváření odkazu, aby mrtvý odkaz z kampaně vedl na domovskou stránku, a ne na chybu. U tištěných odkazů raději měňte cílovou adresu, než abyste nechali platnost vypršet.
- Deep linky. Použijte cílovou adresu, která aplikaci rozpozná a jinak přejde na web, nebo funkci platformy, která to umí. Otestujte na obou operačních systémech s nainstalovanou aplikací i bez ní.
- Kódování. Cílovou adresu zakódujte pro URL dřív, než ji vložíte do JSON, zvlášť když má vlastní řetězec dotazu. Obvyklou chybou je dvojité kódování.
- Lokalizace. Pokud jeden krátký odkaz slouží několika jazykům, rozpoznávejte jazyk na cílové stránce, ne v koncovce odkazu.
Webhooky pro důležité události
Webhooky umožní zbytku vašeho systému reagovat na dění kolem odkazů bez
dotazování. LinkPilot každé doručení podepisuje hlavičkou s podpisem
HMAC a posílá události životního cyklu odkazu (link.created,
link.updated, link.deleted) a životního cyklu tajné zprávy (secret.created,
secret.viewed, secret.burned). Podpis ověřte před parsováním,
příjem potvrďte rychle, zpracování veďte přes frontu a ukládejte ID
událostí, aby opakované doručení nic nepokazilo. Data o kliknutích
jsou proud pro vykazování, ne webhook. Čtěte je přes statistiky
a exporty. Stavbu přijímače popisuje návod k webhookovým
integracím.
Otestujte vše od začátku do konce a pak dál sledujte
Než integrace sáhne na skutečnou kampaň:
- Vytvořte odkaz se svými testovacími štítky v testovacím pracovním prostoru.
- Ověřte, že odpověď obsahuje očekávané ID a krátkou URL.
- Klikněte na odkaz z telefonu a z notebooku. Ověřte přesměrování, značky UTM po příchodu a dvě kliknutí ve statistikách se správnými typy zařízení.
- Vytvořte stejný záznam znovu a ověřte, že dostanete stejný odkaz, ne duplikát.
- Odkaz smažte a ověřte, že na váš koncový bod webhooku dorazí
link.deleted, pokud webhook používáte.
V provozu sledujte tři věci: chybovost API podle stavového kódu,
latenci přesměrování ze syntetické kontroly a týdenní porovnání počtu
odkazů mezi vašimi záznamy a GET /links. Klíč API pravidelně rotujte
a také pokaždé, když z týmu, který ho má, někdo odejde.
Integraci zdokumentujte jako interní produkt: jaká pole přijímá,
pravidlo pro koncovky, chování náhradní stránky, limity z /me a koho
volat, když kampaň hlásí nula kliknutí. Další člověk, který na ni
sáhne, bude rád, a často to budete vy.