Segment

Einführung

Die Segment-Integration sendet Dodo Payments-Ereignisse als Track- und Identify-Aufrufe an die HTTP Tracking API von Segment. Segment leitet Zahlungs-, Abonnement- und Kundendaten anschließend an die Analyse-, Marketing- und Warehouse-Tools weiter, die mit Ihrem Workspace verbunden sind – aus einem Katalog mit mehr als 300 Zielen.

Für diese Integration benötigen Sie den Write Key einer HTTP API-Quelle in Ihrem Segment-Workspace. Außerdem benötigen Sie Zugriff auf Developer → Webhooks im Dodo Payments-Dashboard.

Erste Schritte

Open the Webhook Section

Gehen Sie im Dodo Payments-Dashboard zu Entwickler → Webhooks und klicken Sie auf Endpunkt hinzufügen.

Dialog zum Hinzufügen eines Endpunkts mit ausgewähltem Segment im Dropdown-Menü „Integration“ und den Schritten zum Verbinden von Segment

Select Segment

Wählen Sie unter Integration die Option Segment aus. Das Dashboard trägt die Endpoint URL und den Transformationscode für Segment ein.

Enter Write Key

Gehen Sie in Segment zu Connections → Sources und öffnen oder erstellen Sie eine HTTP API-Quelle. Kopieren Sie den Write Key aus den Einstellungen der Quelle und fügen Sie ihn unter API key ein.

Select Events

Wählen Sie unter Subscribed events nur die Ereignisse aus, die Ihre Transformation verarbeitet. Die Beispiele auf dieser Seite verwenden payment.succeeded, subscription.active und subscription.cancelled.

Configure Transformation

Bearbeiten Sie unter Transformation code den Handler, um Ereignisse für die Track- oder Identify API von Segment zu formatieren. Beginnen Sie mit den Beispielen.

Test & Create

Wählen Sie unter Test this code einen Ereignistyp aus und klicken Sie auf Simulate, um den Aufruf an Segment in der Vorschau anzuzeigen. Klicken Sie anschließend auf Create endpoint.

Switch to Basic Authentication

Dodo Payments sendet den Wert von API key als Bearer-Token. Die HTTP API von Segment akzeptiert jedoch einen Write Key über Basic authentication oder ein writeKey-Feld im Body. Öffnen Sie direkt nach dem Erstellen des Endpunkts dessen Tab Advanced. Geben Sie unter Custom headers in der ausgeblendeten Zeile Authorization einen neuen Wert ein: Basic, ein Leerzeichen und die Base64-Kodierung Ihres Write Key mit einem angehängten Doppelpunkt. Klicken Sie anschließend auf Save. Beispielsweise gibt echo -n 'YOUR_WRITE_KEY:' | base64 den kodierten Wert aus.

Done

Subscribed events erreichen nun Segment, das sie an Ihre verbundenen Ziele weiterleitet.

Beispiele für Transformationscode

Jeder Handler setzt webhook.url auf einen Segment-API-Endpunkt und ersetzt webhook.payload durch den Aufruf. Die Beträge von Dodo Payments werden in der kleinsten Währungseinheit angegeben, daher teilen die Beispiele durch 100. Verwenden Sie bei Währungen ohne Dezimalstellen wie JPY und KRW den Betrag unverändert.

Zahlungsereignisse mit Track erfassen

Erfassen Sie ein Payment Completed-Ereignis, wenn eine Zahlung erfolgreich ist:

track_payments.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/track";
    webhook.payload = {
      userId: p.customer.customer_id,
      event: "Payment Completed",
      properties: {
        amount: (p.total_amount / 100).toFixed(2),
        currency: p.currency || "USD",
        payment_method: p.payment_method || "unknown",
        payment_id: p.payment_id,
        customer_email: p.customer.email,
        customer_name: p.customer.name
      },
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}

Lebenszyklus von Abonnements mit Track erfassen

Erfassen Sie die Ereignisse Subscription Started und Subscription Cancelled:

track_subscriptions.js

function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Started",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
          frequency: s.payment_frequency_interval,
          next_billing: s.next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Cancelled",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          cancelled_at: s.cancelled_at,
          cancel_at_next_billing: s.cancel_at_next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}

Kundeneigenschaften mit Identify erfassen

Aktualisieren Sie die Merkmale des Kunden nach jeder erfolgreichen Zahlung. Jeder Identify-Aufruf setzt die Merkmale auf die gesendeten Werte. Diese Merkmale beschreiben daher die letzte Zahlung:

identify_customer.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/identify";
    webhook.payload = {
      userId: p.customer.customer_id,
      traits: {
        email: p.customer.email,
        name: p.customer.name,
        last_payment_amount: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || "unknown",
        last_payment_date: webhook.payload.timestamp
      }
    };
  }
  return webhook;
}

Tipps

Verwenden Sie in Ihrer Integration konsistente Ereignisnamen, beispielsweise das Objekt- und Aktionsformat von Segment in Payment Completed.
Fügen Sie die Eigenschaften ein, die Sie für Analysen und Segmentierung benötigen.
Setzen Sie timestamp anhand von timestamp des Ereignisses, damit Segment den Zeitpunkt des Ereignisses und nicht den Zeitpunkt des Eingangs erfasst.
Verwenden Sie die Dodo Payments customer_id als userId, damit jeder Aufruf für einen Kunden demselben Segment-Benutzer zugeordnet wird.

Fehlerbehebung

Events Not Appearing in Segment

Prüfen Sie, ob der Write Key zu einer HTTP API-Quelle gehört und der Authorization-Header Basic authentication verwendet.
Segment gibt für die meisten Anfragen 200 zurück, auch für solche, die nicht akzeptiert werden. Eine erfolgreiche Zustellung in den Dodo Payments-Logs belegt daher nicht, dass das Ereignis angekommen ist. Prüfen Sie den Debugger der Quelle in Segment.
Prüfen Sie, ob die Ereignisnamen den Namenskonventionen von Segment entsprechen.
Prüfen Sie, ob jeder Aufruf userId setzt. Segment lehnt einen Aufruf ab, der weder ein userId noch ein anonymousId enthält.
Prüfen Sie die Rate Limits der HTTP API von Segment. Segment empfiehlt, unter 1.000 Anfragen pro Sekunde und Workspace zu bleiben.
Wenn Ihr Workspace die EU-Region von Segment verwendet, senden Sie Aufrufe stattdessen an https://events.eu1.segmentapis.com/v1/track und https://events.eu1.segmentapis.com/v1/identify.

Transformation Errors

Prüfen Sie, ob die Payload dem API-Format von Segment entspricht.
Prüfen Sie, ob alle erforderlichen Felder vorhanden sind. Track erfordert event, und sowohl Track als auch Identify erfordern ein userId oder ein anonymousId.
Prüfen Sie, ob die Ereignisnamen Zeichenfolgen und keine Objekte sind.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Einführung

Erste Schritte

Beispiele für Transformationscode

Zahlungsereignisse mit Track erfassen

Lebenszyklus von Abonnements mit Track erfassen

Kundeneigenschaften mit Identify erfassen

Tipps

Fehlerbehebung

​Einführung

​Erste Schritte

​Beispiele für Transformationscode

​Zahlungsereignisse mit Track erfassen

​Lebenszyklus von Abonnements mit Track erfassen

​Kundeneigenschaften mit Identify erfassen

​Tipps

​Fehlerbehebung

Einführung

Erste Schritte

Beispiele für Transformationscode

Zahlungsereignisse mit Track erfassen

Lebenszyklus von Abonnements mit Track erfassen

Kundeneigenschaften mit Identify erfassen

Tipps

Fehlerbehebung