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とともに支払いメタデータに含めます。

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
}

ステップ2: 販売データをDubに送信する

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

Open the Webhook Section

Dodo PaymentsダッシュボードでWebhooks → + Add Endpointに移動し、integrationsのドロップダウンを展開します。

Select Dub

Dub統合カードを選択します。

Enter API Key

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

Configure Transformation

変換コードを編集して、DubのTrack Sale API用に支払いデータを整形します。

Test & Create

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

変換コードの例

基本的な販売追跡

支払い成功時に販売を追跡します。

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

代替方法: クライアント側での実装

webhookを使用せず、サーバーから販売を追跡したい場合は、支払い成功後に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,
    });
  }
}

ベストプラクティス

クリックIDを早期に取得する: 正確なアトリビューションを確保するため、ユーザーが離脱して後から戻ってきた場合でも、チェックアウトフローのできるだけ早い段階でDubのクリックIDを保存します。

メタデータには必ずクリックIDを含める: クリックIDがないと、Dubは収益をリンクに紐付けられません
外部IDを一貫して使用する: 顧客単位で正確に分析できるよう、システムで使用しているものと同じ顧客IDを渡します
オーガニックトラフィックを適切に処理する: クリックIDがない場合はwebhook.cancel = trueを設定し、不要なAPI呼び出しを避けます
サンプル支払いでテストする: 本番稼働前に統合が正しく動作することを確認します
Dubダッシュボードを監視する: 適切なアトリビューションで販売が正しく表示されていることを確認します

重要な注意事項

金額形式: Dubは金額をセント単位で受け取ります（例: $10.00 = 1000）
通貨: ISO 4217通貨コード（USD、EUR、GBPなど）を使用します
無料トライアル: $0の支払いは販売として追跡されません
返金: 正確な収益レポートが必要な場合は、返金を別途追跡することを検討してください

トラブルシューティング

Sales not appearing in Dub

Dub APIキーが正しく、conversions.writeスコープを持っていることを確認します
dub_click_idが取得され、支払いメタデータに保存されていることを確認します
webhookの変換でpayloadが正しく整形されていることを確認します
webhookがpayment.succeededイベントでトリガーされていることを確認します
Dubリンクでコンバージョン追跡が有効になっていることを確認します

Revenue attribution not working

チェックアウト前にユーザーがDubの短縮リンクをクリックしていることを確認します
ドメインでdub_id cookieが正しく設定されていることを確認します
チェックアウト作成時と支払い完了時でクリックIDが一致していることを確認します
チェックアウトセッションを作成する前にクリックIDを取得していることを確認します

Transformation errors

JSON構造がDubのTrack Sale API形式と一致することを確認します
必須フィールド（clickId、externalId、amount）がすべて存在することを確認します
金額がセント単位（小数ではなく整数）であることを確認します
API endpoint URLが正しいことを確認します: https://api.dub.co/track/sale
サンプルwebhook payloadで変換をテストします

Duplicate sales being tracked

payment.succeededイベントでのみ追跡し、payment.processingでは追跡しないようにします
各販売には一意のinvoiceId値を使用します
サブスクリプションでは、更新時の重複を防ぐためにタイムスタンプまたは請求期間を追加します

追加リソース

Dub Conversions Documentation

Dubのコンバージョン追跡および分析機能について詳しく学びます。

Dub Track Sale API

DubのTrack Sale endpointの完全なAPIリファレンスを確認します。

Dub Dashboard

Dubダッシュボードにアクセスして、コンバージョン分析とアトリビューションデータを確認します。

Webhook Events Guide

利用可能なすべてのDodo Payments webhookイベントについて学びます。

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

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

はじめに

仕組み

前提条件

はじめに

実装ガイド

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

ステップ2: 販売データをDubに送信する

変換コードの例

基本的な販売追跡

サブスクリプション販売の追跡

税額を除外した販売の追跡

カスタムイベント名を使用した販売の追跡

代替方法: クライアント側での実装

ベストプラクティス

重要な注意事項

トラブルシューティング

追加リソース

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​はじめに

​仕組み

​前提条件

​はじめに

​実装ガイド

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

​ステップ2: 販売データをDubに送信する

​変換コードの例

​基本的な販売追跡

​サブスクリプション販売の追跡

​税額を除外した販売の追跡

​カスタムイベント名を使用した販売の追跡

​代替方法: クライアント側での実装

​ベストプラクティス

​重要な注意事項

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

​追加リソース

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

はじめに

仕組み

前提条件

はじめに

実装ガイド

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

ステップ2: 販売データをDubに送信する

変換コードの例

基本的な販売追跡

サブスクリプション販売の追跡

税額を除外した販売の追跡

カスタムイベント名を使用した販売の追跡

代替方法: クライアント側での実装

ベストプラクティス

重要な注意事項

トラブルシューティング

追加リソース