DataFast

المقدمة

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

يتطلب هذا التكامل مفتاح DataFast API، الذي تنشئه في لوحة تحكم DataFast.

كيف يعمل

تعرّف DataFast على كل زائر باستخدام معرّف مخزّن في ملف تعريف الارتباط datafast_visitor_id. لإسناد الإيرادات إلى قنوات التسويق:

التقاط معرّف زائر DataFast من ملف تعريف الارتباط datafast_visitor_id عند إنشاء صفحة الدفع.
تخزين معرّف الزائر في metadata الخاص بعملية الدفع.
إرسال عملية الدفع إلى DataFast عبر Payment API عند نجاح عملية الدفع.

تطابق DataFast كل عملية دفع ناجحة مع مصدر الزيارة الأصلي للزائر، وبذلك تُسند الإيرادات إلى تلك القناة.

البدء

Install DataFast Script

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

Get Your API Key

في لوحة تحكم DataFast، افتح إعدادات موقعك، وانتقل إلى API، ثم انقر على Create API Key.

احتفظ بمفتاح API بأمان. لا تكشفه مطلقًا في التعليمات البرمجية من جانب العميل.

Capture Visitor ID in Checkout

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

Send Payment Data via Webhook

أنشئ نقطة نهاية webhook ترسل كل عملية دفع ناجحة إلى Payment API الخاص بـ DataFast. راجع الخطوة 2.

Done

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

دليل التنفيذ

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

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

تستخدم الأمثلة أدناه POST /payments، وهو مهمل. يظل هذا الخيار يعمل مع عمليات التكامل الحالية، لكن ينبغي لعمليات التكامل الجديدة استخدام Checkout Sessions (POST /checkouts)، التي تقبل metadata بالطريقة نفسها.

import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie (cookies() is async in Next.js 15 and later)
  const datafastVisitorId = (await 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;
}

const express = require('express');
const router = express.Router();

// dodopayments is your initialized Dodo Payments client
router.post('/create-checkout', async (req, res) => {
  // Capture DataFast visitor ID from cookie (req.cookies requires the cookie-parser middleware)
  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 });
});

// Capture DataFast visitor ID from cookie
const datafastVisitorId = getCookie('datafast_visitor_id'); // Use your framework's cookie method

// dodopayments is your initialized Dodo Payments client, and productId is the product to sell
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
  },
});

الخطوة 2: إرسال بيانات الدفع إلى DataFast

أنشئ نقطة نهاية webhook ترسل عمليات الدفع الناجحة إلى Payment API الخاص بـ DataFast.

Open the Webhook Section

في لوحة تحكم Dodo Payments، انتقل إلى Developer → Webhooks وانقر على Add endpoint.

مربع حوار إضافة نقطة نهاية مع تحديد DataFast في القائمة المنسدلة Integration

Select DataFast

ضمن Integration، حدّد DataFast.

Enter API Key

في API key، الصق مفتاح DataFast API الخاص بك. يرسله Dodo Payments في ترويسة Authorization لكل عملية تسليم.

عنوان URL لنقطة نهاية DataFast مملوء وحقل مفتاح API

Check the URL and Events

إذا كان Endpoint URL فارغًا، فأدخل https://datafa.st/api/v1/payments. في Subscribed events، حدد payment.succeeded.

Configure Transformation

ضمن Transformation code، عدّل المعالج لتنسيق بيانات الدفع من أجل Payment API الخاص بـ DataFast. ابدأ من الأمثلة.

Test & Create

ضمن Test this code، انقر على Simulate لتشغيل المعالج باستخدام حمولة نموذجية. ثم انقر على Create endpoint.

أمثلة على Transformation Code

يعمل كل معالج على payment.succeeded. عندما لا يحتوي metadata الخاص بالدفع على معرّف زائر، فإنه يعيّن webhook.cancel = true، ولذلك لا يُرسل أي طلب إلى DataFast. ويظل التسليم الملغى ظاهرًا على أنه ناجح في سجلات webhook. تتلقى Payment API الخاصة بـ DataFast القيمة amount بوحدات العملة الرئيسية، مثل 29.99. يرسل Dodo Payments القيمة total_amount بأصغر وحدة عملة، مثل السنتات بالنسبة إلى USD، ولذلك تحوّل الأمثلة هذه القيمة.

إسناد الدفع الأساسي

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، لا تحتوي على وحدة فرعية، ولذلك تكون total_amount موجودة بالفعل بالوحدات الرئيسية. أما العملات ذات المنازل العشرية الثلاث، مثل KWD، فتحتوي على 1,000 وحدة فرعية لكل وحدة رئيسية. يحوّل هذا المثال المبلغ لكل حالة، باستخدام العملات التي يتعامل معها Dodo Payments على أنها ذات منازل عشرية صفرية وثلاثية:

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: the smallest unit is the major unit
      const zeroDecimalCurrencies = ['BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF'];
      // Three-decimal currencies: 1 major unit = 1000 minor units
      const threeDecimalCurrencies = ['BHD', 'IQD', 'JOD', 'KWD', 'LYD', 'OMR', 'TND'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      const isThreeDecimal = threeDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / (isThreeDecimal ? 1000 : 100), // Convert from minor units
        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;
}

مدفوعات الاشتراكات

تؤدي مدفوعات الاشتراكات أيضًا إلى تشغيل payment.succeeded، مع تعيين subscription_id. يرسل هذا المعالج كل دفعة اشتراك إلى DataFast ويعيّن renewal: true عند التجديد، حتى يتمكن DataFast من التمييز بين التجديد والدفعة الأولى. يُحصّل التجديد خارج الجلسة، ولذلك تحتوي حمولته على subscription_id معيّنًا وcheckout_session_id معيّنًا إلى null. تحتوي الدفعة الأولى لاشتراك تم إنشاؤه عبر Checkout Session على checkout_session_id معيّنًا. وتحمل دفعات التجديد metadata الخاص بالاشتراك، ولذلك احتفظ بـ datafast_visitor_id في metadata الخاصة بالاشتراك لإسناد التجديدات.

subscription_payment.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // A renewal belongs to a subscription and isn't paid through a checkout session
    const isRenewal = Boolean(payment.subscription_id) && !payment.checkout_session_id;
    
    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,
        renewal: isRenewal,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

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

التقاط معرّف الزائر مبكرًا: خزّن معرّف زائر DataFast في أقرب وقت ممكن ضمن تدفق الدفع، حتى يظل الإسناد دقيقًا حتى إذا غادر العميل وعاد لاحقًا.

تضمين معرّف الزائر في metadata: من دون معرّف الزائر، لا يستطيع DataFast إسناد الإيرادات إلى قنوات التسويق.
التعامل مع العملات ذات المنازل العشرية الصفرية: بعض العملات، مثل JPY وKRW، لا تحتوي على منازل عشرية. اضبط تحويل المبلغ لهذه العملات، وكذلك للعملات ذات المنازل العشرية الثلاث مثل KWD.
الاختبار باستخدام مدفوعات نموذجية: شغّل المعالج باستخدام Test this code، وتأكد من عمل التكامل قبل إطلاقه.
مراقبة لوحة تحكم DataFast: تحقق من ظهور المدفوعات مع الإسناد المتوقع.
الاعتماد على إعادة محاولات webhook: يتجاهل DataFast الدفعة التي سجّل بالفعل transaction_id الخاص بها، ولذلك لا يؤدي التسليم المعاد إلى إنشاء نسخة مكررة.

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

Payments Not Appearing in DataFast

تحقق من صحة مفتاح DataFast API وأنه نشط.
تحقق من التقاط datafast_visitor_id وتخزينه في metadata الخاصة بالدفع.
تحقق من أن تحويل webhook ينسّق الحمولة بشكل صحيح.
تحقق من اشتراك نقطة النهاية في payment.succeeded.
تحقق من لوحة تحكم DataFast بحثًا عن رسائل الخطأ أو سجلات API.
افتح محاولات تسليم نقطة النهاية في علامة التبويب Logs ضمن Developer → Webhooks لرؤية استجابة DataFast. يُلغى الدفع الذي لا يحتوي على معرّف زائر ويظهر على أنه ناجح.

Revenue Attribution Not Working

تأكد من تثبيت وتشغيل نص تتبع DataFast على موقعك.
تحقق من تعيين ملف تعريف الارتباط datafast_visitor_id.
تحقق من تطابق معرّف الزائر في metadata الخاصة بالدفع مع المعرّف الذي سجّله DataFast للزيارة.
التقط معرّف الزائر قبل إنشاء الدفع.
راجع توثيق Payment API الخاص بـ DataFast لمزيد من الإرشادات.

Transformation Errors

تحقق من مطابقة الحمولة لتنسيق Payment API الخاص بـ DataFast.
تحقق من وجود جميع الحقول المطلوبة: amount وcurrency وtransaction_id. أدرج datafast_visitor_id للإسناد.
تحقق من تحويل المبلغ: اقسم على 100 لمعظم العملات، وعلى 1,000 للعملات ذات المنازل العشرية الثلاث، ولا تقسّم إطلاقًا للعملات ذات المنازل العشرية الصفرية.
تحقق من أن عنوان URL لنقطة النهاية هو https://datafa.st/api/v1/payments.
اختبر التحويل باستخدام حمولات webhook نموذجية.

Currency Conversion Issues

بالنسبة إلى العملات ذات المنازل العشرية الصفرية (BIF وCLP وDJF وGNF وJPY وKMF وKRW وMGA وPYG وRWF وUGX وVND وVUV وXAF وXOF وXPF)، أرسل المبلغ كما هو.
بالنسبة إلى العملات ذات المنازل العشرية الثلاث (BHD وIQD وJOD وKWD وLYD وOMR وTND)، اقسم المبلغ على 1,000.
بالنسبة إلى جميع العملات الأخرى، اقسم المبلغ على 100 للتحويل من أصغر وحدة إلى الوحدة الرئيسية.
تحقق من استخدام رمز العملة لتنسيق ISO 4217، مثل USD أو EUR أو JPY.

موارد إضافية

DataFast Documentation

اقرأ عن Payment API الخاص بـ DataFast وإسناد الإيرادات.

DataFast Dashboard

اعرض تحليلات الإيرادات وبيانات الإسناد في لوحة تحكم DataFast الخاصة بك.

للحصول على مساعدة بشأن هذا التكامل، تواصل مع دعم Dodo Payments عبر support@dodopayments.com.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Pricing

المقدمة

كيف يعمل

البدء

دليل التنفيذ

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

الخطوة 2: إرسال بيانات الدفع إلى DataFast

أمثلة على Transformation Code

إسناد الدفع الأساسي

التعامل مع العملات ذات المنازل العشرية الصفرية

مدفوعات الاشتراكات

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

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

موارد إضافية

DataFast Documentation

DataFast Dashboard

​المقدمة

​كيف يعمل

​البدء

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

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

​الخطوة 2: إرسال بيانات الدفع إلى DataFast

​أمثلة على Transformation Code

​إسناد الدفع الأساسي

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

​مدفوعات الاشتراكات

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

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

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

DataFast Documentation

DataFast Dashboard

المقدمة

كيف يعمل

البدء

دليل التنفيذ

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

الخطوة 2: إرسال بيانات الدفع إلى DataFast

أمثلة على Transformation Code

إسناد الدفع الأساسي

التعامل مع العملات ذات المنازل العشرية الصفرية

مدفوعات الاشتراكات

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

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

موارد إضافية