Jossain vaiheessa tiimi lakkaa tekemästä linkkejä käsin. Tuote tarvitsee jakolinkin jokaiselle käyttäjälle, julkaisujärjestelmän pitäisi luoda lyhyt URL-osoite, kun kirjoitus julkaistaan, ja kampanjatyökalu haluaa seuratun linkin jokaiselle mainosversiolle. Kehittäjäintegraatio seurattavien brändättyjen linkkien luomiseen tekee lyhentäjästä funktion, jota järjestelmäsi kutsuvat.
Tämä opas käy integraation läpi alusta loppuun: mitä päättää ennen koodin kirjoittamista, miten tunnistautuminen ja luontikutsu toimivat, miten linkeistä tehdään seurattavia rikkomatta attribuutiota, mitkä uudelleenohjausten erikoistapaukset aiheuttavat ongelmia, miten webhookit sopivat kokonaisuuteen ja miten integraatio testataan. Esimerkkinä on LinkPilotin API, mutta sama rakenne pätee useimpiin alustoihin.
Päätä arkkitehtuuri ensin
Neljä kerran tehtyä päätöstä säästää suurimman osan uudelleentyöstä.
- Mitkä järjestelmät luovat linkkejä ja mistä laukaisijasta: julkaisutapahtumasta, käyttäjän toiminnosta vai kampanjatietueen tallentamisesta.
- Mitä kenttiä kutsujat hallitsevat. Yleensä kohdeosoitetta ja tunnisteita, joskus polkutunnusta. Harvoin verkkotunnusta, jonka pitäisi olla työtila- tai asiakaskohtainen asetus.
- Miten kampanjatiedot muunnetaan seurannaksi. Järjestelmäsi kampanjasta, kanavasta ja sijoittelusta tulee linkin tunnisteita ja kohdeosoitteen UTM-parametreja. Päätä muunnos ja kirjoita se yhteen funktioon.
- Suora linkki, syvälinkki vai varasivu. Mobiilisovellukseen vievä linkki tarvitsee verkkosivuversion niille, joilla sovellusta ei ole. Päätä, hoitaako sen lyhentäjä vai kohdesivusi.
Kirjoita nämä ylös. Integraatio on enimmäkseen liimakoodia, ja liimakoodin pitää olla tylsää.
Tunnistaudu rajatuilla avaimilla
LinkPilotin API tunnistaa kutsujan bearer-avaimilla, jotka alkavat merkkijonolla lp_live_. Avaimet luodaan hallintapaneelissa, ja ne ovat käytössä kaikissa paketeissa, myös Free-paketissa. Jokainen avain kuuluu yhteen työtilaan, joten toimiston integraatio käyttää yhtä avainta asiakkaan työtilaa kohden, ja linkit päätyvät rakenteen ansiosta oikeaan paikkaan.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me palauttaa työtilan, paketin, rajat, nykyisen käytön ja avaimen pyyntökiintiön. Kutsu sitä käynnistyksen yhteydessä ja kirjaa rajat omiin lokeihisi, niin saat tietää ylärajasta ennen kuin kampanja törmää siihen.
Käsittele avainta tuotantoympäristön kirjautumistietona: säilytä se salaisuuksien hallintapalvelussa, älä koskaan koodivarastossa tai käyttöliittymän koodipaketissa, ja kun joudut antamaan sen integraatiota rakentavalle henkilölle, lähetä se kertakäyttöisellä salaisella linkillä. API-avainten opas käsittelee luovutuksen ja kierrätyksen.
Luo linkki
Luontikutsu ottaa kohdeosoitteen ja muutaman valinnaisen kentän.
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"]
}'
Vastauksessa on linkin tunnus, lyhyt URL-osoite ja lähettämäsi metatiedot. Tallenna tunnus oman tietueesi viereen: sillä luet, päivität tai poistat linkin myöhemmin. GET /links listaa linkit uusimmasta alkaen kursoripohjaisella sivutuksella ({ data, next_cursor }), ja GET /links/{id} sekä DELETE /links/{id} käsittelevät yhtä linkkiä.
Muutama sääntö pitää integraation luotettavana:
- Rakenna kohdeosoite koodissa UTM-parametreineen kampanjasi kentistä. Käsin kirjoitetut parametrit lipsuvat. UTM-käsikirja määrittää käytännöt.
- Anna alustan luoda polkutunnukset, ellei ihminen lue niitä. Jos asetat polkutunnukset itse, johda ne kampanjasta, kanavasta ja sijoittelusta pienillä kirjaimilla ja väliviivoilla, ja hoida ristiriita lisäämällä lyhyt pääte ja yrittämällä kerran uudelleen.
- Tee luonnista idempotentti. Sido jokainen luontikutsu omaan tietuetunnukseesi, jotta aikakatkaisun jälkeinen uusi yritys löytää olemassa olevan linkin eikä tee toista. Jos alusta ei tarjoa idempotenssiavainta, tarkista ennen luontia kutsulla
GET /links, löytyykö tunnisteesi tai polkutunnuksesi jo. - Massaluonti on silmukka, jossa on viive. Noudata kutsun
/mekertomaa pyyntökiintiötä, hidasta vastauksen 429 kohdalla ja kirjaa jokainen epäonnistuminen sen tietueen kanssa, johon se liittyi.
Skripteihin ja paikallisiin työkaluihin npm:stä löytyy linkpilot CLI, joka käyttää samoja kutsuja, ja palvelin @uselinkpilot/mcp tarjoaa ne tekoälyagenteille. Molemmat ovat avointa lähdekoodia GitHubissa TetraCoreHQ-tilin alla.
Tee linkeistä seurattavia rikkomatta attribuutiota
Jokainen klikkaus API:lla luotuun linkkiin kirjataan täsmälleen kuten hallintapaneelissa tehtyyn: aika, viittaava sivu, laite, selain, maa, alue, bottimerkintä ja suolattu tiiviste IP-osoitteen sijaan. Siitä saat linkkikohtaisen klikkausmäärän. Kohdesivun attribuutio riippuu silti siitä, että URL-osoite saapuu perille ehjänä.
- Säilytä kyselyparametrit uudelleenohjauksen läpi. Testaa linkki uudelleenohjausten tarkistimella ja varmista, että UTM-parametrit ovat lopullisessa URL-osoitteessa.
- Vältä ketjuja. Lyhytlinkki, joka ohjaa toiseen uudelleenohjaukseen, menettää parametreja ja nopeutta. Ohjaa suoraan lopulliselle sivulle.
- Päätä, mitä keräät. Maa ja laite ovat yhteenlaskettuja tilastoja. Käyttäjäkohtainen linkki, joka on yhdistetty asiakastietueeseen, on henkilötieto. Nykyaikainen opas linkkien seurantaan luettelee, mitä kirjataan ja mitä tarkoituksella jätetään kirjaamatta.
- Kerro tuotteessa, mitä luvut ovat. Klikkausten määrä ei ole konversioiden määrä. Näytä molemmat, nimettyinä.
Hoida uudelleenohjausten erikoistapaukset
- Kohdeosoitteen tarkistus. Hylkää ennen linkin luontia kohteet, jotka eivät ole HTTPS-osoitteita, oma lyhentäjäsi verkkotunnus ja kaikki estolistalla olevat. Avoin uudelleenohjaus brändisi nimissä on tietojenkalastelun työkalu.
- Vanhentuneet, käytöstä poistetut tai puuttuvat linkit. Päätä varasivu linkkiä luodessa ja aseta se, jotta päättyneen kampanjan linkki vie etusivulle eikä virhesivulle. Painetuissa linkeissä on parempi muokata kohdeosoitetta kuin antaa linkin koskaan vanhentua.
- Syvälinkit. Käytä kohdetta, joka tunnistaa sovelluksen ja palaa tarvittaessa verkkosivulle, tai alustan omaa ominaisuutta siihen. Testaa molemmilla käyttöjärjestelmillä sekä sovelluksen kanssa että ilman sitä.
- Koodaus. URL-koodaa kohdeosoite ennen kuin laitat sen JSON-dataan, varsinkin jos siinä on oma kyselymerkkijono. Kaksinkertainen koodaus on tavallisin virhe.
- Lokalisointi. Jos yksi lyhytlinkki palvelee useaa kieltä, tunnista kieli kohdesivulla, älä polkutunnuksessa.
Lisää webhookit tärkeille tapahtumille
Webhookien avulla muu järjestelmäsi voi reagoida linkkien tapahtumiin ilman jatkuvaa kyselyä. LinkPilot allekirjoittaa jokaisen toimituksen HMAC-allekirjoitusotsakkeella ja lähettää tapahtumat linkin elinkaaresta (link.created, link.updated, link.deleted) ja salaisuuden elinkaaresta (secret.created, secret.viewed, secret.burned). Tarkista allekirjoitus ennen jäsentämistä, kuittaa nopeasti, käsittele jonosta ja tallenna tapahtumien tunnukset, jotta uudelleenyritykset eivät aiheuta haittaa. Klikkaustiedot ovat raportointivirta eivätkä webhook: lue ne tilastoista ja vienneistä. Webhook-integraatioiden opas käsittelee vastaanottajan rakentamista.
Testaa alusta loppuun ja seuraa jatkossakin
Ennen kuin integraatio koskee oikeaan kampanjaan:
- Luo linkki testitunnisteillasi testityötilassa.
- Varmista, että vastauksessa on odottamasi tunnus ja lyhyt URL-osoite.
- Klikkaa sitä puhelimella ja kannettavalla. Varmista uudelleenohjaus, UTM-parametrit perillä ja kaksi klikkausta tilastoissa oikeilla laitetyypeillä.
- Luo sama tietue uudelleen ja varmista, että saat saman linkin etkä kaksoiskappaletta.
- Poista linkki ja varmista, että
link.deletedsaapuu webhook-päätepisteeseesi, jos käytät sellaista.
Tuotannossa seuraa kolmea asiaa: API-virheiden osuutta tilakoodeittain, uudelleenohjauksen viivettä synteettisellä tarkistuksella ja viikoittaista täsmäytystä omien tietueidesi ja kutsun GET /links linkkimäärien välillä. Kierrätä API-avain aikataulun mukaan ja aina, kun joku lähtee avainta hallussaan pitävästä tiimistä.
Dokumentoi integraatio kuin sisäinen tuote: mitä kenttiä se hyväksyy, polkutunnusten sääntö, varasivun toiminta, kutsun /me rajat ja kenelle soitetaan, kun kampanja raportoi nolla klikkausta. Seuraava, joka koskee siihen, on kiitollinen, ja usein se olet sinä itse.