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

​
المقدمة

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

​
كيف يعمل

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

​
البدء

1

تثبيت سكربت DataFast

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

احصل على مفتاح API الخاص بك

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

التقاط معرف الزائر في الدفع

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

إرسال بيانات الدفع عبر Webhook

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

تم!

🎉 ستظهر الآن بيانات الإيرادات في لوحة معلومات 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

فتح قسم Webhook

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

اختيار DataFast

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

إدخال مفتاح API

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

تكوين التحويل

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

اختبار وإنشاء

اختبر باستخدام حمولات عينة وانقر على إنشاء لتفعيل التكامل.

​
أمثلة كود التحويل

​
نسب الدفع الأساسية

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

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

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

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

وثائق DataFast

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

لوحة معلومات DataFast

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