> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DataFast

> 使用 DataFast 分析将收入归因于营销渠道。跟踪哪些流量来源带来了付费客户，并优化您的增长。

## 介绍

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

<Info>
  此集成需要您的 DataFast API 密钥，您可以从您的 [DataFast dashboard](https://datafa.st/) 获取。
</Info>

## 工作原理

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

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

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

## 开始使用

<Steps>
  <Step title="Install DataFast Script">
    首先，在您的网站上安装 DataFast 跟踪脚本。此脚本会创建用于跟踪访客的 `datafast_visitor_id` cookie。

    请访问 [DataFast documentation](https://datafa.st/docs) 获取针对您所用平台的安装说明。
  </Step>

  <Step title="Get Your API Key">
    登录您的 [DataFast dashboard](https://datafa.st/)，并进入网站设置以获取您的 API 密钥。

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

  <Step title="Capture Visitor ID in Checkout">
    在创建结账会话时，从 cookie 捕获 DataFast 访客 ID 并将其添加到您的支付元数据中。
  </Step>

  <Step title="Send Payment Data via Webhook">
    配置一个 webhook，在支付成功时将支付数据发送到 DataFast 的 Payment API。
  </Step>

  <Step title="Done!">
    🎉 现在收入数据将出现在您的 DataFast 仪表板中，并可完整归因到营销渠道。
  </Step>
</Steps>

## 实施指南

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

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

<CodeGroup>
  ```typescript Next.js theme={null}
  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;
  }
  ```

  ```javascript Express.js theme={null}
  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 });
  });
  ```

  ```javascript Other Frameworks theme={null}
  // 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
    },
  });
  ```
</CodeGroup>

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

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

<Steps>
  <Step title="Open the Webhook Section">
    在您的 Dodo Payments 仪表板中，导航至 <b>Webhooks → + 添加端点</b> 并展开集成下拉菜单。

    <Frame>
      <img src="https://mintcdn.com/dodopayments/VOF9xBBvs1EjN4xq/images/integrations/datafast/add.png?fit=max&auto=format&n=VOF9xBBvs1EjN4xq&q=85&s=3aec6c9e450d0616573a4a7dfe89f78e" alt="添加端点和集成下拉菜单" style={{ maxHeight: '500px', width: 'auto' }} width="1720" height="1192" data-path="images/integrations/datafast/add.png" />
    </Frame>
  </Step>

  <Step title="Select DataFast">
    选择 <b>DataFast</b> 集成卡。
  </Step>

  <Step title="Enter API Key">
    在配置字段中提供您的 DataFast API 密钥。

    <Frame>
      <img src="https://mintcdn.com/dodopayments/VOF9xBBvs1EjN4xq/images/integrations/datafast/api-key.png?fit=max&auto=format&n=VOF9xBBvs1EjN4xq&q=85&s=25129c8ca64e38ef44a6960c2f3a2993" alt="添加 API 密钥" style={{ maxHeight: '500px', width: 'auto' }} width="1740" height="882" data-path="images/integrations/datafast/api-key.png" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    编辑转换代码，使其将支付数据格式化为 DataFast 的 Payment API 所需格式。
  </Step>

  <Step title="Test & Create">
    使用示例有效负载进行测试，然后点击 <b>Create</b> 以激活集成。
  </Step>
</Steps>

## 转换代码示例

### 基本支付归因

```javascript basic_payment.js icon="js" expandable theme={null}
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）不使用小数位。相应地调整金额计算：

```javascript zero_decimal.js icon="js" expandable theme={null}
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;
}
```

### 订阅支付

对于定期订阅支付，您可以跟踪每笔支付：

```javascript subscription_payment.js icon="js" expandable theme={null}
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;
}
```

## 最佳实践

<Tip>
  **尽早捕获访客 ID**：在结账流程中尽快存储 DataFast 访客 ID，以确保即使用户中途离开再返回也能正确归因。
</Tip>

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

## 故障排除

<AccordionGroup>
  <Accordion title="Payments not appearing in DataFast">
    * 验证您的 DataFast API 密钥是否正确且已激活
    * 检查 `datafast_visitor_id` 是否已被捕获并存储在支付元数据中
    * 确保 webhook 转换正在正确格式化有效负载
    * 验证 webhook 是否在 `payment.succeeded` 事件触发时运行
    * 在 DataFast 仪表板中查看是否有任何错误消息或 API 日志
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * 确认 DataFast 跟踪脚本已在您的网站上安装并正常运行
    * 验证 `datafast_visitor_id` cookie 是否已正确设置
    * 检查访客 ID 在创建结账和完成支付之间是否一致
    * 确保您在创建结账会话之前就已捕获访客 ID
    * 查阅 DataFast 的 [Payment API documentation](https://datafa.st/docs/payments-api) 以获得额外指导
  </Accordion>

  <Accordion title="Transformation errors">
    * 验证 JSON 结构是否与 DataFast 的 Payment API 格式匹配
    * 检查所有必填字段（`amount`、`currency`、`transaction_id`、`datafast_visitor_id`）是否存在
    * 确保金额已正确转换（对于大多数货币除以 100，零小数货币除外）
    * 验证 API 端点 URL 是否正确：`https://datafa.st/api/v1/payments`
    * 使用示例 webhook 有效负载测试转换
  </Accordion>

  <Accordion title="Currency conversion issues">
    * 对于零小数货币（JPY、KRW、CLP、VND、UGX、MGA），直接按原值发送金额，无需除以 100
    * 对于其他所有货币，需将金额除以 100 来从分转换为基础单位
    * 仔细核对货币代码是否符合 ISO 4217 格式（例如“USD”、“EUR”、“JPY”）
  </Accordion>
</AccordionGroup>

## 其他资源

<CardGroup cols={2}>
  <Card title="DataFast Documentation" icon="book" href="https://datafa.st/docs/payments-api">
    了解有关 DataFast 的 Payment API 和收入归因功能的更多信息。
  </Card>

  <Card title="DataFast Dashboard" icon="chart-bar" href="https://datafa.st/">
    访问您的 DataFast 仪表板，以查看收入分析和归因数据。
  </Card>
</CardGroup>

<Info>
  需要帮助吗？请联系 Dodo Payments 支持团队，发送邮件至 [support@dodopayments.com](mailto:support@dodopayments.com) 获取集成协助。
</Info>