はじめに
Dub は、短縮リンク、コンバージョントラッキング、アフィリエイトプログラム向けのリンクアトリビューションプラットフォームです。この統合により、顧客が Dodo Payments を通じて支払うたびに Dub がセールコンバージョンイベントを記録するため、マーケティングキャンペーンや紹介プログラムの投資効果を測定できます。 Dub は、顧客が次のいずれかを行ったときにセールを記録します。- 単発の支払いを完了する
- 有料プランをサブスクライブする
- 定期サブスクリプションの支払いを行う
この統合には、リンクでコンバージョントラッキングが有効になっている Dub アカウントが必要です。Dub のコンバージョントラッキングには Business プラン以上が必要です。
仕組み
訪問者が Dub の短縮リンクのいずれかをクリックすると、Dub はdub_id cookie に一意の click ID を保存します。セールをリンクにアトリビューションするには、次の手順を行います。
- チェックアウトを作成するときに、
dub_idcookie から Dub の click ID を取得します。 - 支払いの
metadataに click ID を保存し、システム内の顧客 ID(external ID)も併せて保存します。 - 支払いが成功したときに、Track API を通じて セールを Dub に送信します。
前提条件
この統合を設定する前に、次のものが必要です。- ワークスペースを持つ Dub アカウント。
- リンクで有効になっているコンバージョントラッキング。
- Dub のダッシュボードの Settings → API Keys で作成した Dub API key。
はじめに
1
Enable Conversion Tracking in Dub
Dub のダッシュボードで、セールを追跡するリンクのコンバージョントラッキングを有効にします。Dub はそれらのリンク経由でアクセスした顧客のセールイベントを記録します。
コンバージョントラッキングを有効にする方法については、Dub のドキュメントを参照してください。
2
Get Your Dub API Key
Dub のダッシュボードで Settings → API Keys に移動し、
conversions.write scope の API key を作成します。3
Capture Click ID in Checkout
チェックアウトを作成するときに cookie から Dub click ID を読み取り、支払いの
metadata に追加します。Step 1を参照してください。4
Send Sale Data via Webhook
支払いが成功したときに各セールを Dub の Track API に送信する webhook endpoint を作成します。Step 2を参照してください。
5
Done
セールコンバージョンイベントは Dub の analytics dashboard に表示され、リンクにアトリビューションされます。
実装ガイド
ステップ1: クリックIDと顧客IDをチェックアウトメタデータに追加する
チェックアウトを作成するときに cookie から Dub click ID を読み取り、顧客の external ID と併せて支払いのmetadata に含めます。
以下の例では、deprecated である
POST /payments を使用しています。既存の統合では引き続き動作しますが、新しい統合では、同じ方法で metadata を受け取る Checkout Sessions(POST /checkouts)を使用してください。Step 2: Dubに販売データを送信する
支払いが成功したときにセールデータを Dub の Track API に送信する webhook endpoint を作成します。1
Open the Webhook Section
Dodo Payments ダッシュボードで、Developer → Webhooks に移動し、Add endpoint をクリックします。

2
Select Dub
Integration で Dub.co を選択します。
3
Enter API Key
API key に Dub API key を貼り付けます。Dodo Payments はすべての delivery の 
Authorization header にこのキーを含めます。
4
Check the URL and Events
Endpoint URL が空の場合は、
https://api.dub.co/track/sale を入力します。Subscribed events で、payment.succeeded など、変換で処理する events を選択します。5
Configure Transformation
Transformation code で、payment data を Dub の Track Sale API 用にフォーマットするよう handler を編集します。examples を参考にしてください。
6
Test & Create
Test this code で Simulate をクリックし、sample payload に対して handler を実行します。次に Create endpoint をクリックします。
Transformation Code Examples
各 handler は、metadata に click ID がある場合にのみ Dub に sale を送信します。click ID がない organic traffic の場合は webhook.cancel = true を設定するため、Dub には request が送信されません。キャンセルされた delivery は webhook logs では引き続き successful と表示されます。
request body は Dub の Track Sale API に従います。customerExternalId と amount は必須で、Dub の payment processors の一覧に Dodo Payments の値がないため、paymentProcessor は custom です。Dub は amount を Dodo Payments の amount と同じ単位で受け取ります。つまり、小数点以下2桁の通貨では cents、JPY などの小数点以下のない通貨では整数全体です。examples では amount を変更せずに渡します。
Basic Sale Tracking
payment が成功したときに sale を追跡します:basic_sale.js
Track Subscription Sales
初回 subscription と recurring payment の両方を追跡します。subscription にはpayment.succeeded handlers ではなく、この handler を使用してください。両方を併用しないでください。各 subscription payment は payment.succeeded も発生させるため、両方の events を処理すると、すべての sale が2回記録されます。Subscription Integration Guide を参照してください。
この handler は subscription の metadata から click ID を読み取るため、subscription の作成時に同じ metadata を渡してください。renewal では、invoiceId が subscription ID と previous_billing_date(現在の billing period の開始時点)を組み合わせます。そのため、delivery が retry されても同じ invoiceId が再利用されます。
subscription_sale.js
Track Sales with Tax Exclusion
税引前の amount のみを Dub に送信し、Dub の revenue から tax を除外します:sale_without_tax.js
Track Sales with Custom Event Names
custom event names を使用して、さまざまな種類の sale を分類します。次の example は、payment のmetadata に設定した is_upgrade flag を読み取ります:
custom_events.js
Alternative: Client-Side Implementation
webhook transformation を介さずに独自の server から sale を追跡するには、payment 成功後に Dub の Track API を直接呼び出します。たとえば、payment.succeeded webhook handler から呼び出せます。code では Dub API key を使用するため、browser ではなく必ず server 上で実行してください。
Best Practices
- click ID を metadata に含める: click ID がないと、Dub は revenue を link に attribution できません。
- external IDs を一貫して使用する: 正確な customer-level analytics のため、毎回 system の同じ customer ID を
customerExternalIdとして渡します。 - organic traffic を処理する: click ID がない場合は
webhook.cancel = trueを設定し、不要な API calls を避けます。 - sample payments でテストする: Test this code で handler を実行し、live にする前に integration が動作することを確認します。
- Dub dashboard を監視する: 期待どおりの attribution で sales が表示されることを確認します。
Important Notes
- Amount format: Dub は、小数点以下2桁の通貨では cents(たとえば、$10.00 は
1000)、JPY などの小数点以下のない通貨では整数全体を想定します。 - Currency: USD、EUR、GBP などの ISO 4217 currency codes を使用します。Dub は各 sale を最新の exchange rate で USD に変換します。
- Free trials: Dub の Track Sale API は
0のamountを受け付けます。examples では $0 payments を除外しないため、各 $0 payment は sale として Dub に到達します。$0 payments を除外するには、total_amountが0の場合にwebhook.cancel = trueを設定します。 - Refunds: 正確な revenue reporting が必要な場合は、refunds を個別に追跡します。
Troubleshooting
Sales Not Appearing in Dub
Sales Not Appearing in Dub
- Dub API key が正しく、
conversions.writescope を持っていることを確認します。 dub_click_idが取得され、payment metadata に保存されていることを確認します。- webhook transformation が payload を正しくフォーマットしていることを確認します。
- endpoint が
payment.succeededを subscribe していることを確認します。 - Dub links で conversion tracking が有効になっていることを確認します。
- Developer → Webhooks の Logs tab で endpoint の delivery attempts を開き、Dub の response を確認します。click ID のない payment は canceled になり、successful と表示されます。
Revenue Attribution Not Working
Revenue Attribution Not Working
- checkout 前に customer が Dub short links をクリックしていることを確認します。
dub_idcookie が domain に設定されていることを確認します。- payment metadata の click ID が customer のクリックと一致していることを確認します。
- checkout を作成する前に click ID を取得します。
Transformation Errors
Transformation Errors
- payload が Dub の Track Sale API format と一致していることを確認します。
- 必須 fields である
customerExternalIdとamountが存在し、attribution 用にclickIdが設定されていることを確認します。 - amount が decimal ではなく、最小の currency unit の integer であることを確認します。
- endpoint URL が
https://api.dub.co/track/saleであることを確認します。 - sample webhook payloads で transformation をテストします。
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
payment.succeededevents の場合のみ sales を追跡し、payment.processingでは追跡しません。- 各 sale に一意の
invoiceIdを使用します。Dub は各invoiceIdにつき1件の sale のみを記録します。 - renewal では、Track Subscription Sales のように、subscription ID と billing period から
invoiceIdを作成します。現在時刻のように delivery ごとに変化する値を使うと、delivery の retry 時に重複した sale が記録されます。
Additional Resources
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 にお問い合わせください。