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.
Integration des Partnerprogramms: Diese Integration funktioniert auch nahtlos mit Dub Partners zur Verfolgung von Affiliate-Referenzen und Provisionen. Verwenden Sie Dubs Conversion-Tracking, um Verkäufe Ihren Affiliate-Links zuzuordnen und die Leistung der Partner zu messen. Erfahren Sie mehr über die Einrichtung von Partnerprogrammen in unserem Leitfaden zur Affiliate-Funktion.

​
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. Dubs Klick-ID aus dem dub_id Cookie erfassen, wenn Sie Checkout-Sitzungen erstellen
  2. Die Klick-ID in Ihren Zahlungsmetadaten zusammen mit der externen ID des Kunden speichern
  3. Verkaufsdaten an Dub senden, 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 Conversion-Zuordnung erhalten.

​
Voraussetzungen

Bevor Sie diese Integration einrichten, stellen Sie sicher, dass Sie:
  1. Ein Dub-Konto mit einem Arbeitsbereich haben
  2. Conversion-Tracking 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

Conversion-Tracking in Dub aktivieren

Aktivieren Sie in Ihrem Dub-Dashboard das Conversion-Tracking 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 des Conversion-Trackings 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 Scope.
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!

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

​
Implementierungsleitfaden

​
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: 'customer@example.com',
      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

Webhook-Bereich öffnen

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

Dub auswählen

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 anfängliche Abonnements als auch wiederkehrende 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 ohne Steuerverrechnung 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 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

Klicken Sie ID früh erfassen: 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 ID immer in Metadaten einfügen: Ohne die Klick-ID kann Dub keine Einnahmen Ihren Links zuordnen
  • Externe IDs konsistent verwenden: Übergeben Sie die gleiche Kunden-ID, die Sie in Ihrem System verwenden, für eine genaue Kundenanalyse
  • Organischen Verkehr angemessen behandeln: Setzen Sie webhook.cancel = true, wenn keine Klick-ID vorhanden ist, um unnötige API-Aufrufe zu vermeiden
  • Mit Beispielzahlungen testen: Ü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 den conversions.write Scope 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
  • Verifizieren Sie, dass der Webhook bei payment.succeeded Ereignissen ausgelöst wird
  • Bestätigen Sie, dass das Conversion-Tracking 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
  • Überprüfen Sie, ob Sie die Klick-ID vor der Erstellung der Checkout-Sitzung erfassen
  • 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 vermeiden

​
Zusätzliche Ressourcen

Dub Conversions Dokumentation

Erfahren Sie mehr über Dubs Conversion-Tracking und Analysefunktionen.

Dub Track Sale API

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

Dub Dashboard

Greifen Sie auf Ihr Dub-Dashboard zu, um Conversion-Analysen 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 support@dodopayments.com für Unterstützung bei der Integration.