Udviklerintegration til oprettelse af sporbare links på eget domæne: en praktisk guide

På et tidspunkt holder et team op med at lave links i hånden. Produktet skal have et delingslink pr. bruger, CMS'et skal lave en kort URL, når et indlæg bliver udgivet, og kampagneværktøjet vil have et sporet link pr. annoncemateriale. En udviklerintegration til oprettelse af sporbare links på eget domæne gør linkforkorteren til en funktion, som dine systemer kalder.

Denne guide gennemgår integrationen fra start til slut: hvad du skal beslutte, før du skriver kode, hvordan godkendelse og oprettelseskaldet virker, hvordan du gør links sporbare uden at ødelægge attributionen, de særtilfælde ved omdirigering, der giver problemer, hvor webhooks passer ind, og hvordan du tester det hele. LinkPilots API er det gennemgående eksempel, men opbygningen gælder for de fleste platforme.

Beslut arkitekturen først

Fire beslutninger, truffet én gang, sparer det meste af omarbejdet.

• Hvilke systemer der opretter links, og hvad der udløser det: en udgivelse, en handling fra en bruger, en kampagnepost, der bliver gemt.
• Hvilke felter kalderen styrer. Som regel destinationen og tags, nogle gange en slug. Sjældent domænet, som bør være en indstilling pr. arbejdsområde eller pr. kunde.
• Hvordan kampagnedata oversættes til sporing. Kampagnen, kanalen og placeringen i dit system bliver til tags på linket og UTM-parametre på destinationen. Beslut koblingen, og læg den i én funktion.
• Direkte link, deep link eller reserveside. Et link ind i en mobilapp skal have en reserveside på nettet til folk, der ikke har appen. Beslut, om linkforkorteren tager sig af det, eller om din destination gør.

Skriv beslutningerne ned. Integrationen er mest limkode, og limkoden bør være kedelig.

Godkend med afgrænsede nøgler

LinkPilots API godkender med bearer-nøgler, der starter med lp_live_, oprettes i dashboardet og findes på alle planer, også Free. Hver nøgle hører til ét arbejdsområde, så en bureauintegration bruger én nøgle pr. kundes arbejdsområde, og linkene havner automatisk det rigtige sted.

curl https://uselinkpilot.com/api/v1/me \
  -H "Authorization: Bearer lp_live_..."

GET /me returnerer arbejdsområdet, planen, grænserne, det aktuelle forbrug og nøglens budget for antal kald. Kald det ved opstart, og vis grænserne i dine egne logs, så du opdager et loft, før en kampagne gør det.

Behandl nøglen som loginoplysninger til produktion: gem den i en hemmelighedsadministrator, aldrig i et repository eller i en frontend-pakke, og når du skal give den til den, der bygger integrationen, så send den via et hemmeligt engangslink. Guiden til API-nøgler gennemgår overdragelsen og rotationen.

Opret linket

Oprettelseskaldet tager destinationen og nogle få valgfrie felter.

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"]
  }'

Svaret indeholder linkets ID, den korte URL og de metadata, du sendte. Gem ID'et ved siden af din egen post. Det er det, du bruger til at læse, opdatere eller slette linket senere. GET /links viser links med de nyeste først og cursor-paginering ({ data, next_cursor }), og GET /links/{id} og DELETE /links/{id} handler på ét link.

Nogle få regler holder integrationen ærlig:

• Byg destinationens URL i koden, inklusive UTM-tags, ud fra dine kampagnefelter. Tags, der tastes i hånden, glider fra hinanden. UTM-playbooken fastlægger konventionerne.
• Lad platformen generere slugs, medmindre et menneske skal læse dem. Når du selv sætter slugs, så afled dem af kampagne, kanal og placering, med små bogstaver og bindestreger, og håndter en konflikt ved at tilføje et kort suffiks og prøve igen én gang.
• Gør oprettelsen idempotent. Knyt hver oprettelse til dit eget post-ID, så et nyt forsøg efter en timeout finder det eksisterende link i stedet for at lave et nyt. Tilbyder platformen ikke en idempotensnøgle, så tjek GET /links for dit tag eller din slug, før du opretter.
• Masseoprettelse er en løkke med backoff. Overhold budgettet for antal kald fra /me, vent og prøv igen ved 429, og log hver fejl sammen med den post, den hørte til.

Til scripts og lokale værktøjer pakker CLI'en linkpilot på npm de samme kald ind, og serveren @uselinkpilot/mcp gør dem tilgængelige for AI-agenter. Begge er open source på GitHub under TetraCoreHQ.

Gør links sporbare uden at ødelægge attributionen

Hvert klik på et link, der er oprettet via API'et, registreres præcis som et link, der er lavet i dashboardet: tidspunkt, henviser, enhed, browser, land, region, en bot-markering og en saltet hash i stedet for IP-adressen. Det giver dig antallet på linkniveau. Attributionen på destinationen afhænger stadig af, at URL'en kommer frem i god behold.

• Bevar forespørgselsparametrene gennem omdirigeringen. Test et link med redirect-tjekkeren, og bekræft, at UTM-tags er med i den endelige URL.
• Undgå kæder. Et kortlink, der omdirigerer til en anden omdirigering, mister parametre og hastighed. Peg på den endelige side.
• Beslut, hvad du indsamler. Land og enhed er samlet statistik. Et link pr. bruger, der kobles til en kundepost, er personoplysninger. Den moderne guide til linksporing viser, hvad der registreres, og hvad der bevidst ikke registreres.
• Afstem forventningerne i produktet. Et antal klik er ikke et antal konverteringer. Vis begge, tydeligt mærket.

Håndter særtilfældene ved omdirigering

• Validering af destinationen. Afvis destinationer uden HTTPS, dit eget forkorterdomæne og alt, der står på en blokeringsliste, før du opretter linket. En åben omdirigering på dit brand er et phishing-værktøj.
• Udløbne, deaktiverede eller manglende links. Beslut reservesiden, når linket oprettes, og sæt den, så et dødt kampagnelink lander på forsiden i stedet for en fejl. For trykte links er det bedre at redigere destinationen end nogensinde at lade dem udløbe.
• Deep links. Brug en destination, der finder ud af, om appen er installeret, og ellers falder tilbage til nettet, eller brug en funktion i platformen til det. Test på begge styresystemer med og uden appen installeret.
• Kodning. URL-kod destinationen, før du lægger den ind i JSON'en, især når den har sin egen forespørgselsstreng. Dobbelt kodning er den sædvanlige fejl.
• Lokalisering. Hvis ét kortlink betjener flere sprog, så find sproget på destinationen, ikke i sluggen.

Tilføj webhooks til de hændelser, der betyder noget

Med webhooks kan resten af din stak reagere på aktivitet på links uden at spørge efter ændringer igen og igen. LinkPilot signerer hver levering med en HMAC-signatur i en header og sender hændelser for linkets livscyklus (link.created, link.updated, link.deleted) og hemmelighedens livscyklus (secret.created, secret.viewed, secret.burned). Verificer signaturen, før du parser, kvitter hurtigt for modtagelsen, behandl fra en kø, og gem hændelses-ID'er, så nye forsøg ikke gør skade. Klikdata er en rapporteringsstrøm og ikke en webhook. Læs dem via statistikken og eksporterne. Guiden til webhook-integrationer gennemgår, hvordan du bygger modtageren.

Test fra start til slut, og bliv ved med at holde øje

Før integrationen rører en rigtig kampagne:

1. Opret et link med dine testtags i et arbejdsområde til test.
2. Bekræft, at svaret har det ID og den korte URL, du forventer.
3. Klik på det fra en telefon og en bærbar. Bekræft omdirigeringen, UTM-tags ved ankomsten og de to klik i statistikken med de rigtige enhedstyper.
4. Opret den samme post igen, og bekræft, at du får det samme link og ikke en dublet.
5. Slet det, og bekræft, at link.deleted når frem til dit webhook-endpoint, hvis du bruger et.

I produktion skal du holde øje med tre ting: fejlraten i API'et fordelt på statuskode, omdirigeringens svartid målt med et syntetisk tjek og en ugentlig afstemning af antallet af links mellem dine poster og GET /links. Roter API-nøglen efter en fast plan, og hver gang nogen forlader det team, der har den.

Dokumenter integrationen som et internt produkt: de felter, den accepterer, reglen for slugs, opførslen med reservesider, grænserne fra /me, og hvem man skal ringe til, når en kampagne rapporterer nul klik. Den næste, der skal arbejde med den, bliver glad, og ofte er det dig selv.

Mere at læse

• Sammenligning af API'er til linkforkortere: Bitly, Dub, Short.io, TinyURL
• Sådan vælger og bruger du en platform til linksporing med webhook-integrationer
• Sådan deler du API-nøgler sikkert
• UTM-parametre: den komplette playbook for 2026