Irgendwann hört ein Team auf, Links von Hand anzulegen. Das Produkt braucht einen Teilen-Link pro Nutzer, das CMS soll beim Veröffentlichen eines Beitrags eine Kurz-URL erzeugen, das Kampagnentool will einen getrackten Link pro Werbemittel. Eine Entwickler-Integration für trackbare Links mit eigener Domain macht aus dem Shortener eine Funktion, die Ihre Systeme aufrufen.
Diese Anleitung geht die Integration von Anfang bis Ende durch: was Sie entscheiden sollten, bevor Sie Code schreiben, wie Authentifizierung und der Erstellungsaufruf funktionieren, wie Links trackbar werden, ohne die Zuordnung zu beschädigen, welche Sonderfälle bei Weiterleitungen Ärger machen, wo Webhooks ins Bild passen und wie Sie das Ganze testen. Die API von LinkPilot dient als durchgehendes Beispiel. Der Aufbau gilt für die meisten Plattformen.
Zuerst die Architektur festlegen
Vier Entscheidungen, einmal getroffen, ersparen den größten Teil der Nacharbeit.
- Welche Systeme Links erstellen und auf welchen Auslöser hin: ein Veröffentlichungsereignis, eine Nutzeraktion, das Speichern eines Kampagnendatensatzes.
- Welche Felder die Aufrufer bestimmen. Meist das Ziel und die Tags, manchmal ein Kürzel. Selten die Domain, die eine Einstellung pro Workspace oder pro Kunde sein sollte.
- Wie Kampagnendaten auf das Tracking abgebildet werden. Kampagne, Kanal und Platzierung in Ihrem System werden zu Tags am Link und zu UTM-Parametern am Ziel. Legen Sie die Zuordnung fest und packen Sie sie in eine einzige Funktion.
- Direkter Link, Deep Link oder Fallback. Ein Link in eine mobile App braucht einen Fallback im Web für alle, die die App nicht haben. Entscheiden Sie, ob der Shortener das übernimmt oder Ihr Ziel.
Schreiben Sie diese Entscheidungen auf. Die Integration ist größtenteils Verbindungscode, und der sollte langweilig sein.
Mit Schlüsseln pro Workspace authentifizieren
Die API von LinkPilot authentifiziert über Bearer-Schlüssel, die mit lp_live_ beginnen. Sie werden im Dashboard erstellt und stehen in jedem Tarif zur Verfügung, auch im Free-Tarif. Jeder Schlüssel gehört zu einem Workspace. Eine Agentur-Integration nutzt deshalb einen Schlüssel pro Kunden-Workspace, und die Links landen schon durch diesen Aufbau am richtigen Ort.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me liefert Workspace, Tarif, Limits, aktuelle Nutzung und das Anfragekontingent des Schlüssels. Rufen Sie den Endpunkt beim Start auf und schreiben Sie die Limits in Ihre eigenen Logs. So erfahren Sie von einer Obergrenze, bevor eine Kampagne daran scheitert.
Behandeln Sie den Schlüssel wie Zugangsdaten für die Produktion: Speichern Sie ihn in einem Secrets-Manager, nie in einem Repository oder einem Frontend-Bundle. Wenn Sie ihn an jemanden weitergeben müssen, der die Integration baut, schicken Sie ihn über einen Einmal-Link. Die Anleitung zu API-Schlüsseln behandelt Übergabe und Rotation.
Den Link erstellen
Der Erstellungsaufruf nimmt das Ziel und einige optionale Felder entgegen.
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"]
}'
Die Antwort enthält die ID des Links, die Kurz-URL und die Metadaten, die Sie gesendet haben. Speichern Sie die ID neben Ihrem eigenen Datensatz. Mit ihr lesen, ändern oder löschen Sie den Link später. GET /links listet Links mit den neuesten zuerst und Cursor-Paginierung ({ data, next_cursor }), GET /links/{id} und DELETE /links/{id} wirken auf einen einzelnen Link.
Einige Regeln halten die Integration sauber:
- Bauen Sie die Ziel-URL im Code, UTM-Parameter eingeschlossen, aus Ihren Kampagnenfeldern. Von Hand getippte Parameter weichen mit der Zeit ab. Das UTM-Playbook legt die Konventionen fest.
- Lassen Sie die Plattform Kürzel erzeugen, außer ein Mensch wird sie lesen. Wenn Sie Kürzel selbst setzen, leiten Sie sie aus Kampagne, Kanal und Platzierung ab, kleingeschrieben mit Bindestrichen. Bei einem Konflikt hängen Sie ein kurzes Suffix an und versuchen es einmal erneut.
- Machen Sie das Erstellen idempotent. Verknüpfen Sie jeden Erstellungsaufruf mit Ihrer eigenen Datensatz-ID, damit ein erneuter Versuch nach einem Timeout den bestehenden Link findet, statt einen zweiten anzulegen. Bietet die Plattform keinen Idempotenzschlüssel, prüfen Sie vor dem Erstellen mit
GET /links, ob es Ihr Tag oder Kürzel schon gibt. - Massenerstellung heißt Schleife mit Backoff. Halten Sie das Anfragekontingent aus
/meein, warten Sie bei 429 länger und protokollieren Sie jeden Fehler mit dem Datensatz, zu dem er gehörte.
Für Skripte und lokale Werkzeuge bündelt die linkpilot-CLI auf npm dieselben Aufrufe, und der Server @uselinkpilot/mcp stellt sie KI-Agenten zur Verfügung. Beide sind Open Source auf GitHub unter TetraCoreHQ.
Links trackbar machen, ohne die Zuordnung zu beschädigen
Jeder Klick auf einen per API erstellten Link wird genauso erfasst wie bei einem im Dashboard angelegten: Zeitpunkt, Referrer, Gerät, Browser, Land, Region, eine Bot-Kennzeichnung und statt der IP-Adresse ein gesalzener Hash. Das liefert die Zahl auf Link-Ebene. Die Zuordnung auf der Zielseite hängt weiterhin davon ab, dass die URL unverändert ankommt.
- Erhalten Sie die Query-Parameter über die Weiterleitung hinweg. Testen Sie einen Link mit dem Redirect-Checker und prüfen Sie, ob die UTM-Parameter in der finalen URL stehen.
- Vermeiden Sie Ketten. Ein Kurzlink, der auf eine weitere Weiterleitung zeigt, verliert Parameter und Tempo. Zeigen Sie direkt auf die finale Seite.
- Legen Sie fest, was Sie erfassen. Land und Gerät sind zusammengefasste Statistiken. Ein Link pro Nutzer, der mit einem Kundendatensatz verknüpft ist, fällt unter personenbezogene Daten. Der Leitfaden zum modernen Link-Tracking zeigt, was erfasst wird und was bewusst nicht.
- Wecken Sie im Produkt die richtigen Erwartungen. Eine Klickzahl ist keine Conversion-Zahl. Zeigen Sie beide, klar beschriftet.
Sonderfälle bei der Weiterleitung abfangen
- Ziele prüfen. Lehnen Sie Ziele ohne HTTPS, Ihre eigene Shortener-Domain und alles auf einer Sperrliste ab, bevor Sie den Link erstellen. Eine offene Weiterleitung unter Ihrer Marke ist ein Phishing-Werkzeug.
- Abgelaufene, deaktivierte oder fehlende Links. Legen Sie die Fallback-Seite beim Erstellen des Links fest, damit ein toter Kampagnenlink auf der Startseite landet statt auf einer Fehlermeldung. Bei gedruckten Links ändern Sie lieber das Ziel, als den Link jemals ablaufen zu lassen.
- Deep Links. Nutzen Sie ein Ziel, das die App erkennt und sonst auf das Web ausweicht, oder eine Funktion der Plattform dafür. Testen Sie auf beiden Betriebssystemen, mit und ohne installierte App.
- Kodierung. Kodieren Sie die Ziel-URL, bevor Sie sie ins JSON schreiben, besonders wenn sie einen eigenen Query-String enthält. Doppelte Kodierung ist der übliche Fehler.
- Lokalisierung. Wenn ein Kurzlink mehrere Sprachen bedient, erkennen Sie die Sprache auf der Zielseite, nicht im Kürzel.
Webhooks für die wichtigen Ereignisse ergänzen
Mit Webhooks reagiert der Rest Ihres Stacks auf Link-Aktivität, ohne ständig abzufragen. LinkPilot signiert jede Zustellung mit einem HMAC-Signatur-Header und löst bei Ereignissen im Lebenszyklus von Links aus (link.created, link.updated, link.deleted) sowie im Lebenszyklus von Geheimnissen (secret.created, secret.viewed, secret.burned). Prüfen Sie die Signatur vor dem Parsen, bestätigen Sie schnell, verarbeiten Sie aus einer Warteschlange und speichern Sie Ereignis-IDs, damit Wiederholungen keinen Schaden anrichten. Klickdaten sind ein Berichtsstrom und kein Webhook. Lesen Sie sie über Statistiken und Exporte. Die Anleitung zu Webhook-Integrationen beschreibt, wie Sie den Empfänger bauen.
Von Anfang bis Ende testen und dann im Blick behalten
Bevor die Integration eine echte Kampagne berührt:
- Erstellen Sie in einem Staging-Workspace einen Link mit Ihren Test-Tags.
- Prüfen Sie, ob die Antwort die erwartete ID und Kurz-URL enthält.
- Klicken Sie den Link auf einem Handy und einem Laptop an. Prüfen Sie die Weiterleitung, die UTM-Parameter bei der Ankunft und die zwei Klicks in den Statistiken mit den richtigen Gerätetypen.
- Legen Sie denselben Datensatz noch einmal an und prüfen Sie, ob Sie denselben Link erhalten und kein Duplikat.
- Löschen Sie den Link und prüfen Sie, ob
link.deletedan Ihrem Webhook-Endpunkt ankommt, falls Sie einen nutzen.
Im Betrieb beobachten Sie drei Dinge: API-Fehlerraten nach Statuscode, die Latenz der Weiterleitung aus einem synthetischen Check und einen wöchentlichen Abgleich der Link-Anzahl zwischen Ihren Datensätzen und GET /links. Rotieren Sie den API-Schlüssel nach Plan und jedes Mal, wenn jemand das Team verlässt, das ihn verwaltet.
Dokumentieren Sie die Integration wie ein internes Produkt: welche Felder sie annimmt, die Regel für Kürzel, das Fallback-Verhalten, die Limits aus /me und wen man anruft, wenn eine Kampagne null Klicks meldet. Wer sie als Nächstes anfasst, wird dankbar sein, und oft sind Sie das selbst.