Segment

Giới thiệu

Tích hợp Segment gửi các sự kiện Dodo Payments đến HTTP Tracking API của Segment dưới dạng các lệnh gọi Track và Identify. Sau đó, Segment chuyển tiếp dữ liệu thanh toán, subscription và customer đến các công cụ analytics, marketing và warehouse được kết nối với workspace của bạn, từ danh mục hơn 300 destination.

Tích hợp này yêu cầu Write Key của một source HTTP API trong workspace Segment của bạn. Bạn cũng cần quyền truy cập Developer → Webhooks trong dashboard Dodo Payments.

Bắt đầu

Open the Webhook Section

Trong dashboard Dodo Payments, đi đến Developer → Webhooks và nhấp vào Add endpoint.

Add endpoint dialog with Segment selected in the Integration dropdown and the How to connect Segment steps

Select Segment

Trong Integration, chọn Segment. Dashboard sẽ tự điền Endpoint URL và mã chuyển đổi cho Segment.

Enter Write Key

Trong Segment, đi đến Connections → Sources và mở hoặc tạo một source HTTP API. Sao chép Write Key từ phần cài đặt của source rồi dán vào API key.

Select Events

Trong Subscribed events, chỉ chọn các sự kiện mà transformation của bạn xử lý. Các ví dụ trên trang này sử dụng payment.succeeded, subscription.active và subscription.cancelled.

Configure Transformation

Trong Transformation code, chỉnh sửa handler để định dạng các sự kiện cho Track hoặc Identify API của Segment. Bắt đầu từ các ví dụ.

Test & Create

Trong Test this code, chọn một loại sự kiện và nhấp vào Simulate để xem trước lệnh gọi đến Segment. Sau đó nhấp vào Create endpoint.

Switch to Basic Authentication

Dodo Payments gửi giá trị API key dưới dạng bearer token, nhưng HTTP API của Segment chấp nhận Write Key thông qua Basic authentication hoặc một trường writeKey trong body. Ngay sau khi tạo endpoint, mở tab Advanced của endpoint đó. Trong Custom headers, nhập một giá trị mới vào hàng Authorization bị ẩn: Basic, một khoảng trắng và chuỗi mã hóa Base64 của Write Key có thêm dấu hai chấm ở cuối. Sau đó nhấp vào Save. Ví dụ, echo -n 'YOUR_WRITE_KEY:' | base64 sẽ in ra giá trị đã mã hóa.

Done

Các sự kiện đã đăng ký hiện sẽ đến Segment, nơi chuyển tiếp chúng đến các destination đã kết nối của bạn.

Ví dụ về Transformation code

Mỗi handler đặt webhook.url thành một endpoint API của Segment và thay webhook.payload bằng lệnh gọi. Các amount của Dodo Payments được tính theo đơn vị tiền tệ nhỏ nhất, vì vậy các ví dụ chia cho 100. Đối với các loại tiền tệ không có chữ số thập phân như JPY và KRW, hãy sử dụng amount nguyên trạng.

Theo dõi các sự kiện thanh toán

Ghi lại một sự kiện Payment Completed khi thanh toán thành công:

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;
}

Theo dõi vòng đời subscription

Ghi lại các sự kiện Subscription Started và 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;
}

Xác định thuộc tính customer

Cập nhật traits của customer sau mỗi lần thanh toán thành công. Mỗi lệnh gọi Identify đặt traits thành các giá trị được gửi, vì vậy các traits này mô tả lần thanh toán mới nhất:

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;
}

Mẹo

Sử dụng tên sự kiện nhất quán trong toàn bộ tích hợp, chẳng hạn như định dạng object và action của Segment trong Payment Completed.
Bao gồm các properties cần thiết cho analytics và segmentation.
Đặt timestamp từ timestamp của sự kiện, để Segment ghi nhận thời điểm sự kiện xảy ra thay vì thời điểm sự kiện được nhận.
Sử dụng customer_id của Dodo Payments làm userId, để mọi lệnh gọi cho một customer được gắn với cùng một user Segment.

Khắc phục sự cố

Events Not Appearing in Segment

Kiểm tra Write Key thuộc về một source HTTP API và header Authorization sử dụng Basic authentication.
Segment trả về 200 cho hầu hết các request, bao gồm cả những request mà Segment không chấp nhận, vì vậy việc gửi thành công trong log Dodo Payments không chứng minh sự kiện đã đến nơi. Kiểm tra Debugger của source trong Segment.
Kiểm tra tên sự kiện có tuân theo quy ước đặt tên của Segment hay không.
Kiểm tra mọi lệnh gọi đều đặt userId. Segment từ chối lệnh gọi không có userId hoặc anonymousId.
Kiểm tra rate limit của Segment đối với HTTP API. Segment khuyến nghị duy trì dưới 1.000 request mỗi giây cho mỗi workspace.
Nếu workspace của bạn sử dụng region EU của Segment, hãy gửi các lệnh gọi đến https://events.eu1.segmentapis.com/v1/track và https://events.eu1.segmentapis.com/v1/identify thay thế.

Transformation Errors

Kiểm tra payload khớp với định dạng API của Segment.
Kiểm tra tất cả các field bắt buộc đều có mặt. Track yêu cầu event, còn cả Track và Identify đều yêu cầu userId hoặc anonymousId.
Kiểm tra tên sự kiện là các string, không phải object.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

Giới thiệu

Bắt đầu

Ví dụ về Transformation code

Theo dõi các sự kiện thanh toán

Theo dõi vòng đời subscription

Xác định thuộc tính customer

Mẹo

Khắc phục sự cố

​Giới thiệu

​Bắt đầu

​Ví dụ về Transformation code

​Theo dõi các sự kiện thanh toán

​Theo dõi vòng đời subscription

​Xác định thuộc tính customer

​Mẹo

​Khắc phục sự cố

Giới thiệu

Bắt đầu

Ví dụ về Transformation code

Theo dõi các sự kiện thanh toán

Theo dõi vòng đời subscription

Xác định thuộc tính customer

Mẹo

Khắc phục sự cố