> ## 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 대시보드](https://datafa.st/)에서 얻을 수 있습니다.
</Info>

## 작동 방식

DataFast는 쿠키에 저장된 고유 방문자 ID를 통해 방문자를 추적합니다. 마케팅 채널에 수익을 귀속시키려면 다음을 수행해야 합니다:

1. 체크아웃 세션을 생성할 때 `datafast_visitor_id` 쿠키에서 **DataFast 방문자 ID를 캡처**합니다
2. 결제 메타데이터에 **방문자 ID를 저장**합니다
3. 결제가 성공하면 DataFast의 Payment API를 사용하여 **결제 데이터를 DataFast로 전송**합니다

이렇게 하면 DataFast가 성공적인 결제를 원래의 트래픽 소스와 일치시킬 수 있어 완전한 수익 귀속이 가능합니다.

## 시작하기

<Steps>
  <Step title="Install DataFast Script">
    먼저 웹사이트에 DataFast 추적 스크립트를 설치합니다. 이렇게 하면 방문자를 추적하는 `datafast_visitor_id` 쿠키가 생성됩니다.

    플랫폼별 설치 지침은 [DataFast 문서](https://datafa.st/docs)를 참조하세요.
  </Step>

  <Step title="Get Your API Key">
    [DataFast 대시보드](https://datafa.st/)에 로그인한 다음 웹사이트 설정으로 이동하여 API 키를 얻습니다.

    <Warning>
      API 키를 안전하게 보관하고 클라이언트 측 코드에 절대 노출하지 마세요.
    </Warning>
  </Step>

  <Step title="Capture Visitor ID in Checkout">
    체크아웃 세션을 생성할 때 쿠키에서 DataFast 방문자 ID를 가져와 결제 메타데이터에 추가하세요.
  </Step>

  <Step title="Send Payment Data via Webhook">
    결제가 성공할 때 DataFast의 Payment API로 결제 데이터를 전송하도록 웹후크를 구성하세요.
  </Step>

  <Step title="Done!">
    🎉 이제 수익 데이터가 마케팅 채널에 대한 전체 귀속 정보와 함께 DataFast 대시보드에 표시됩니다.
  </Step>
</Steps>

## 구현 가이드

### 1단계: 체크아웃 메타데이터에 방문자 ID 추가

체크아웃 세션을 생성할 때 쿠키에서 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에 결제 데이터 전송

결제가 성공할 때 DataFast의 결제 API에 결제 데이터를 전송하도록 웹훅 엔드포인트를 구성합니다.

<Steps>
  <Step title="Open the Webhook Section">
    Dodo Payments 대시보드에서 <b>Webhooks → + Add Endpoint</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="Add Endpoint and integrations dropdown" 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="Add API Key" 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 대시보드 모니터링**: 결제가 올바르게 나타나고 적절한 귀속이 이루어지고 있는지 확인하세요.
* **웹훅 재시도 사용**: DataFast의 결제 API는 멱등성이 있으므로 웹훅이 실패할 경우 재시도가 안전합니다.

## 문제 해결

<AccordionGroup>
  <Accordion title="Payments not appearing in DataFast">
    * DataFast API 키가 올바르고 활성화되어 있는지 확인하세요
    * `datafast_visitor_id`가 캡처되어 결제 메타데이터에 저장되고 있는지 확인하세요
    * 웹후크 변환이 페이로드를 올바르게 포맷하는지 확인하세요
    * 웹후크가 `payment.succeeded` 이벤트에서 트리거되는지 확인하세요
    * 오류 메시지나 API 로그가 있는지 DataFast 대시보드를 확인하세요
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * DataFast 추적 스크립트가 웹사이트에 설치되어 제대로 작동하는지 확인하세요
    * `datafast_visitor_id` 쿠키가 올바르게 설정되고 있는지 확인하세요
    * 체크아웃 생성과 결제 완료 간에 방문자 ID가 일치하는지 확인하세요
    * 체크아웃 세션을 만들기 전에 방문자 ID를 캡처하고 있는지 확인하세요
    * 추가 안내는 DataFast의 [Payment API 문서](https://datafa.st/docs/payments-api)를 검토하세요
  </Accordion>

  <Accordion title="Transformation errors">
    * JSON 구조가 DataFast의 Payment API 형식과 일치하는지 검증하세요
    * 필요한 모든 필드(`amount`, `currency`, `transaction_id`, `datafast_visitor_id`)가 존재하는지 확인하세요
    * 대부분의 통화에서는 금액을 100으로 나누어 변환하지만, 0소수 통화는 제외합니다
    * API 엔드포인트 URL이 `https://datafa.st/api/v1/payments`로 올바른지 확인하세요
    * 샘플 웹후크 페이로드로 변환을 테스트하세요
  </Accordion>

  <Accordion title="Currency conversion issues">
    * 0소수 통화(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>
  도움이 필요하시면 통합 관련 지원을 위해 [support@dodopayments.com](mailto:support@dodopayments.com)으로 Dodo Payments 지원팀에 문의하세요.
</Info>