> ## 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>
  يتطلب هذا التكامل مفتاح API الخاص بـ DataFast، والذي يمكنك الحصول عليه من [لوحة معلومات DataFast](https://datafa.st/).
</Info>

## كيف يعمل

تتبع DataFast الزوار من خلال معرف زائر فريد يتم تخزينه في ملف تعريف الارتباط. لنسب الإيرادات إلى قنوات التسويق، تحتاج إلى:

1. **قم بالتقاط معرف زائر DataFast** من ملف تعريف الارتباط `datafast_visitor_id` عند إنشاء جلسات الخروج
2. **قم بتخزين معرف الزائر** في بيانات التعريف الخاصة بالدفع
3. **أرسل بيانات الدفع إلى 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 من ملف تعريف الارتباط وأضفه إلى بيانات التعريف الخاصة بالدفع.
  </Step>

  <Step title="Send Payment Data via Webhook">
    قم بتكوين ويب هوك لإرسال بيانات الدفع إلى واجهة برمجة تطبيقات الدفع الخاصة بـ DataFast عند نجاح المدفوعات.
  </Step>

  <Step title="Done!">
    🎉 ستظهر بيانات الإيرادات الآن في لوحة معلومات DataFast مع الإسناد الكامل لقنوات التسويق.
  </Step>
</Steps>

## دليل التنفيذ

### الخطوة 1: إضافة معرف الزائر إلى بيانات الدفع

عند إنشاء جلسة دفع، قم بالتقاط معرف زائر DataFast من ملف تعريف الارتباط وأدرجه في بيانات الدفع الخاصة بك.

<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 عند نجاح المدفوعات.

<Steps>
  <Step title="Open the Webhook Section">
    في لوحة معلومات دفعات Dodo، انتقل إلى <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="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">
    قدّم مفتاح API الخاص بك لـ DataFast في حقل التكوين.

    <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.
  </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>
  **قم بالتقاط معرف الزائر مبكرًا**: خزّن معرف زائر DataFast في أقرب وقت ممكن خلال سير الخروج لضمان الإسناد الدقيق، حتى لو تنقل المستخدم بعيدًا وعاد لاحقًا.
</Tip>

* **تأكد دائمًا من تضمين معرف الزائر في البيانات الوصفية**: بدون معرف الزائر، لا يمكن لـ DataFast نسب الإيرادات إلى قنوات التسويق
* **التعامل مع العملات ذات الصفر العشري**: بعض العملات (JPY، KRW، إلخ) لا تستخدم أماكن عشرية - قم بتعديل حساب المبلغ وفقًا لذلك
* **اختبر باستخدام مدفوعات عينة**: تحقق من أن التكامل يعمل بشكل صحيح قبل الذهاب للعرض
* **راقب لوحة معلومات DataFast الخاصة بك**: تحقق من أن المدفوعات تظهر بشكل صحيح مع نسب صحيحة
* **استخدم إعادة المحاولة لـ Webhook**: واجهة برمجة التطبيقات الخاصة بـ DataFast هي idempotent، لذا فإن إعادة المحاولة آمنة إذا فشل Webhook

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="Payments not appearing in DataFast">
    * تأكد من أن مفتاح API الخاص بـ DataFast صحيح ومفعل
    * تحقق من أنه يتم التقاط `datafast_visitor_id` وتخزينه في بيانات التعريف الخاصة بالدفع
    * تأكد من أن تحويل الويب هوك ينسق الحمولة بشكل صحيح
    * تحقق من أن الويب هوك يتم تشغيله عند أحداث `payment.succeeded`
    * تحقق من لوحة معلومات DataFast لأي رسائل خطأ أو سجلات API
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * تأكد من تثبيت برنامج تتبع DataFast ويعمل على موقعك
    * تحقق من أن ملف تعريف الارتباط `datafast_visitor_id` يتم تعيينه بشكل صحيح
    * تأكد من تطابق معرفات الزوار بين إنشاء الخروج وإتمام الدفع
    * تأكد من التقاط معرف الزائر قبل إنشاء جلسة الخروج
    * راجع [توثيق واجهة برمجة تطبيقات الدفع](https://datafa.st/docs/payments-api) الخاص بـ DataFast لمزيد من الإرشادات
  </Accordion>

  <Accordion title="Transformation errors">
    * تحقق من تطابق هيكل JSON مع تنسيق واجهة برمجة تطبيقات الدفع الخاصة بـ DataFast
    * تأكد من تضمين جميع الحقول المطلوبة (`amount`, `currency`, `transaction_id`, `datafast_visitor_id`)
    * تأكد من تحويل المبلغ بشكل صحيح (قسّم على 100 لمعظم العملات، باستثناء العملات ذات الأرقام العشرية الصفرية)
    * تحقق من أن عنوان نقطة نهاية API صحيح: `https://datafa.st/api/v1/payments`
    * اختبر التحويل باستخدام أحمال ويب هوك تجريبية
  </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.
  </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>