跳转到主要内容

​
介绍

DataFast 是一款以收入为导向的分析工具，帮助您发现哪些营销渠道驱动付费客户。通过将 Dodo Payments 与 DataFast 集成，您可以将收入归因于您的流量来源，识别高价值客户群体，并做出数据驱动的决策以推动业务增长。
此集成需要您的 DataFast API 密钥，您可以从您的 DataFast 仪表板 获取。

​
工作原理

DataFast 通过存储在 cookie 中的唯一访客 ID 跟踪访问者。要将收入归因于营销渠道，您需要：
  1. 在创建结账会话时 从 datafast_visitor_id cookie 中 捕获 DataFast 的访客 ID
  2. 将访客 ID 存储 在您的支付元数据中
  3. 在支付成功时使用其支付 API 将支付数据发送到 DataFast
这使 DataFast 能够将成功的支付与原始流量来源匹配，从而为您提供完整的收入归因。

​
开始使用

1

安装 DataFast 脚本

首先，在您的网站上安装 DataFast 跟踪脚本。这将创建 datafast_visitor_id cookie 来跟踪您的访问者。请访问 DataFast 文档 获取特定于您平台的安装说明。
2

获取您的 API 密钥

登录到您的 DataFast 仪表板 并导航到您的网站设置以获取您的 API 密钥。
请妥善保管您的 API 密钥，切勿在客户端代码中暴露。
3

在结账中捕获访客 ID

在创建结账会话时，从 cookie 中捕获 DataFast 访客 ID 并将其添加到您的支付元数据中。
4

通过 Webhook 发送支付数据

配置一个 webhook，在支付成功时将支付数据发送到 DataFast 的支付 API。
5

完成！

🎉 收入数据现在将在您的 DataFast 仪表板中显示，并完整归因于营销渠道。

​
实施指南

​
第 1 步：将访客 ID 添加到结账元数据

在创建结账会话时，从 cookie 中捕获 DataFast 访客 ID 并将其包含在您的支付元数据中。 
import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = cookies().get('datafast_visitor_id')?.value;

  const payment = await dodopayments.payments.create({
    product_id: productId,
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  return payment;
}

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

配置一个 webhook 端点，在支付成功时将支付数据发送到 DataFast 的支付 API。
1

打开 Webhook 部分

在您的 Dodo Payments 仪表板中，导航到 Webhooks → + 添加端点 并展开集成下拉菜单。
添加端点和集成下拉菜单
2

选择 DataFast

选择 DataFast 集成卡片。
3

输入 API 密钥

在配置字段中提供您的 DataFast API 密钥。
添加 API 密钥
4

配置转换

编辑转换代码以格式化支付数据以适应 DataFast 的支付 API。
5

测试并创建

使用示例有效负载进行测试，然后单击 创建 以激活集成。

​
转换代码示例

​
基本支付归因

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?.datafast_visitor_id) {
      webhook.url = "https://datafa.st/api/v1/payments";
      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 {
      // Skip if no visitor ID (prevents unnecessary API calls)
      return null;
    }
  }
  return webhook;
}

​
处理零小数货币

某些货币（如 JPY）不使用小数位。相应地调整金额计算：
zero_decimal.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (payment.metadata?.datafast_visitor_id) {
      // Zero decimal currencies: JPY, KRW, CLP, etc.
      const zeroDecimalCurrencies = ['JPY', 'KRW', 'CLP', 'VND', 'UGX', 'MGA'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      
      webhook.url = "https://datafa.st/api/v1/payments";
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / 100, // Convert from cents for other currencies
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      return null;
    }
  }
  return webhook;
}

​
订阅支付

对于定期订阅支付，您可以跟踪每笔支付：
subscription_payment.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Check if this is a subscription payment
    const isSubscription = payment.subscription_id !== null;
    
    if (payment.metadata?.datafast_visitor_id) {
      webhook.url = "https://datafa.st/api/v1/payments";
      webhook.payload = {
        amount: payment.total_amount / 100,
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
        // Optional: Add subscription context
        ...(isSubscription && {
          subscription_id: payment.subscription_id,
        }),
      };
    } else {
      return null;
    }
  }
  return webhook;
}

​
最佳实践

尽早捕获访客 ID：在结账流程中尽早存储 DataFast 访客 ID，以确保准确归因，即使用户离开后再返回。
  • 始终在元数据中包含访客 ID：没有访客 ID，DataFast 无法将收入归因于营销渠道
  • 处理零小数货币：某些货币（JPY、KRW 等）不使用小数位——相应地调整您的金额计算
  • 使用示例支付进行测试：在上线之前验证集成是否正常工作
  • 监控您的 DataFast 仪表板：检查支付是否正确显示并具有适当的归因
  • 使用 webhook 重试：DataFast 的支付 API 是幂等的，因此如果 webhook 失败，重试是安全的

​
故障排除

  • 验证您的 DataFast API 密钥是否正确且有效
  • 检查 datafast_visitor_id 是否被捕获并存储在支付元数据中
  • 确保 webhook 转换正确格式化有效负载
  • 验证 webhook 是否在 payment.succeeded 事件上触发
  • 检查 DataFast 仪表板是否有任何错误消息或 API 日志
  • 确认 DataFast 跟踪脚本已安装并在您的网站上正常工作
  • 验证 datafast_visitor_id cookie 是否正确设置
  • 检查结账创建和支付完成之间的访客 ID 是否匹配
  • 确保在创建结账会话之前捕获访客 ID
  • 查看 DataFast 的 支付 API 文档 以获取更多指导
  • 验证 JSON 结构是否与 DataFast 的支付 API 格式匹配
  • 检查所有必需字段（amount, currency, transaction_id, datafast_visitor_id）是否存在
  • 确保金额正确转换（对于大多数货币除以 100，零小数货币除外）
  • 验证 API 端点 URL 是否正确： https://datafa.st/api/v1/payments
  • 使用示例 webhook 有效负载测试转换
  • 对于零小数货币（JPY、KRW、CLP、VND、UGX、MGA），直接发送金额而不除以 100
  • 对于所有其他货币，将金额除以 100 以从分转换为基本单位
  • 仔细检查货币代码是否符合 ISO 4217 格式（例如，“USD”、“EUR”、“JPY”）

​
其他资源

DataFast 文档

了解有关 DataFast 的支付 API 和收入归因功能的更多信息。

DataFast 仪表板

访问您的 DataFast 仪表板以查看收入分析和归因数据。
需要帮助吗？请联系 Dodo Payments 支持，邮箱为 [email protected]，以获取集成方面的帮助。