Dub

はじめに

Dubは、短縮リンクの作成、共有、追跡を支援する強力なリンク管理プラットフォームです。Dodo PaymentsとDubを統合すると、顧客が購入を完了した際に販売コンバージョンイベントを自動的に追跡でき、マーケティングキャンペーンや紹介プログラムのROIを測定できます。 Dubでは、顧客が次のいずれかを行ったときに「販売」イベントが記録されます。

一回限りの支払いを完了する
有料プランに登録する
定期サブスクリプションの支払いを行う

この統合には、リンクでコンバージョン追跡が有効になっているDubアカウントが必要です。

アフィリエイトプログラム統合: この統合は、アフィリエイトの紹介とコミッションの追跡にDub Partnersともシームレスに連携します。Dubのコンバージョン追跡を使用して、販売をアフィリエイトリンクに紐付け、パートナーのパフォーマンスを測定できます。アフィリエイトプログラムの設定については、Affiliates機能ガイドをご覧ください。

仕組み

Dubは、ユーザーがDubの短縮リンクをクリックした際にcookieに保存される一意のクリックID（dub_id）を通じて訪問者を追跡します。販売をリンクに紐付けるには、次の操作が必要です。

チェックアウトセッションの作成時に、cookieからDubのクリックIDを取得する
顧客の外部IDとともに、クリックIDを支払いメタデータに保存する
Track APIを使用して、支払い成功時に販売データをDubへ送信する

これにより、Dubは成功した販売と元のリンククリックを照合でき、完全なコンバージョンアトリビューションを実現できます。

前提条件

この統合を設定する前に、次のものを準備してください。

ワークスペースを含むDubアカウント
リンクのコンバージョン追跡
Dub APIキー（DubダッシュボードのSettings → API Keysから取得可能）

はじめに

Enable Conversion Tracking in Dub

Dubダッシュボードで、販売を追跡するリンクのコンバージョン追跡を有効にします。これにより、顧客が購入を完了した際にDubが販売イベントを記録できるようになります。

コンバージョン追跡の有効化については、Dubドキュメントをご覧ください。

Get Your Dub API Key

DubダッシュボードでSettings → API Keysに移動し、conversions.writeスコープを持つ新しいAPIキーを作成します。

APIキーは安全に管理し、クライアント側のコードには決して公開しないでください。

Capture Click ID in Checkout

チェックアウトセッションの作成時にcookieからDubのクリックIDを取得し、支払いメタデータに追加します。

Send Sale Data via Webhook

支払い成功時に販売データをDubのTrack APIへ送信するwebhookを設定します。

Done!

これで、販売コンバージョンイベントがDubの分析ダッシュボードに表示され、リンクへの完全なアトリビューションが確認できるようになります。

実装ガイド

ステップ1: クリックIDと顧客IDをチェックアウトメタデータに追加する

チェックアウトセッションの作成時にcookieからDubのクリックIDを取得し、顧客の外部IDとともに支払いメタデータに含めます。

以下の例では POST /payments を使用していますが、これは 非推奨 です。既存のintegrationsでは引き続き動作しますが、新しいintegrationsでは Checkout Sessions（POST /checkouts）を使用してください。— metadata は同じ方法で渡されます。

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_cart: [{ product_id: productId, quantity: 1 }],
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

const express = require('express');
const DodoPayments = require('dodopayments').default;
const router = express.Router();

const client = new DodoPayments();

router.post('/create-checkout', async (req, res) => {
  // Capture Dub click ID from cookie
  const dubClickId = req.cookies?.dub_id;

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

  res.json({ payment });
});

from fastapi import FastAPI, Request
from dodopayments import DodoPayments

app = FastAPI()
client = DodoPayments()

@app.post("/create-checkout")
async def create_checkout(request: Request):
    # Capture Dub click ID from cookie
    dub_click_id = request.cookies.get("dub_id")

    body = await request.json()

    payment = client.payments.create(
        billing={
            "city": "New York",
            "country": "US",
            "state": "NY",
            "street": "123 Main St",
            "zipcode": "10001",
        },
        customer={
            "email": body["email"],
            "name": body["name"],
        },
        product_cart=[{"product_id": body["product_id"], "quantity": 1}],
        metadata={
            "dub_click_id": dub_click_id,          # Store Dub click ID
            "dub_external_id": body["customer_id"], # Store your customer's unique ID
        },
    )

    return {"payment": payment}

package main

import (
    "context"

    "github.com/dodopayments/dodopayments-go"
)

func createCheckout(dubClickId, customerId, productId string) (*dodopayments.PaymentNewResponse, error) {
    client := dodopayments.NewClient()

    payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
        Billing: dodopayments.F(dodopayments.BillingAddressParam{
            City:    dodopayments.F("New York"),
            Country: dodopayments.F(dodopayments.CountryCodeUs),
            State:   dodopayments.F("NY"),
            Street:  dodopayments.F("123 Main St"),
            Zipcode: dodopayments.F("10001"),
        }),
        Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
            dodopayments.NewCustomerParam{
                Email: dodopayments.F("customer@example.com"),
                Name:  dodopayments.F("John Doe"),
            },
        ),
        ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
            ProductID: dodopayments.F(productId),
            Quantity:  dodopayments.F(int64(1)),
        }}),
        Metadata: dodopayments.F(map[string]string{
            "dub_click_id":    dubClickId, // Store Dub click ID
            "dub_external_id": customerId, // Store your customer's unique ID
        }),
    })

    return payment, err
}

Step 2: Dubに販売データを送信する

支払いが成功したときに販売データをDubのTrack APIへ送信するよう、webhook endpointを設定します。

Open the Webhook Section

Dodo Payments dashboardで Webhooks → + Add Endpoint に移動し、integrations dropdownを展開します。

Select Dub

Dub integration cardを選択します。

Enter API Key

設定フィールドにDub API Keyを入力します。

Configure Transformation

支払いデータをDubのTrack Sale API用にフォーマットするよう、transformation codeを編集します。

Test & Create

サンプルpayloadでテストし、Create をクリックしてintegrationを有効化します。

Transformation Codeの例

基本的な販売トラッキング

支払いが成功したときに販売をトラッキングします。

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

サブスクリプション販売のトラッキング

初回のサブスクリプションと継続的な支払いの両方をトラッキングします。

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

税抜き販売のトラッキング

正確な収益トラッキングのため、税抜き金額のみをDubに送信します。

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

カスタムイベント名を使用した販売のトラッキング

カスタムイベント名を使用して、さまざまな種類の販売を分類します。

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

代替方法: Client-Side Implementation

webhookを使用せず、serverから販売をトラッキングしたい場合は、支払い成功後にDubのTrack APIを直接呼び出せます。

'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,
  });
}

const { Dub } = require('dub');

const dub = new Dub();

async function trackSale(payment) {
  if (payment.metadata?.dub_click_id) {
    await dub.track.sale({
      clickId: payment.metadata.dub_click_id,
      externalId: payment.metadata.dub_external_id,
      amount: payment.total_amount,
      currency: payment.currency,
      paymentProcessor: 'dodo',
      invoiceId: payment.payment_id,
    });
  }
}

ベストプラクティス

click IDを早い段階で取得する: 正確なアトリビューションを確保するため、checkout flowではできるだけ早くDub click IDを保存してください。これにより、ユーザーがページを離れて後から戻ってきた場合でも正しく計測できます。

metadataには必ずclick IDを含める: click IDがない場合、Dubはリンクに収益を紐付けられません
external IDを一貫して使用する: customer-level analyticsを正確に行うため、システムで使用しているものと同じcustomer IDを渡します
organic trafficを適切に処理する: click IDがない場合は webhook.cancel = true を設定し、不要なAPI callsを避けます
サンプル支払いでテストする: production環境で利用開始する前に、integrationが正しく動作することを確認します
Dub dashboardを監視する: 適切なアトリビューションで販売が正しく表示されていることを確認します

重要な注意事項

Amount format: Dubでは金額をcents単位で指定します（例: $10.00 = 1000）
Currency: ISO 4217 currency codes（USD、EUR、GBPなど）を使用します
Free trials: $0の支払いは販売としてトラッキングされません
Refunds: 正確な収益レポートが必要な場合は、refundsを別途トラッキングすることを検討してください

トラブルシューティング

Sales not appearing in Dub

Dub API keyが正しく、conversions.write scopeを持っていることを確認します
dub_click_id が取得され、payment metadataに保存されていることを確認します
webhook transformationがpayloadを正しくフォーマットしていることを確認します
webhookが payment.succeeded eventsでtriggerされていることを確認します
Dub linksでconversion trackingが有効になっていることを確認します

Revenue attribution not working

checkout前にユーザーがDub short linksをクリックしていることを確認します
dub_id cookieがdomainに正しく設定されていることを確認します
checkout creationとpayment completionの間でclick IDsが一致していることを確認します
checkout sessionを作成する前にclick IDを取得していることを確認します

Transformation errors

JSON structureがDubのTrack Sale API formatと一致していることを確認します
必須フィールド（clickId、externalId、amount）がすべて存在することを確認します
amountがcents単位（decimalではなくinteger）であることを確認します
API endpoint URLが正しいことを確認します: https://api.dub.co/track/sale
サンプルwebhook payloadでtransformationをテストします

Duplicate sales being tracked

payment.succeeded eventsでのみトラッキングし、payment.processing ではトラッキングしないようにします
販売ごとに一意の invoiceId valuesを使用します
subscriptionsの場合は、renewalsでの重複を防ぐため、timestampsまたはbilling periodを追加します

追加リソース

Dub Conversions Documentation

Dubのconversion trackingとanalytics featuresについて詳しく説明します。

Dub Track Sale API

DubのTrack Sale endpointの完全なAPI referenceを確認します。

Dub Dashboard

Dub dashboardにアクセスして、conversion analyticsとattribution dataを確認します。

Webhook Events Guide

利用可能なすべてのDodo Payments webhook eventsについて説明します。

サポートが必要ですか？integrationについてサポートが必要な場合は、support@dodopayments.com までDodo Payments supportにお問い合わせください。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

はじめに

仕組み

前提条件

はじめに

実装ガイド

ステップ1: クリックIDと顧客IDをチェックアウトメタデータに追加する

Step 2: Dubに販売データを送信する

Transformation Codeの例

基本的な販売トラッキング

サブスクリプション販売のトラッキング

税抜き販売のトラッキング

カスタムイベント名を使用した販売のトラッキング

代替方法: Client-Side Implementation

ベストプラクティス

重要な注意事項

トラブルシューティング

追加リソース

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​はじめに

​仕組み

​前提条件

​はじめに

​実装ガイド

​ステップ1: クリックIDと顧客IDをチェックアウトメタデータに追加する

​Step 2: Dubに販売データを送信する

​Transformation Codeの例

​基本的な販売トラッキング

​サブスクリプション販売のトラッキング

​税抜き販売のトラッキング

​カスタムイベント名を使用した販売のトラッキング

​代替方法: Client-Side Implementation

​ベストプラクティス

​重要な注意事項

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

​追加リソース

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

はじめに

仕組み

前提条件

はじめに

実装ガイド

ステップ1: クリックIDと顧客IDをチェックアウトメタデータに追加する

Step 2: Dubに販売データを送信する

Transformation Codeの例

基本的な販売トラッキング

サブスクリプション販売のトラッキング

税抜き販売のトラッキング

カスタムイベント名を使用した販売のトラッキング

代替方法: Client-Side Implementation

ベストプラクティス

重要な注意事項

トラブルシューティング

追加リソース