DataFast

介绍

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

此集成需要您的 DataFast API 密钥，您可以从您的 DataFast dashboard 获取。

工作原理

DataFast 通过存储在 cookie 中的唯一访客 ID 跟踪访问者。要将收入归因于营销渠道，您需要：

在创建结账会话时从 datafast_visitor_id cookie 捕获 DataFast 的访客 ID
将访客 ID 存储在您的支付元数据中
在支付成功时通过其 Payment API 向 DataFast 发送支付数据

这使 DataFast 能够将成功的支付与原始流量来源匹配，从而为您提供完整的收入归因。

开始使用

Install DataFast Script

首先，在您的网站上安装 DataFast 跟踪脚本。此脚本会创建用于跟踪访客的 datafast_visitor_id cookie。请访问 DataFast documentation 获取针对您所用平台的安装说明。

Get Your API Key

登录您的 DataFast dashboard，并进入网站设置以获取您的 API 密钥。

保持您的 API 密钥安全，切勿在客户端代码中暴露。

Capture Visitor ID in Checkout

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

Send Payment Data via Webhook

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

Done!

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

实施指南

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

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

以下示例使用 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
  const datafastVisitorId = 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();

router.post('/create-checkout', async (req, res) => {
  // Capture DataFast visitor ID from cookie
  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

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 控制面板中，前往 Webhooks → + Add Endpoint，然后展开集成下拉菜单。

Select DataFast

选择 DataFast 集成卡片。

Enter API Key

在配置字段中输入你的 DataFast API Key。

Configure Transformation

编辑转换代码，以便为 DataFast 的 Payment API 格式化支付数据。

Test & Create

使用示例 payload 进行测试，然后点击 Create 激活集成。

转换代码示例

基本支付归因

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

处理零小数位货币

某些货币（如 JPY）不使用小数位。请相应调整金额计算：

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: JPY, KRW, CLP, etc.
      const zeroDecimalCurrencies = ['JPY', 'KRW', 'CLP', 'VND', 'UGX', 'MGA'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      
      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 {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  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 && 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,
        // Optional: Add subscription context
        ...(isSubscription && {
          subscription_id: payment.subscription_id,
        }),
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

最佳实践

尽早捕获访客 ID：在结账流程中尽早存储 DataFast visitor ID，以确保准确归因，即使用户离开后又返回。

始终在 metadata 中包含 visitor ID：如果没有 visitor ID，DataFast 将无法将收入归因到营销渠道
处理零小数位货币：某些货币（如 JPY、KRW 等）不使用小数位——请相应调整金额计算
使用示例支付进行测试：在正式上线前确认集成正常运行
监控你的 DataFast 控制面板：检查支付是否正确显示并具有适当的归因信息
使用 webhook 重试：DataFast 的 Payment API 具有幂等性，因此 webhook 失败时可以安全地重试

故障排除

Payments not appearing in DataFast

确认你的 DataFast API key 正确且处于启用状态
检查是否已捕获 datafast_visitor_id 并将其存储在支付 metadata 中
确保 webhook 转换能够正确格式化 payload
确认 webhook 是否针对 payment.succeeded 事件触发
检查 DataFast 控制面板中是否有任何错误消息或 API 日志

Revenue attribution not working

确认 DataFast tracking script 已安装并在你的网站上正常运行
确认 datafast_visitor_id cookie 已正确设置
检查 checkout 创建与支付完成之间的 visitor ID 是否匹配
确保在创建 checkout session 之前捕获 visitor ID
查阅 DataFast 的 Payment API 文档了解更多指导

Transformation errors

验证 JSON 结构是否符合 DataFast 的 Payment API 格式
检查所有必需字段（amount、currency、transaction_id、datafast_visitor_id）是否存在
确保金额已正确转换（对于大多数货币，除以 100；零小数位货币除外）
确认 API endpoint URL 正确：https://datafa.st/api/v1/payments
使用示例 webhook payload 测试转换

Currency conversion issues

对于零小数位货币（JPY、KRW、CLP、VND、UGX、MGA），直接发送金额，不要除以 100
对于其他所有货币，将金额除以 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

介绍

工作原理

开始使用

实施指南

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

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

转换代码示例

基本支付归因

处理零小数位货币

订阅支付

最佳实践

故障排除

其他资源

DataFast Documentation

DataFast Dashboard

​介绍

​工作原理

​开始使用

​实施指南

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

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

​转换代码示例

​基本支付归因

​处理零小数位货币

​订阅支付

​最佳实践

​故障排除

​其他资源

DataFast Documentation

DataFast Dashboard

介绍

工作原理

开始使用

实施指南

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

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

转换代码示例

基本支付归因

处理零小数位货币

订阅支付

最佳实践

故障排除

其他资源