DataFast

المقدمة

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

يتطلب هذا التكامل مفتاح API الخاص بـ DataFast، والذي يمكنك الحصول عليه من لوحة معلومات DataFast.

كيف يعمل

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

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

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

البدء

Install DataFast Script

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

Get Your API Key

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

احفظ مفتاح API بأمان ولا تكشف عنه في كود جانب العميل.

Capture Visitor ID in Checkout

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

Send Payment Data via Webhook

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

Done!

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

دليل التنفيذ

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

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

تستخدم الأمثلة أدناه INLINE_CODE_PLACEHOLDER_387c606e621825f48c606e621825f8_END، وهو مهجور. لا يزال يعمل مع عمليات التكامل الحالية، ولكن يجب أن تستخدم عمليات التكامل الجديدة 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
  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;
}

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 });
});

// 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
  },
});

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

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

Open the Webhook Section

في لوحة تحكم Dodo Payments، انتقل إلى Webhooks → + Add Endpoint ووسّع القائمة المنسدلة للتكاملات.

Select DataFast

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

Enter API Key

أدخل DataFast API Key في حقل الإعداد.

Configure Transformation

عدّل كود التحويل لتنسيق بيانات الدفع بما يتوافق مع Payment API الخاص بـ DataFast.

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 في أقرب وقت ممكن ضمن مسار الدفع لديك لضمان دقة الإسناد، حتى إذا غادر المستخدم الصفحة وعاد لاحقًا.

احرص دائمًا على تضمين معرّف الزائر في metadata: بدون معرّف الزائر، لا يستطيع DataFast إسناد الإيرادات إلى قنوات التسويق
تعامل مع العملات التي لا تستخدم الكسور العشرية: بعض العملات (مثل JPY وKRW وغيرها) لا تستخدم المنازل العشرية—اضبط حساب المبلغ وفقًا لذلك
اختبر باستخدام مدفوعات نموذجية: تحقّق من عمل التكامل بشكل صحيح قبل إطلاقه
راقب لوحة تحكم DataFast: تحقّق من ظهور المدفوعات بشكل صحيح مع الإسناد المناسب
استخدم إعادة محاولة webhook: إن Payment API الخاص بـ DataFast idempotent، لذا فإن إعادة المحاولة آمنة في حال فشل webhook

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

Payments not appearing in DataFast

تحقّق من صحة DataFast API key وتفعيله
تحقّق من التقاط datafast_visitor_id وتخزينه في metadata الخاصة بالدفع
تأكّد من أن تحويل webhook ينسّق الحمولة بشكل صحيح
تحقّق من تشغيل webhook عند أحداث payment.succeeded
تحقّق من لوحة تحكم DataFast بحثًا عن أي رسائل خطأ أو سجلات API

Revenue attribution not working

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

Transformation errors

تحقّق من تطابق بنية JSON مع تنسيق Payment API الخاص بـ DataFast
تحقّق من وجود جميع الحقول المطلوبة (amount وcurrency وtransaction_id وdatafast_visitor_id)
تأكّد من تحويل amount بشكل صحيح (اقسمه على 100 لمعظم العملات، باستثناء العملات التي لا تستخدم الكسور العشرية)
تحقّق من صحة عنوان URL لنقطة نهاية API: https://datafa.st/api/v1/payments
اختبر التحويل باستخدام حمولات webhook نموذجية

Currency conversion issues

بالنسبة إلى العملات التي لا تستخدم الكسور العشرية (JPY وKRW وCLP وVND وUGX وMGA)، أرسل المبلغ كما هو دون قسمته على 100
بالنسبة إلى جميع العملات الأخرى، اقسم المبلغ على 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

المقدمة

كيف يعمل

البدء

دليل التنفيذ

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

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

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

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

التعامل مع العملات التي لا تستخدم الكسور العشرية

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

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

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

موارد إضافية

DataFast Documentation

DataFast Dashboard

​المقدمة

​كيف يعمل

​البدء

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

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

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

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

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

​التعامل مع العملات التي لا تستخدم الكسور العشرية

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

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

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

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

DataFast Documentation

DataFast Dashboard

المقدمة

كيف يعمل

البدء

دليل التنفيذ

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

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

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

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

التعامل مع العملات التي لا تستخدم الكسور العشرية

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

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

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

موارد إضافية