DataFast

介绍

DataFast 是一款以收入为核心的分析工具，可显示哪些营销渠道带来了付费客户。当你将 Dodo Payments 交易发送到 DataFast 时，它会将收入归因到每位客户最初的流量来源，因此你可以了解哪些渠道和客户细分带来了最多收入。

此集成需要 DataFast API key，你可以在 DataFast 控制台中创建。

工作原理

DataFast 使用存储在 datafast_visitor_id cookie 中的 ID 来识别每位访问者。要将收入归因到营销渠道：

从 datafast_visitor_id cookie 中获取 DataFast 访问者 ID：创建 checkout 时读取该 cookie。
存储访问者 ID：将其存储在支付的 metadata 中。
将支付发送到 DataFast：支付成功后，通过其 Payment API 发送。

DataFast 会将每笔成功支付匹配到访问者最初的流量来源，并将收入归因到该渠道。

开始使用

Install DataFast Script

在你的网站上安装 DataFast 跟踪脚本。该脚本会设置 datafast_visitor_id cookie，用于识别每位访问者。有关适用于你平台的安装说明，请参阅 DataFast 文档。

Get Your API Key

在 DataFast 控制台中打开你网站的设置，转到 API，然后点击 Create API Key。

请妥善保管你的 API key。切勿在客户端代码中公开它。

Capture Visitor ID in Checkout

创建 checkout 时，从 cookie 中读取 DataFast 访问者 ID，并将其添加到支付的 metadata 中。请参阅步骤 1。

Send Payment Data via Webhook

创建一个 webhook endpoint，将每笔成功支付发送到 DataFast 的 Payment API。请参阅步骤 2。

Done

收入会显示在你的 DataFast 控制台中，并归因到为每位客户带来访问的营销渠道。

实施指南

步骤 1：将访问者 ID 添加到 Checkout Metadata

创建 checkout 时，从 cookie 中读取 DataFast 访问者 ID，并将其包含在支付的 metadata 中。

以下示例使用 POST /payments，该项已弃用。它仍适用于现有集成，但新集成应使用 Checkout Sessions（POST /checkouts），它们以相同方式接受 metadata。

import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie (cookies() is async in Next.js 15 and later)
  const datafastVisitorId = (await cookies()).get('datafast_visitor_id')?.value;

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId ?? '', // Store visitor ID in metadata
    },
  });

  return payment;
}

const express = require('express');
const router = express.Router();

// dodopayments is your initialized Dodo Payments client
router.post('/create-checkout', async (req, res) => {
  // Capture DataFast visitor ID from cookie (req.cookies requires the cookie-parser middleware)
  const datafastVisitorId = req.cookies?.datafast_visitor_id;

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

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

// Capture DataFast visitor ID from cookie
const datafastVisitorId = getCookie('datafast_visitor_id'); // Use your framework's cookie method

// dodopayments is your initialized Dodo Payments client, and productId is the product to sell
const payment = await dodopayments.payments.create({
  product_cart: [{ product_id: productId, quantity: 1 }],
  // ... other payment configuration
  metadata: {
    datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
  },
});

步骤 2：将支付数据发送到 DataFast

创建一个 webhook endpoint，将成功支付发送到 DataFast 的 Payment API。

Open the Webhook Section

在 Dodo Payments 控制面板中，转到 Developer → Webhooks，然后点击 Add endpoint。

Add endpoint 对话框，其中在 Integration 下拉菜单中选择了 DataFast

Select DataFast

在 Integration 中选择 DataFast。

Enter API Key

在 API key 中粘贴您的 DataFast API key。Dodo Payments 会在每次传送的 Authorization header 中发送该密钥。

Check the URL and Events

如果 Endpoint URL 为空，请输入 https://datafa.st/api/v1/payments。在 Subscribed events 中，选择 payment.succeeded。

Configure Transformation

在 Transformation code 下，编辑 handler 以便为 DataFast’s Payment API 格式化 payment data。请从示例开始。

Test & Create

在 Test this code 下，点击 Simulate，使用示例 payload 运行 handler。然后点击 Create endpoint。

Transformation Code Examples

每个 handler 都在 payment.succeeded 上运行。当 payment 的 metadata 没有 visitor ID 时，它会设置 webhook.cancel = true，因此不会向 DataFast 发送请求。已取消的传送仍会在 webhook 日志中显示为成功。 DataFast’s Payment API 接受以主要货币单位表示的 amount，例如 29.99。Dodo Payments 以最小货币单位发送 total_amount，例如 USD 的 cents，因此示例会进行转换。

Basic Payment Attribution

basic_payment.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Only send to DataFast if visitor ID exists in metadata
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100, // Convert from cents to dollars
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Handle Zero Decimal Currencies

零小数货币（例如 JPY）没有次级货币单位，因此 total_amount 已经是主要货币单位。三位小数货币（例如 KWD）每个主要货币单位包含 1,000 个次级货币单位。本示例会针对每种情况转换金额，并使用 Dodo Payments 视为零小数和三位小数的货币：

zero_decimal.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      // Zero-decimal currencies: the smallest unit is the major unit
      const zeroDecimalCurrencies = ['BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF'];
      // Three-decimal currencies: 1 major unit = 1000 minor units
      const threeDecimalCurrencies = ['BHD', 'IQD', 'JOD', 'KWD', 'LYD', 'OMR', 'TND'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      const isThreeDecimal = threeDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / (isThreeDecimal ? 1000 : 100), // Convert from minor units
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Subscription Payments

订阅付款也会触发 payment.succeeded，并设置 subscription_id。此 handler 会将每笔订阅付款发送到 DataFast，并在续订时设置 renewal: true，使 DataFast 能够区分续订付款和首次付款。续订付款以 off-session 方式收取，因此其 payload 会设置 subscription_id，并将 checkout_session_id 设置为 null。通过 Checkout Session 创建的订阅，其首次付款会设置 checkout_session_id。续订付款会携带订阅的 metadata，因此请将 datafast_visitor_id 保存在订阅的 metadata 中，以便归因续订付款。

subscription_payment.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // A renewal belongs to a subscription and isn't paid through a checkout session
    const isRenewal = Boolean(payment.subscription_id) && !payment.checkout_session_id;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100,
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
        renewal: isRenewal,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

最佳实践

尽早捕获 visitor ID：尽可能早地在 checkout 流程中存储 DataFast visitor ID，这样即使客户离开后再次返回，归因仍能保持准确。

在 metadata 中包含 visitor ID：没有 visitor ID，DataFast 就无法将收入归因到营销渠道。
处理零小数货币：某些货币（例如 JPY 和 KRW）没有小数位。请调整这些货币以及三位小数货币（例如 KWD）的金额转换方式。
使用示例付款进行测试：使用 Test this code 运行 handler，并在正式上线前确认集成正常运行。
监控您的 DataFast 控制面板：确认付款显示了预期的归因信息。
依靠 webhook 重试：DataFast 会跳过其 transaction_id 已记录的付款，因此重试的传送不会创建重复记录。

故障排除

Payments Not Appearing in DataFast

确认您的 DataFast API key 正确且处于活动状态。
检查是否已捕获并将 datafast_visitor_id 存储在 payment metadata 中。
检查 webhook transformation 是否正确格式化 payload。
确认 endpoint 已订阅 payment.succeeded。
检查 DataFast 控制面板中的错误消息或 API 日志。
在 Developer → Webhooks 的 Logs 标签页中打开 endpoint 的传送尝试，以查看 DataFast 的响应。没有 visitor ID 的付款会被取消，但显示为成功。

Revenue Attribution Not Working

确认 DataFast tracking script 已安装并在您的网站上运行。
确认已设置 datafast_visitor_id cookie。
检查 payment metadata 中的 visitor ID 是否与 DataFast 为该访问记录的 visitor ID 匹配。
在创建 checkout 之前捕获 visitor ID。
如需更多指导，请参阅 DataFast 的 Payment API 文档。

Transformation Errors

检查 payload 是否符合 DataFast’s Payment API 格式。
检查所有必填字段是否存在：amount、currency 和 transaction_id。为进行归因，请包含 datafast_visitor_id。
检查金额转换：大多数货币除以 100，三位小数货币除以 1,000，零小数货币无需除法转换。
确认 endpoint URL 为 https://datafa.st/api/v1/payments。
使用示例 webhook payload 测试 transformation。

Currency Conversion Issues

对于零小数货币（BIF、CLP、DJF、GNF、JPY、KMF、KRW、MGA、PYG、RWF、UGX、VND、VUV、XAF、XOF 和 XPF），按原值发送金额。
对于三位小数货币（BHD、IQD、JOD、KWD、LYD、OMR 和 TND），将金额除以 1,000。
对于其他所有货币，将金额除以 100，以便从最小单位转换为主要单位。
检查货币代码是否使用 ISO 4217 格式，例如 USD、EUR 或 JPY。

其他资源

DataFast Documentation

了解 DataFast 的 Payment API 和收入归因。

DataFast Dashboard

在您的 DataFast 控制面板中查看收入分析和归因数据。

如需此集成的帮助，请通过 support@dodopayments.com 联系 Dodo Payments 支持团队。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

介绍

工作原理

开始使用

实施指南

步骤 1：将访问者 ID 添加到 Checkout Metadata

步骤 2：将支付数据发送到 DataFast

Transformation Code Examples

Basic Payment Attribution

Handle Zero Decimal Currencies

Subscription Payments

最佳实践

故障排除

其他资源

DataFast Documentation

DataFast Dashboard

​介绍

​工作原理

​开始使用

​实施指南

​步骤 1：将访问者 ID 添加到 Checkout Metadata

​步骤 2：将支付数据发送到 DataFast

​Transformation Code Examples

​Basic Payment Attribution

​Handle Zero Decimal Currencies

​Subscription Payments

​最佳实践

​故障排除

​其他资源

DataFast Documentation

DataFast Dashboard

介绍

工作原理

开始使用

实施指南

步骤 1：将访问者 ID 添加到 Checkout Metadata

步骤 2：将支付数据发送到 DataFast

Transformation Code Examples

Basic Payment Attribution

Handle Zero Decimal Currencies

Subscription Payments

最佳实践

故障排除

其他资源