الانتقال إلى المحتوى الرئيسي

​
المقدمة

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

​
كيف يعمل

تتبع DataFast الزوار من خلال معرف زائر فريد يتم تخزينه في ملف تعريف الارتباط. لنسب الإيرادات إلى قنوات التسويق، تحتاج إلى:
  1. قم بالتقاط معرف زائر DataFast من ملف تعريف الارتباط datafast_visitor_id عند إنشاء جلسات الخروج
  2. قم بتخزين معرف الزائر في بيانات التعريف الخاصة بالدفع
  3. أرسل بيانات الدفع إلى DataFast عند نجاح المدفوعات باستخدام واجهة برمجة تطبيقات الدفع الخاصة بهم
يسمح ذلك لـ DataFast بمطابقة المدفوعات الناجحة مع مصدر الحركة الأصلي، مما يمنحك نسب الإيرادات الكاملة.

​
البدء

1

Install DataFast Script

أولاً، قم بتثبيت برنامج تتبع DataFast على موقعك الإلكتروني. هذا ينشئ ملف تعريف الارتباط datafast_visitor_id الذي يتتبع زوارك.قم بزيارة توثيق DataFast للحصول على تعليمات التثبيت الخاصة بمنصتك.
2

Get Your API Key

قم بتسجيل الدخول إلى لوحة معلومات DataFast وانتقل إلى إعدادات موقعك للحصول على مفتاح API.
احفظ مفتاح API بأمان ولا تكشف عنه في كود جانب العميل.
3

Capture Visitor ID in Checkout

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

Send Payment Data via Webhook

قم بتكوين ويب هوك لإرسال بيانات الدفع إلى واجهة برمجة تطبيقات الدفع الخاصة بـ DataFast عند نجاح المدفوعات.
5

Done!

🎉 ستظهر بيانات الإيرادات الآن في لوحة معلومات DataFast مع الإسناد الكامل لقنوات التسويق.

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

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

عند إنشاء جلسة دفع، قم بالتقاط معرف زائر DataFast من ملف تعريف الارتباط وأدرجه في بيانات الدفع الخاصة بك. 
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 عند نجاح المدفوعات.
1

Open the Webhook Section

في لوحة تحكم Dodo Payments، انتقل إلى Webhooks → + Add Endpoint وقم بتوسيع قائمة التكاملات.
إضافة نقطة نهاية وقائمة التكاملات
2

Select DataFast

اختر بطاقة التكامل DataFast.
3

Enter API Key

قدم مفتاح API الخاص بـ DataFast في حقل التكوين.
إضافة مفتاح API
4

Configure Transformation

قم بتحرير كود التحويل لتنسيق بيانات الدفع لواجهة برمجة تطبيقات الدفع الخاصة بـ DataFast.
5

Test & Create

اختبر باستخدام أحمال تجريبية وانقر على 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;
}

​
أفضل الممارسات

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

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

  • تأكد من أن مفتاح API الخاص بـ DataFast صحيح ومفعل
  • تحقق من أنه يتم التقاط datafast_visitor_id وتخزينه في بيانات التعريف الخاصة بالدفع
  • تأكد من أن تحويل الويب هوك ينسق الحمولة بشكل صحيح
  • تحقق من أن الويب هوك يتم تشغيله عند أحداث payment.succeeded
  • تحقق من لوحة معلومات DataFast لأي رسائل خطأ أو سجلات API
  • تأكد من تثبيت برنامج تتبع DataFast ويعمل على موقعك
  • تحقق من أن ملف تعريف الارتباط datafast_visitor_id يتم تعيينه بشكل صحيح
  • تأكد من تطابق معرفات الزوار بين إنشاء الخروج وإتمام الدفع
  • تأكد من التقاط معرف الزائر قبل إنشاء جلسة الخروج
  • راجع توثيق واجهة برمجة تطبيقات الدفع الخاص بـ DataFast لمزيد من الإرشادات
  • تحقق من تطابق هيكل JSON مع تنسيق واجهة برمجة تطبيقات الدفع الخاصة بـ DataFast
  • تأكد من تضمين جميع الحقول المطلوبة (amount, currency, transaction_id, datafast_visitor_id)
  • تأكد من تحويل المبلغ بشكل صحيح (قسّم على 100 لمعظم العملات، باستثناء العملات ذات الأرقام العشرية الصفرية)
  • تحقق من أن عنوان نقطة نهاية API صحيح: https://datafa.st/api/v1/payments
  • اختبر التحويل باستخدام أحمال ويب هوك تجريبية
  • بالنسبة للعملات ذات الأرقام العشرية الصفرية (JPY، KRW، CLP، VND، UGX، MGA)، أرسل المبلغ كما هو دون تقسيمه على 100
  • بالنسبة لجميع العملات الأخرى، قسّم المبلغ على 100 لتحويله من السنت إلى الوحدة الأساسية
  • تحقق مرة أخرى من أن رمز العملة يطابق تنسيق ISO 4217 (مثل “USD”، “EUR”، “JPY”)

​
موارد إضافية

DataFast Documentation

تعرّف على المزيد حول واجهة برمجة تطبيقات الدفع وميزات إسناد الإيرادات الخاصة بـ DataFast.

DataFast Dashboard

ادخل إلى لوحة معلومات DataFast للاطلاع على تحليلات الإيرادات وبيانات الإسناد.
هل تحتاج مساعدة؟ اتصل بدعم Dodo Payments على support@dodopayments.com للحصول على مساعدة في التكامل.