Integration & SDK

Der Partner Hub liefert ein Runtime-SDK aus. Konsumenten-Projekte binden nur ein einziges Script-Tag ein — Änderungen an der Client-Logik werden zentral vom Hub ausgeliefert, ohne Redeploy in den Konsumenten.

1. App im Superadmin registrieren

Lege im Superadmin eine neue App an. Du erhältst einen slug und ein HMAC-Secret (nur einmalig sichtbar — sofort speichern).

2. Klick-Tracking: EIN Script-Tag ins HTML

Einbauen in index.html im <head> — oder in TanStack Start im head() von src/routes/__root.tsx. Kein Code kopieren, kein SDK bundlen.

<script
  src="https://partner-program-toolkit.lovable.app/sdk/v1.js"
  data-app="<slug>"
  async
></script>

Das SDK liest ?ref=CODE, setzt Cookie partner_hub_ref (90 Tage), meldet den Klick an den Hub und stellt window.PartnerHub.getRef() bereit.

3. Server-ENV setzen (nur backend)

PARTNER_HUB_URL=https://partner-program-toolkit.lovable.app
PARTNER_HUB_APP=<slug>
PARTNER_HUB_HMAC_SECRET=<secret>

4. Bei Signup melden (Server, HMAC)

Ref-Code aus dem Cookie partner_hub_ref lesen und an den Hub melden:

import { reportSignup } from "@/lib/partner-sdk.server";

await reportSignup({
  code: cookies.get("partner_hub_ref"),
  externalUserId: newUser.id,
  externalEmail: newUser.email,
});

5. Bei bezahlter Rechnung melden (Server, HMAC)

import { reportCommission } from "@/lib/partner-sdk.server";

await reportCommission({
  externalInvoiceId: invoice.id,
  externalUserId: invoice.user_id,
  amountCents: invoice.gross_cents,
});

Endpoints (Referenz)

GET /sdk/v1.js — Runtime-SDK, per Script-Tag im Browser
POST /api/public/track-click — unsigniert, vom SDK
GET /api/public/resolve-ref?code=… — unsigniert
POST /api/public/track-signup — HMAC-signiert (Server)
POST /api/public/track-commission — HMAC-signiert (Server)

Signatur: x-partner-hub-signature = HMAC-SHA256(secret, `$${timestamp}.$${rawBody}`) (hex). Header: x-partner-hub-app, x-partner-hub-timestamp (Millis, ±5 Min).