セグメント

はじめに

Segment integration は、Dodo Payments のイベントを Track および Identify calls として Segment の HTTP Tracking API に送信します。Segment はその後、ワークスペースに接続された 300 以上の送信先から、分析、マーケティング、データウェアハウスのツールに決済、サブスクリプション、顧客データを転送します。

この integration には、Segment ワークスペースの HTTP API source の Write Key が必要です。また、Dodo Payments dashboard の Developer → Webhooks にアクセスできる必要があります。

始め方

Open the Webhook Section

Dodo Payments ダッシュボードで、Developer → Webhooks に移動し、Add endpoint をクリックします。

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

Select Segment

Integration で Segment を選択します。dashboard に Endpoint URL と Segment 用の transformation code が入力されます。

Enter Write Key

Segment で Connections → Sources に移動し、HTTP API source を開くか作成します。source の設定から Write Key をコピーし、API key に貼り付けます。

Select Events

Subscribed events で、transformation が処理するイベントだけを選択します。このページの例では payment.succeeded、subscription.active、subscription.cancelled を使用します。

Configure Transformation

Transformation code で handler を編集し、Segment の Track または Identify API 用にイベントをフォーマットします。例から始めてください。

Test & Create

Test this code でイベントタイプを選択し、Simulate をクリックして Segment への call をプレビューします。次に Create endpoint をクリックします。

Switch to Basic Authentication

Dodo Payments は API key の値を bearer token として送信しますが、Segment の HTTP API は Basic authentication を通じた Write Key、または body 内の writeKey field を受け付けます。endpoint を作成した直後に、その Advanced tab を開きます。Custom headers で、非表示の Authorization row に新しい値を入力します。値は Basic、スペース、そして末尾にコロンを付けた Write Key の Base64 encoding です。次に Save をクリックします。たとえば、echo -n 'YOUR_WRITE_KEY:' | base64 は encoded value を出力します。

Done

Subscribed events が Segment に届き、接続された送信先に転送されるようになります。

Transformation Code の例

各 handler は webhook.url を Segment API endpoint に設定し、webhook.payload を call に置き換えます。Dodo Payments の金額は通貨の最小単位で表されるため、例では 100 で割っています。JPY や KRW などの小数点以下の桁数がない通貨では、金額をそのまま使用してください。

Track Payment Events

決済が成功したときに Payment Completed event を記録します。

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

Track Subscription Lifecycle

Subscription Started event と Subscription Cancelled event を記録します。

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

Identify Customer Properties

決済が成功するたびに、顧客の traits を更新します。各 Identify call は送信した値で traits を設定するため、これらの traits は最新の決済を表します。

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

ヒント

integration 全体で一貫した event names を使用します。たとえば、Payment Completed にある Segment の object と action の形式です。
分析と segmentation に必要な properties を含めます。
event の timestamp から timestamp を設定し、到着時刻ではなくイベント発生時刻を Segment に記録させます。
Dodo Payments の customer_id を userId として使用し、顧客に対するすべての call が同じ Segment user に紐付くようにします。

トラブルシューティング

Events Not Appearing in Segment

Write Key が HTTP API source に属していること、および Authorization header が Basic authentication を使用していることを確認します。
Segment は、受け付けなかったリクエストを含むほとんどのリクエストに対して 200 を返すため、Dodo Payments logs で delivery が成功していても、event が届いたことの証明にはなりません。Segment の source にある Debugger を確認してください。
event names が Segment の命名規則に従っていることを確認します。
すべての call が userId を設定していることを確認します。userId も anonymousId もない call は Segment に拒否されます。
HTTP API の Segment の rate limits を確認します。Segment は、ワークスペースあたり毎秒 1,000 requests 未満に抑えることを推奨しています。
ワークスペースが Segment の EU region を使用している場合は、代わりに https://events.eu1.segmentapis.com/v1/track と https://events.eu1.segmentapis.com/v1/identify に call を送信します。

Transformation Errors

payload が Segment の API format と一致していることを確認します。
必須 fields がすべて存在することを確認します。Track には event が必要で、Track と Identify の両方には userId または anonymousId が必要です。
event names が objects ではなく strings であることを確認します。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

はじめに

始め方

Transformation Code の例

Track Payment Events

Track Subscription Lifecycle

Identify Customer Properties

ヒント

トラブルシューティング

​はじめに

​始め方

​Transformation Code の例

​Track Payment Events

​Track Subscription Lifecycle

​Identify Customer Properties

​ヒント

​トラブルシューティング

はじめに

始め方

Transformation Code の例

Track Payment Events

Track Subscription Lifecycle

Identify Customer Properties

ヒント

トラブルシューティング