Zum Hauptinhalt springen

​
Einführung

Dub ist eine leistungsstarke Link-Management-Plattform, die Ihnen hilft, kurze Links zu erstellen, zu teilen und zu verfolgen. Durch die Integration von Dodo Payments mit Dub können Sie automatisch Verkaufsumwandlungsereignisse verfolgen, wenn Kunden Käufe abschließen, sodass Sie den ROI Ihrer Marketingkampagnen und Empfehlungsprogramme messen können. Ein “Verkauf”-Ereignis wird in Dub aufgezeichnet, wenn ein Kunde:
  • Eine einmalige Zahlung abschließt
  • Ein kostenpflichtiges Abonnement abonniert
  • Eine wiederkehrende Abonnementzahlung leistet
Diese Integration erfordert ein Dub-Konto mit aktivierter Umwandlungsverfolgung für Ihre Links.

​
So funktioniert es

Dub verfolgt Besucher über eine eindeutige Klick-ID (dub_id), die in einem Cookie gespeichert wird, wenn Benutzer auf Ihre Dub-Shortlinks klicken. Um Verkäufe Ihren Links zuzuordnen, müssen Sie:
  1. Erfassen Sie Dubs Klick-ID aus dem dub_id Cookie, wenn Sie Checkout-Sitzungen erstellen
  2. Speichern Sie die Klick-ID in Ihren Zahlungsmetadaten zusammen mit der externen ID des Kunden
  3. Senden Sie Verkaufsdaten an Dub, wenn Zahlungen erfolgreich sind, unter Verwendung ihrer Track API
Dies ermöglicht es Dub, erfolgreiche Verkäufe mit dem ursprünglichen Link-Klick abzugleichen, sodass Sie eine vollständige Umwandlungszuordnung erhalten.

​
Voraussetzungen

Bevor Sie diese Integration einrichten, stellen Sie sicher, dass Sie:
  1. Ein Dub-Konto mit einem Arbeitsbereich haben
  2. Die Umwandlungsverfolgung für Ihre Links aktiviert ist
  3. Ihren Dub-API-Schlüssel (verfügbar in Ihrem Dub-Dashboard unter Einstellungen → API-Schlüssel)

​
Erste Schritte

1

Umwandlungsverfolgung in Dub aktivieren

Aktivieren Sie in Ihrem Dub-Dashboard die Umwandlungsverfolgung für die Links, für die Sie Verkäufe verfolgen möchten. Dadurch kann Dub Verkaufsereignisse aufzeichnen, wenn Kunden Käufe abschließen.
Erfahren Sie mehr über die Aktivierung der Umwandlungsverfolgung in der Dub-Dokumentation.
2

Holen Sie sich Ihren Dub-API-Schlüssel

Navigieren Sie zu Ihrem Dub-Dashboard → Einstellungen → API-Schlüssel und erstellen Sie einen neuen API-Schlüssel mit conversions.write Berechtigung.
Halten Sie Ihren API-Schlüssel sicher und geben Sie ihn niemals im Client-Code preis.
3

Klick-ID im Checkout erfassen

Erfassen Sie beim Erstellen einer Checkout-Sitzung die Dub-Klick-ID aus dem Cookie und fügen Sie sie Ihren Zahlungsmetadaten hinzu.
4

Verkaufsdaten über Webhook senden

Konfigurieren Sie einen Webhook, um Verkaufsdaten an Dubs Track API zu senden, wenn Zahlungen erfolgreich sind.
5

Fertig!

Verkaufsumwandlungsereignisse erscheinen jetzt in Ihrem Dub-Analyse-Dashboard mit vollständiger Zuordnung zu Ihren Links.

​
Implementierungsanleitung

​
Schritt 1: Klick-ID und Kunden-ID zu den Checkout-Metadaten hinzufügen

Beim Erstellen einer Checkout-Sitzung erfassen Sie die Dub-Klick-ID aus dem Cookie und fügen Sie sie Ihren Zahlungsmetadaten zusammen mit der externen ID Ihres Kunden hinzu. 
import { cookies } from 'next/headers';
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createCheckout(productId: string, customerId: string) {
  // Capture Dub click ID from cookie
  const dubClickId = cookies().get('dub_id')?.value;

  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: '[email protected]',
      name: 'John Doe',
    },
    product_id: productId,
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

​
Schritt 2: Verkaufsdaten an Dub senden

Konfigurieren Sie einen Webhook-Endpunkt, um Verkaufsdaten an Dubs Track API zu senden, wenn Zahlungen erfolgreich sind.
1

Öffnen Sie den Webhook-Bereich

Navigieren Sie in Ihrem Dodo Payments-Dashboard zu Webhooks → + Endpunkt hinzufügen und erweitern Sie das Dropdown-Menü für Integrationen.
Endpunkt hinzufügen und Dropdown für Integrationen
2

Wählen Sie Dub aus

Wählen Sie die Dub-Integrationskarte aus.
3

API-Schlüssel eingeben

Geben Sie Ihren Dub-API-Schlüssel im Konfigurationsfeld ein.
API-Schlüssel hinzufügen
4

Transformation konfigurieren

Bearbeiten Sie den Transformationscode, um Zahlungsdaten für Dubs Track Sale API zu formatieren.
5

Testen & Erstellen

Testen Sie mit Beispielpayloads und klicken Sie auf Erstellen, um die Integration zu aktivieren.

​
Transformationscode-Beispiele

​
Grundlegende Verkaufsverfolgung

Verfolgen Sie Verkäufe, wenn Zahlungen erfolgreich sind:
basic_sale.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    // Only send to Dub if click ID exists in metadata
    if (payment.metadata && payment.metadata.dub_click_id) {
      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount, // Ensure the amount is in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          customer_email: payment.customer.email,
          customer_name: payment.customer.name,
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Abonnementverkäufe verfolgen

Verfolgen Sie sowohl die anfänglichen Abonnements als auch die wiederkehrenden Zahlungen:
subscription_sale.js
function handler(webhook) {
  const data = webhook.payload.data;

  // Track initial subscription activation
  if (webhook.eventType === "subscription.active") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount, // Amount in cents
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: data.subscription_id,
        eventName: "Subscription Started",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          billing_interval: data.payment_frequency_interval,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  // Track recurring subscription payments
  if (webhook.eventType === "subscription.renewed") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount,
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: `${data.subscription_id}_${Date.now()}`,
        eventName: "Subscription Renewed",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  return webhook;
}

​
Verkäufe mit Steuerexklusion verfolgen

Senden Sie nur den Betrag vor Steuern an Dub für eine genaue Umsatzverfolgung:
sale_without_tax.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Calculate pre-tax amount (total minus tax)
      const preTaxAmount = payment.total_amount - (payment.tax || 0);

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: preTaxAmount, // Pre-tax amount in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          total_amount: payment.total_amount,
          tax_amount: payment.tax || 0,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Verkäufe mit benutzerdefinierten Ereignisnamen verfolgen

Verwenden Sie benutzerdefinierte Ereignisnamen, um verschiedene Arten von Verkäufen zu kategorisieren:
custom_events.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Determine event name based on payment type
      let eventName = "Purchase";
      if (payment.subscription_id) {
        eventName = "Subscription Purchase";
      } else if (payment.metadata && payment.metadata.is_upgrade) {
        eventName = "Plan Upgrade";
      }

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount,
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        eventName: eventName,
        metadata: {
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Alternative: Client-seitige Implementierung

Wenn Sie Verkäufe lieber von Ihrem Server aus verfolgen möchten, anstatt Webhooks zu verwenden, können Sie Dubs Track API direkt nach einer erfolgreichen Zahlung aufrufen: 
'use server';

import { Dub } from 'dub';

const dub = new Dub();

export async function trackSale(
  paymentId: string,
  clickId: string,
  customerId: string,
  amount: number,
  currency: string
) {
  await dub.track.sale({
    clickId: clickId,
    externalId: customerId,
    amount: amount,
    currency: currency,
    paymentProcessor: 'dodo',
    invoiceId: paymentId,
  });
}

​
Best Practices

Erfassen Sie die Klick-ID frühzeitig: Speichern Sie die Dub-Klick-ID so früh wie möglich in Ihrem Checkout-Prozess, um eine genaue Zuordnung sicherzustellen, selbst wenn der Benutzer weg navigiert und später zurückkehrt.
  • Klicken Sie immer auf die ID in den Metadaten: Ohne die Klick-ID kann Dub keine Einnahmen Ihren Links zuordnen
  • Verwenden Sie externe IDs konsistent: Übergeben Sie die gleiche Kunden-ID, die Sie in Ihrem System verwenden, für eine genaue Analyse auf Kundenebene
  • Behandeln Sie organischen Verkehr elegant: Setzen Sie webhook.cancel = true, wenn keine Klick-ID vorhanden ist, um unnötige API-Aufrufe zu vermeiden
  • Testen Sie mit Beispielzahlungen: Überprüfen Sie, ob die Integration korrekt funktioniert, bevor Sie live gehen
  • Überwachen Sie Ihr Dub-Dashboard: Überprüfen Sie, ob Verkäufe korrekt mit der richtigen Zuordnung angezeigt werden

​
Wichtige Hinweise

  • Betragsformat: Dub erwartet Beträge in Cent (z.B. $10.00 = 1000)
  • Währung: Verwenden Sie ISO 4217-Währungscodes (USD, EUR, GBP usw.)
  • Kostenlose Testversionen: Zahlungen von $0 werden nicht als Verkäufe verfolgt
  • Rückerstattungen: Erwägen Sie, Rückerstattungen separat zu verfolgen, wenn dies für eine genaue Umsatzberichterstattung erforderlich ist

​
Fehlersuche

  • Überprüfen Sie, ob Ihr Dub-API-Schlüssel korrekt ist und die conversions.write Berechtigung hat
  • Stellen Sie sicher, dass die dub_click_id erfasst und in den Zahlungsmetadaten gespeichert wird
  • Überprüfen Sie, ob die Webhook-Transformation das Payload korrekt formatiert
  • Vergewissern Sie sich, dass der Webhook bei payment.succeeded Ereignissen ausgelöst wird
  • Bestätigen Sie, dass die Umwandlungsverfolgung für Ihre Dub-Links aktiviert ist
  • Bestätigen Sie, dass Benutzer auf Ihre Dub-Shortlinks vor dem Checkout klicken
  • Überprüfen Sie, ob das dub_id Cookie korrekt auf Ihrer Domain gesetzt wird
  • Stellen Sie sicher, dass die Klick-IDs zwischen der Erstellung des Checkouts und dem Abschluss der Zahlung übereinstimmen
  • Vergewissern Sie sich, dass Sie die Klick-ID erfassen, bevor Sie die Checkout-Sitzung erstellen
  • Validieren Sie, dass die JSON-Struktur dem Format der Dub Track Sale API entspricht
  • Überprüfen Sie, ob alle erforderlichen Felder (clickId, externalId, amount) vorhanden sind
  • Stellen Sie sicher, dass der Betrag in Cent (ganzzahlig, nicht dezimal) angegeben ist
  • Überprüfen Sie, ob die API-Endpunkt-URL korrekt ist: https://api.dub.co/track/sale
  • Testen Sie die Transformation mit Beispiel-Webhook-Payloads
  • Stellen Sie sicher, dass Sie nur bei payment.succeeded Ereignissen verfolgen, nicht bei payment.processing
  • Verwenden Sie eindeutige invoiceId Werte für jeden Verkauf
  • Fügen Sie für Abonnements Zeitstempel oder Abrechnungszeiträume hinzu, um Duplikate bei Erneuerungen zu verhindern

​
Zusätzliche Ressourcen

Dub Conversions Dokumentation

Erfahren Sie mehr über Dubs Umwandlungsverfolgung und Analysefunktionen.

Dub Track Sale API

Sehen Sie die vollständige API-Referenz für Dubs Track Sale-Endpunkt.

Dub Dashboard

Greifen Sie auf Ihr Dub-Dashboard zu, um Umwandlungsanalysen und Zuordnungsdaten anzuzeigen.

Webhook-Ereignisleitfaden

Erfahren Sie mehr über alle verfügbaren Dodo Payments Webhook-Ereignisse.
Brauchen Sie Hilfe? Kontaktieren Sie den Dodo Payments-Support unter [email protected] für Unterstützung bei der Integration.