Arriba un moment en què un equip deixa de crear enllaços a mà. El producte necessita un enllaç per compartir per a cada usuari, el CMS hauria de generar un URL curt quan es publica un article, l'eina de campanyes vol un enllaç amb seguiment per a cada peça creativa. Una integració per a desenvolupadors per crear enllaços amb domini propi i seguiment converteix l'escurçador en una funció que criden els vostres sistemes.
Aquesta guia recorre la integració de cap a cap: què cal decidir abans d'escriure codi, com funcionen l'autenticació i la crida de creació, com fer que els enllaços tinguin seguiment sense trencar l'atribució, els casos límit de la redirecció que fan mal, on encaixen els webhooks i com provar-ho tot. L'API de LinkPilot serveix d'exemple; l'estructura val per a la majoria de plataformes.
Decidiu primer l'arquitectura
Quatre decisions, preses una sola vegada, estalvien la major part de la feina refeta.
- Quins sistemes creen enllaços, i amb quin desencadenant: un esdeveniment de publicació, una acció de l'usuari, un registre de campanya que es desa.
- Quins camps controlen els que fan la crida. Normalment, la destinació i les etiquetes; de vegades, un àlies. Poques vegades el domini, que hauria de ser una opció per espai de treball o per client.
- Com es tradueixen les dades de campanya en seguiment. La campanya, el canal i l'emplaçament del vostre sistema es converteixen en etiquetes de l'enllaç i en paràmetres UTM de la destinació. Decidiu aquesta correspondència i poseu-la en una sola funció.
- Enllaç directe, enllaç profund o alternativa. Un enllaç que obre una aplicació mòbil necessita una alternativa web per a qui no té l'aplicació. Decidiu si se n'encarrega l'escurçador o la destinació.
Poseu-ho per escrit. La integració és sobretot codi d'enllaç entre sistemes, i aquest codi ha de ser avorrit.
Autentiqueu-vos amb claus d'abast limitat
L'API de LinkPilot s'autentica amb claus de tipus bearer que comencen
per lp_live_, es creen al tauler i estan disponibles a tots els plans,
inclòs el Free. Cada clau pertany a un espai de treball, de manera que
la integració d'una agència fa servir una clau per a cada espai de
treball de client i els enllaços van a parar al lloc correcte per
disseny.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me retorna l'espai de treball, el pla, els límits, l'ús actual i
el pressupost de peticions de la clau. Crideu-lo en arrencar i mostreu
els límits als vostres registres, perquè us assabenteu d'un límit abans
que el descobreixi una campanya.
Tracteu la clau com una credencial de producció: deseu-la en un gestor de secrets, mai en un repositori ni en un paquet de front-end, i quan l'hàgiu de passar a qui construeix la integració, envieu-la amb un enllaç secret d'un sol ús. La guia sobre claus d'API explica el lliurament i la rotació.
Creeu l'enllaç
La crida de creació rep la destinació i uns quants camps opcionals.
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"]
}'
La resposta inclou l'identificador de l'enllaç, l'URL curt i les
metadades que heu enviat. Deseu l'identificador al costat del vostre
registre: és el que fareu servir per llegir, actualitzar o suprimir
l'enllaç més endavant. GET /links llista els enllaços del més nou al
més antic amb paginació per cursor ({ data, next_cursor }), i
GET /links/{id} i DELETE /links/{id} actuen sobre un de sol.
Unes quantes normes que mantenen la integració honesta:
- Construïu l'URL de destinació al codi, amb les etiquetes UTM, a partir dels camps de la campanya. Les etiquetes escrites a mà acaben divergint. La guia completa dels UTM en fixa les convencions.
- Deixeu que la plataforma generi els àlies tret que els hagi de llegir una persona. Quan sí que en fixeu, deriveu-los de la campanya, el canal i l'emplaçament, en minúscules amb guionets, i resoleu els conflictes afegint-hi un sufix curt i tornant-ho a provar una vegada.
- Feu que la creació sigui idempotent. Associeu cada creació a
l'identificador del vostre registre, perquè un reintent després d'un
temps d'espera exhaurit trobi l'enllaç existent en lloc de crear-ne un
segon. Si la plataforma no ofereix cap clau d'idempotència, consulteu
GET /linksper la vostra etiqueta o àlies abans de crear-lo. - Crear en bloc vol dir un bucle amb espera progressiva. Respecteu
el pressupost de peticions de
/me, espereu i reintenteu davant un 429, i registreu cada error amb el registre al qual corresponia.
Per a scripts i eines locals, la CLI linkpilot d'npm encapsula les
mateixes crides, i el servidor @uselinkpilot/mcp les posa a l'abast
dels agents d'IA. Tots dos són de codi obert a GitHub, a TetraCoreHQ.
Enllaços amb seguiment sense trencar l'atribució
Cada clic en un enllaç creat per API es registra exactament igual que en un de creat al tauler: hora, referent, dispositiu, navegador, país, regió, una marca de bot i un hash amb sal en lloc de la IP. Això us dona el recompte per enllaç. L'atribució a la destinació continua depenent que l'URL hi arribi intacte.
- Conserveu els paràmetres de consulta a través de la redirecció. Proveu l'enllaç amb el comprovador de redireccions i confirmeu que les etiquetes UTM són a l'URL final.
- Eviteu les cadenes. Un enllaç curt que redirigeix a una altra redirecció perd paràmetres i velocitat. Apunteu a la pàgina final.
- Decidiu què recolliu. El país i el dispositiu són estadístiques agregades. Un enllaç per usuari relacionat amb el registre d'un client és una dada personal. La guia moderna del seguiment d'enllaços detalla què es registra i què no es registra expressament.
- Fixeu les expectatives al producte. Un recompte de clics no és un recompte de conversions. Mostreu tots dos, cadascun amb la seva etiqueta.
Gestioneu els casos límit de la redirecció
- Validació de la destinació. Abans de crear l'enllaç, rebutgeu les destinacions que no siguin HTTPS, el vostre propi domini d'escurçador i qualsevol cosa que aparegui en una llista de bloqueig. Una redirecció oberta amb la vostra marca és una eina de phishing.
- Enllaços caducats, desactivats o inexistents. Decidiu la pàgina alternativa quan creeu l'enllaç i configureu-la, perquè un enllaç de campanya mort porti a la pàgina d'inici i no a un error. Per als enllaços impresos, val més editar la destinació que deixar-los caducar mai.
- Enllaços profunds. Feu servir una destinació que detecti l'aplicació i, si no hi és, passi al web, o una funció de la plataforma pensada per a això. Proveu-ho en tots dos sistemes operatius, amb l'aplicació instal·lada i sense.
- Codificació. Codifiqueu la destinació com a URL abans de posar-la al JSON, sobretot quan porta la seva pròpia cadena de consulta. La doble codificació és l'error habitual.
- Localització. Si un sol enllaç curt serveix diversos idiomes, feu la detecció de l'idioma a la destinació, no a l'àlies.
Afegiu webhooks per als esdeveniments que importen
Els webhooks permeten que la resta del vostre sistema reaccioni a
l'activitat dels enllaços sense haver de consultar-la contínuament.
LinkPilot signa cada enviament amb una capçalera de signatura HMAC i
s'activa amb el cicle de vida dels enllaços (link.created,
link.updated, link.deleted) i dels secrets (secret.created,
secret.viewed, secret.burned). Verifiqueu la signatura abans
d'analitzar el contingut, responeu de seguida, processeu des d'una cua i
deseu els identificadors dels esdeveniments perquè els reintents no
facin mal. Les dades de clics són un flux d'informes, no un webhook:
llegiu-les a través de les estadístiques i les exportacions. La guia
d'integracions amb
webhooks
explica com construir el receptor.
Proveu-ho de cap a cap i continueu vigilant
Abans que la integració toqui una campanya real:
- Creeu un enllaç amb les etiquetes de prova, en un espai de treball de proves.
- Comproveu que la resposta té l'identificador i l'URL curt que espereu.
- Feu-hi clic des d'un mòbil i des d'un portàtil. Confirmeu la redirecció, les etiquetes UTM en arribar i els dos clics a les estadístiques amb el tipus de dispositiu correcte.
- Torneu a crear el mateix registre i confirmeu que obteniu el mateix enllaç, no un duplicat.
- Suprimiu-lo i confirmeu que
link.deletedarriba al punt de connexió del webhook, si en feu servir.
En producció, vigileu tres coses: el percentatge d'errors de l'API per
codi d'estat, la latència de la redirecció segons una comprovació
sintètica i una conciliació setmanal del nombre d'enllaços entre els
vostres registres i GET /links. Feu la rotació de la clau d'API
periòdicament i cada vegada que algú marxi de l'equip que la té.
Documenteu la integració com un producte intern: els camps que accepta,
la norma dels àlies, el comportament de la pàgina alternativa, els
límits de /me i a qui cal trucar quan una campanya mostra zero clics.
La pròxima persona que la toqui us ho agrairà, i sovint aquesta persona és
qui la va escriure.