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

​
المقدمة

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?.datafast_visitor_id) {
      webhook.url = "https://datafa.st/api/v1/payments";
      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 {
      // Skip if no visitor ID (prevents unnecessary API calls)
      return null;
    }
  }
  return webhook;
}

​
التعامل مع العملات ذات الصفر العشري

بعض العملات (مثل JPY) لا تستخدم أماكن عشرية. قم بتعديل حساب المبلغ وفقًا لذلك:
zero_decimal.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (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.url = "https://datafa.st/api/v1/payments";
      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 {
      return null;
    }
  }
  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?.datafast_visitor_id) {
      webhook.url = "https://datafa.st/api/v1/payments";
      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 {
      return null;
    }
  }
  return webhook;
}

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

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

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

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

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

وثائق DataFast

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

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

الوصول إلى لوحة معلومات DataFast الخاصة بك لعرض تحليلات الإيرادات وبيانات النسب.
تحتاج إلى مساعدة؟ اتصل بدعم Dodo Payments على [email protected] للحصول على المساعدة في التكامل.