Browser-SDK installieren

Installiere das SDK einmal über den globalen Skriptmechanismus deines Frameworks. Das folgende Tag ist für einfaches HTML.

Frameworks verwalten den Dokument-head. Verwende im Next.js App Router next/script im Root-Layout. Rendere keinen eigenen head und injiziere dieses Tag nicht mit dangerouslySetInnerHTML.

Rufe die beiden Kernmethoden auf

Verwende JavaScript für relevantes Verhalten ohne entsprechende DOM-Aktivierung. Füge für Links, Buttons, Steuerelemente und Formulare stattdessen HTML-Attribute hinzu.

window.splendorize.action(
  "change_billing_period",
  { placement: "pricing" },
);

<a
  href="/signup"
  data-splendorize-action="start_trial"
  data-splendorize-action-placement="hero"
>
  Start trial
</a>

<form data-splendorize-action="request_demo">
  <!-- Existing fields and submit button -->
</form>

Regeln für Aktionen

• Verwende einen kleingeschriebenen Zweck-Key, der mit einem Buchstaben beginnt, Buchstaben, Zahlen und einzelne Unterstriche enthält und höchstens 64 Zeichen lang ist.
• Verwende denselben Key für mehrere Platzierungen. Annotiere ein Formular einmal direkt am Formular und füge niemals einen programmatischen Aufruf für dieselbe Interaktion hinzu.
• Leite Keys oder Platzierungen niemals aus sichtbarem Text, Sprache, Besucherdaten, Account-IDs, Zeitstempeln oder Experimentvarianten ab.

Rufe conversion erst auf, nachdem der bestehende Anwendungsablauf den Erfolg belegt hat – etwa nach einer erfolgreichen API-Antwort oder in einem Zielzustand, der das Ergebnis bestätigt.

Nachweisstärke

Clientseitig deklariert. Die richtige Platzierung macht das Ereignis aussagekräftig, Browsercode kann jedoch keine authentifizierte Serverautorität liefern.

Wann verwenden

Eine Registrierung, ein Testzugang, ein Wartelisteneintrag oder eine Demoanfrage wurde tatsächlich abgeschlossen und der Browser ist die einzige verfügbare Erfolgsgrenze. Rufe conversion niemals beim auslösenden Klick oder Absenden auf.

const result = await startTrial();

if (result.trialStarted === true) {
  window.splendorize.conversion("trial_started");
}

Wenn dein Backend die erfolgreiche Transaktion kontrolliert, übermittle die Conversion per POST an /v1/conversion und verwende den privaten Site-Key. Akzeptierte Anfragen geben 202 zurück. url ist erforderlich und muss zu einer erlaubten Projektdomain gehören; name, occurredAt, referrer sowie Besucher-, Session- und Seitenaufruf-IDs sind optional.

Nachweisstärke

Authentifizierte Herkunft auf Projektebene. Sie ist stärker als eine Browserdeklaration, belegt aber nicht die Identität einer Person.

Wann verwenden

Dein Backend hat ein Ergebnis bestätigt, das keine Zahlung betrifft. Bewahre den privaten Schlüssel serverseitig auf und wähle diesen Weg, statt dieselbe Browser-Conversion auszulösen.

const response = await fetch("https://cdn.splendorize.com/v1/conversion", {
  method: "POST",
  headers: {
    authorization: "Bearer " + process.env.SPLENDORIZE_PRIVATE_SITE_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: "trial_started",
    url: "https://example.com/welcome",
    occurredAt: new Date().toISOString(),
  }),
});

if (response.status !== 202) {
  throw new Error("Splendorize rejected the conversion");
}

Verbinde Stripe, erfasse stripeMetadata() nach dem Laden des Browser-SDKs und validiere die unterstützten Attributions-Keys in deinem Backend. Bei Checkout im Abonnementmodus fügst du sie sowohl den Metadaten der Checkout Session als auch denen des Abonnements hinzu. Signierte invoice.payment_succeeded-Ereignisse liefern Bruttobetrag, Währung und Zahlungszeitpunkt; Webhooks für Rückerstattungen und Zahlungsstreitigkeiten passen den Nettowert an, während Abonnement-Webhooks Kündigungs- und Churn-Signale ergänzen. Historische Rechnungen werden nicht importiert.

Nachweisstärke

Vom Anbieter belegt für den Status bezahlter Rechnungen, Bruttobetrag, Währung und Zahlungszeitpunkt. Splendorize-Metadaten verbinden die Besucherreise; sie belegen keine Zahlung.

Wann verwenden

Wenn du Käufe auf Basis erfolgreich bezahlter Stripe-Rechnungen oder wiederkehrenden Abonnementumsatz messen musst. Übermittle keine vom Browser bereitgestellten Beträge und löse nicht zusätzlich eine Browser-Conversion aus, nur um dieselbe Zahlung zu beanspruchen.

const attribution = window.splendorize.stripeMetadata();

await fetch("/api/checkout", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ attribution }),
});

const attribution = Object.fromEntries(
  [
    "splendorize_site_id",
    "splendorize_visitor_id",
    "splendorize_session_id",
    "splendorize_page_view_id",
  ].flatMap((key) => {
    const value = requestBody.attribution?.[key];
    return typeof value === "string" && value.length <= 120
      ? [[key, value]]
      : [];
  }),
);

await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items,
  success_url,
  cancel_url,
  metadata: attribution,
  subscription_data: { metadata: attribution },
});

Rufe diese Methoden unter window.splendorize auf. Mit dem personalisierten Loader können alle außer stripeMetadata() vor dem Laden des SDKs eingereiht werden.

action(actionKey, { placement? })

Erfasst eine stabile, zweckbezogene Aktion mit optionaler Platzierung. Die Methode erklärt kein Ergebnis für abgeschlossen.

conversion(name?, properties?)

Erfasst eine clientseitig deklarierte Conversion. Rufe sie erst auf, nachdem die Anwendung den Erfolg bestätigt hat.

payment({ email })

Hasht eine Checkout-E-Mail-Adresse, um sie mit der aktuellen Besucherreise zu verbinden. Die Methode belegt niemals Zahlung, Betrag oder Umsatz.

stripeMetadata()Nach dem Laden des SDKs

Gibt Splendorize-Attributions-IDs zurück, die an Stripe-Metadaten angefügt werden. Die Methode belegt keine Zahlung.

setConsent(allowed)

Erlaubt oder widerruft dauerhaftes Tracking, wenn deine Website eine Einwilligung voraussetzt. false löscht die dauerhafte Attribution.

Der generierte Loader unterstützt außerdem aufrufbare Befehle wie window.splendorize("action", "start_trial"). Bevorzuge im Anwendungscode die benannten Methoden oben, da sie leichter zu lesen sind.

Halte die Implementierung eng begrenzt und gib jedem Signal genau eine Bedeutung.

• Installiere einen globalen Loader und behalte die Einwilligungs- und CSP-Logik der Website bei.
• Bewahre den privaten Site-Key auf dem Server auf; der öffentliche Site-Key darf im Browsercode erscheinen.
• Sende niemals Formularwerte, E-Mail-Adressen, Namen, Telefonnummern, Kunden-IDs oder Geheimnisse in Aktions- oder Conversion-Metadaten.
• Sende pro Interaktion eine semantische Aktion und wähle für jedes Ergebnis genau eine maßgebliche Quelle.
• Behandle Zahlungsattribution als Identitätsverbindung, niemals als Autorisierung oder Zahlungsnachweis.