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

مرجع API - استيعاب الأحداث

الوصول إلى الوثائق الكاملة لواجهة برمجة التطبيقات لاستيعاب أحداث الاستخدام واختبار طلبات واستجابات استيعاب الأحداث بشكل تفاعلي.

مرجع API - إنشاء العدادات

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

​
إنشاء عداد

تعرف العدادات كيفية تجميع وقياس أحداث الاستخدام لأغراض الفوترة. قبل إنشاء عداد، خطط لاستراتيجية تتبع الاستخدام الخاصة بك:
  • تحديد أحداث الاستخدام التي تريد تتبعها
  • تحديد كيفية تجميع الأحداث (عدد، مجموع، إلخ)
  • تعريف أي متطلبات تصفية لحالات الاستخدام المحددة

​
خطوات إنشاء العداد خطوة بخطوة

اتبع هذا الدليل الشامل لإعداد عداد الاستخدام الخاص بك:
1

تكوين المعلومات الأساسية

قم بإعداد التفاصيل الأساسية لعدادك.
​
اسم العداد
string
required
اختر اسمًا واضحًا ووصفًا يحدد ما يتعقب هذا العداد.أمثلة: “رموز”, “استدعاءات API”, “استخدام التخزين”, “ساعات الحوسبة”
​
الوصف
string
قدم شرحًا تفصيليًا لما يقيسه هذا العداد.مثال: “يعد كل طلب POST /v1/orders الذي يقوم به العميل”
​
اسم الحدث
string
required
حدد معرف الحدث الذي سيؤدي إلى تشغيل هذا العداد.أمثلة: “token”, “api.call”, “storage.usage”, “compute.session”
يجب أن يتطابق اسم الحدث تمامًا مع ما ترسله في أحداث الاستخدام الخاصة بك. أسماء الأحداث حساسة لحالة الأحرف.
2

تكوين إعدادات التجميع

حدد كيفية حساب العداد للاستخدام من أحداثك.
​
نوع التجميع
string
required
اختر كيفية تجميع الأحداث:
يعد ببساطة عدد الأحداث المستلمة.حالة الاستخدام: استدعاءات API، مشاهدات الصفحات، تحميلات الملفاتالحساب: إجمالي عدد الأحداث
​
على الخاصية
string
اسم الخاصية من بيانات الحدث لتجميعها.
هذا الحقل مطلوب عند استخدام أنواع التجميع Sum أو Max أو Last.
​
وحدة القياس
string
required
حدد تسمية الوحدة لأغراض العرض في التقارير والفوترة.أمثلة: “استدعاءات”, “جيجابايت”, “ساعات”, “رموز”
3

تكوين تصفية الأحداث (اختياري)

قم بإعداد معايير للتحكم في الأحداث التي يتم تضمينها في العداد.
تسمح لك تصفية الأحداث بإنشاء قواعد معقدة تحدد أي الأحداث تساهم في حسابات الاستخدام الخاصة بك. هذا مفيد لاستبعاد أحداث الاختبار، أو التصفية حسب مستويات المستخدمين، أو التركيز على إجراءات معينة.
تفعيل تصفية الأحداثقم بتبديل تفعيل تصفية الأحداث لتنشيط معالجة الأحداث الشرطية.اختر منطق التصفيةحدد كيفية تقييم الشروط المتعددة:
يجب أن تكون جميع الشروط صحيحة حتى يتم احتساب الحدث. استخدم هذا عندما تحتاج الأحداث لتلبية عدة معايير صارمة في وقت واحد.مثال: احتساب استدعاءات API حيث user_tier = "premium" AND endpoint = "/api/v2/users"
إعداد شروط التصفية
1

إضافة شرط

انقر على إضافة شرط لإنشاء قاعدة تصفية جديدة.
2

تكوين مفتاح الخاصية

حدد اسم الخاصية من بيانات الحدث الخاصة بك.
3

اختر المقارن

اختر من بين المشغلين المتاحين:
  • equals - تطابق دقيق
  • not equals - فلتر استبعاد
  • greater than - مقارنة عددية
  • greater than or equals - مقارنة عددية (شاملة)
  • less than - مقارنة عددية
  • less than or equals - مقارنة عددية (شاملة)
  • contains - السلسلة تحتوي على جزء فرعي
  • does not contain - فلتر استبعاد السلسلة
4

تعيين قيمة المقارنة

قم بتعيين القيمة المستهدفة للمقارنة.
5

إضافة مجموعات

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

إنشاء عداد

راجع تكوين العداد الخاص بك وانقر على إنشاء عداد.
عدادك جاهز الآن لاستقبال وتجميع أحداث الاستخدام.

​
ربط العداد بمنتج

بمجرد إنشاء العداد الخاص بك، تحتاج إلى ربطه بمنتج لتمكين الفوترة المعتمدة على الاستخدام. هذه العملية تربط بيانات استخدام العداد الخاصة بك بقواعد التسعير لفوترة العملاء. تربط العدادات بالمنتجات الاتصال بين تتبع الاستخدام والفوترة:
  • تحدد المنتجات قواعد التسعير وسلوك الفوترة
  • توفر العدادات بيانات الاستخدام لحسابات الفوترة
  • يمكن ربط عدة عدادات بمنتج واحد لسيناريوهات فوترة معقدة

​
عملية تكوين المنتج

حوّل بيانات الاستخدام الخاصة بك إلى رسوم قابلة للفوترة من خلال تكوين إعدادات المنتج الخاصة بك بشكل صحيح:
1

اختر نوع المنتج المعتمد على الفوترة

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

حدد العداد المرتبط

انقر على العداد المرتبط لفتح لوحة اختيار العداد من الجانب.تتيح لك هذه اللوحة تكوين أي العدادات ستتبع الاستخدام لهذا المنتج.
3

أضف العداد الخاص بك

في لوحة اختيار العداد:
  1. انقر على إضافة عدادات لعرض العدادات المتاحة
  2. اختر العداد الذي أنشأته من قائمة السحب
  3. سيظهر العداد المحدد في تكوين المنتج الخاص بك
4

تكوين السعر لكل وحدة

حدد التسعير لكل وحدة من الاستخدام التي تتبعها عدادك.
​
السعر لكل وحدة
number
required
حدد مقدار الرسوم لكل وحدة يقيسها عدادك.مثال: تعيين $0.50 لكل وحدة يعني:
  • 1,000 وحدة مستهلكة = 1,000 × $0.50 = 500.00 رسوم
  • 500 وحدة مستهلكة = 500 × $0.50 = 250.00 رسوم
  • 100 وحدة مستهلكة = 100 × $0.50 = 50.00 رسوم
5

تعيين الحد المجاني (اختياري)

قم بتكوين بدل استخدام مجاني قبل بدء الفوترة.
​
الحد المجاني
number
عدد الوحدات التي يمكن للعملاء استهلاكها دون رسوم قبل بدء حساب الاستخدام المدفوع.كيف يعمل:
  • الحد المجاني: 100 وحدة
  • السعر لكل وحدة: $0.50
  • استخدام العميل: 250 وحدة
  • الحساب: (250 - 100) × 0.50=∗∗0.50 = **75.00** رسوم
الحدود المجانية مثالية لنماذج الفريميوم، فترات التجربة، أو توفير قاعدة للعملاء مشمولة في خطتهم.
ينطبق الحد المجاني على كل دورة فوترة، مما يمنح العملاء بدلات جديدة شهريًا أو وفقًا لجدول فوترة الخاص بك.
6

حفظ التكوين

راجع تكوين العداد والتسعير الخاص بك، ثم انقر على حفظ التغييرات لإنهاء الإعداد.
تم تكوين منتجك الآن للفوترة المعتمدة على الاستخدام وسيقوم تلقائيًا بفرض رسوم على العملاء بناءً على استهلاكهم المقاس.
ماذا يحدث بعد ذلك:
  • سيتم تتبع أحداث الاستخدام المرسلة إلى عدادك وتجميعها
  • ستطبق حسابات الفوترة قواعد التسعير الخاصة بك تلقائيًا
  • سيتم فرض رسوم على العملاء بناءً على الاستهلاك الفعلي خلال كل دورة فوترة
تذكر أنه يمكنك إضافة ما يصل إلى 10 عدادات لكل منتج، مما يمكّن تتبع الاستخدام المعقد عبر أبعاد متعددة مثل استدعاءات API، التخزين، وقت الحوسبة، والقياسات المخصصة.

​
إرسال أحداث الاستخدام

بمجرد تكوين عدادك، يمكنك البدء في إرسال أحداث الاستخدام من تطبيقك لتتبع استخدام العملاء.

​
هيكل الحدث

يجب أن تتضمن كل حدث استخدام هذه الحقول المطلوبة:
​
event_id
string
required
معرف فريد لهذا الحدث المحدد. يجب أن يكون فريدًا عبر جميع الأحداث.
​
customer_id
string
required
معرف عميل مدفوعات دودو الذي يجب أن يُنسب إليه هذا الاستخدام.
​
event_name
string
required
اسم الحدث الذي يتطابق مع تكوين العداد الخاص بك. أسماء الأحداث تؤدي إلى تشغيل العداد المناسب.
​
timestamp
string
تاريخ ووقت ISO 8601 عندما حدث الحدث. الافتراضي هو الوقت الحالي إذا لم يتم توفيره.
​
metadata
object
خصائص إضافية للتصفية والتجميع. قم بتضمين أي قيم تم الإشارة إليها في “على الخاصية” أو شروط التصفية الخاصة بالعداد.

​
أمثلة API لأحداث الاستخدام

أرسل أحداث الاستخدام إلى العدادات المكونة الخاصة بك باستخدام واجهة برمجة التطبيقات للأحداث: 
const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

​
تحليلات الفوترة المعتمدة على الاستخدام

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

​
تحليلات نظرة عامة

يوفر علامة التبويب نظرة عامة عرضًا شاملاً لأداء الفوترة المعتمدة على الاستخدام الخاصة بك:

​
مقاييس النشاط

تتبع إحصائيات الاستخدام الرئيسية عبر فترات زمنية مختلفة:
​
الشهر الحالي
metric
يعرض نشاط الاستخدام لفترة الفوترة الحالية، مما يساعدك على فهم أنماط الاستهلاك الشهرية.
​
جميع الأوقات
metric
يعرض إحصائيات الاستخدام التراكمية منذ بدء تتبعك، مما يوفر رؤى حول النمو على المدى الطويل.
استخدم محدد الفترة الزمنية لمقارنة الاستخدام عبر أشهر مختلفة وتحديد الاتجاهات الموسمية أو أنماط النمو.

​
مخطط كميات العدادات

مخطط كميات العدادات يظهر اتجاهات الاستخدام بمرور الوقت مع تصور تدرج أرجواني
يصور مخطط كميات العدادات اتجاهات الاستخدام بمرور الوقت مع الميزات التالية:
  • تصور السلاسل الزمنية: تتبع أنماط الاستخدام عبر الأيام أو الأسابيع أو الأشهر
  • دعم عدة عدادات: عرض البيانات من عدادات مختلفة في وقت واحد
  • تحليل الاتجاهات: تحديد ذروات الاستخدام، الأنماط، ومسارات النمو
يتكيف المخطط تلقائيًا بناءً على حجم الاستخدام الخاص بك والنطاق الزمني المحدد، مما يوفر رؤية واضحة لكل من التقلبات الصغيرة والتغيرات الكبيرة في الاستخدام.

​
تحليلات الأحداث

جدول الأحداث يظهر أسماء الأحداث، المعرفات، وعناصر التحكم في الصفحات لتحليل الأحداث بالتفصيل
يوفر علامة التبويب الأحداث رؤية دقيقة لأحداث الاستخدام الفردية:

​
عرض معلومات الحدث

يوفر جدول الأحداث عرضًا واضحًا لأحداث الاستخدام الفردية مع الأعمدة التالية:
  • اسم الحدث: الإجراء أو الزناد المحدد الذي أنشأ حدث الاستخدام
  • معرف الحدث: معرف فريد لكل حالة حدث
  • معرف العميل: العميل المرتبط بالحدث
  • التاريخ والوقت: متى حدث الحدث
تتيح لك هذه الرؤية تتبع ومراقبة أحداث الاستخدام الفردية عبر قاعدة عملائك، مما يوفر الشفافية في حسابات الفوترة وأنماط الاستخدام.

​
تحليلات العملاء

يوفر علامة التبويب العملاء عرضًا تفصيليًا لبيانات استخدام العملاء مع المعلومات التالية:

​
أعمدة البيانات المتاحة

​
البريد الإلكتروني للعميل
string
عنوان البريد الإلكتروني للعميل للتعريف.
​
معرف الاشتراك
string
معرف فريد لاشتراك العميل.
​
الحد المجاني
number
عدد الوحدات المجانية المضمنة في خطة العميل قبل تطبيق الرسوم.
​
السعر لكل وحدة
currency
التكلفة لكل وحدة للاستخدام الذي يتجاوز الحد المجاني.
​
آخر حدث
timestamp
تاريخ ووقت آخر حدث استخدام للعميل.
​
إجمالي السعر
currency
إجمالي المبلغ المفروض على العميل مقابل الفوترة المعتمدة على الاستخدام.
​
الوحدات المستهلكة
number
إجمالي عدد الوحدات التي استهلكها العميل.
​
الوحدات القابلة للفوترة
number
عدد الوحدات التي تتجاوز الحد المجاني وتخضع للرسوم.

​
ميزات الجدول

  • تصفية الأعمدة: استخدم ميزة “تحرير الأعمدة” لإظهار/إخفاء أعمدة البيانات المحددة
  • تحديثات في الوقت الحقيقي: تعكس بيانات الاستخدام أحدث مقاييس الاستهلاك

​
أمثلة التجميع

إليك أمثلة عملية لكيفية عمل أنواع التجميع المختلفة:

​
فهم أنواع التجميع

تخدم أنواع التجميع المختلفة سيناريوهات فوترة مختلفة. اختر النوع الصحيح بناءً على كيفية قياسك وفرض رسوم على الاستخدام.

​
أمثلة التنفيذ العملية

توضح هذه الأمثلة التطبيقات الواقعية لكل نوع تجميع مع أحداث نموذجية والنتائج المتوقعة.
السيناريو: تتبع العدد الإجمالي لطلبات APIتكوين العداد:
  • اسم الحدث: api.call
  • نوع التجميع: عدد
  • وحدة القياس: calls
أحداث نموذجية:
{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}
النتيجة: 3 استدعاءات مفروضة على العميل
السيناريو: فرض رسوم بناءً على إجمالي البايتات المنقولةتكوين العداد:
  • اسم الحدث: data.transfer
  • نوع التجميع: مجموع
  • على الخاصية: bytes
  • وحدة القياس: GB
أحداث نموذجية:
{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}
النتيجة: 1.5 جيجابايت إجمالي نقل مفروض على العميل
السيناريو: فرض رسوم بناءً على أعلى عدد من المستخدمين المتزامنينتكوين العداد:
  • اسم الحدث: concurrent.users
  • نوع التجميع: أقصى
  • على الخاصية: count
  • وحدة القياس: users
أحداث نموذجية:
{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}
النتيجة: 23 مستخدم متزامن ذروة مفروض على العميل

​
أمثلة تصفية الأحداث

احتساب استدعاءات API فقط لنقاط نهاية محددة:تكوين التصفية:
  • الخاصية: endpoint
  • المقارن: equals
  • القيمة: /v1/orders
حدث نموذجي:
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
النتيجة: سيتم احتساب الأحداث التي تتطابق مع معايير التصفية. سيتم تجاهل الأحداث ذات نقاط نهاية مختلفة.

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

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

​
المشكلات الشائعة

تندرج معظم مشاكل الفوترة المعتمدة على الاستخدام ضمن هذه الفئات:
  • مشكلات تسليم ومعالجة الأحداث
  • مشاكل تكوين العداد
  • أخطاء نوع البيانات والتنسيق
  • مشكلات معرف العميل والمصادقة

​
خطوات تصحيح الأخطاء

عند استكشاف الأخطاء وإصلاحها في الفوترة المعتمدة على الاستخدام:
  1. تحقق من تسليم الأحداث في علامة التبويب تحليلات الأحداث
  2. تحقق من تطابق تكوين العداد مع هيكل الحدث الخاص بك
  3. تحقق من معرفات العملاء ومصادقة واجهة برمجة التطبيقات
  4. راجع شروط التصفية وإعدادات التجميع

​
الحلول والإصلاحات

الأسباب الشائعة:
  • اسم الحدث لا يتطابق تمامًا مع تكوين العداد
  • شروط تصفية الأحداث تستبعد أحداثك
  • معرف العميل غير موجود في حساب مدفوعات دودو الخاص بك
  • تاريخ ووقت الحدث خارج فترة الفوترة الحالية
الحلول:
  • تحقق من تهجئة اسم الحدث وحساسية الحالة
  • راجع واختبر شروط التصفية الخاصة بك
  • تأكد من أن معرف العميل صالح ونشط
  • تحقق من أن تواريخ وأوقات الأحداث حديثة ومهيكلة بشكل صحيح
الأسباب الشائعة:
  • اسم الخاصية على لا يتطابق مع مفاتيح بيانات الحدث
  • قيم البيانات الوصفية هي نوع بيانات خاطئ (سلسلة مقابل عدد)
  • خصائص البيانات الوصفية المطلوبة مفقودة
الحلول:
  • تأكد من أن مفاتيح البيانات الوصفية تتطابق تمامًا مع إعداد الخاصية الخاصة بك
  • تحويل الأرقام السلسلية إلى أرقام فعلية في أحداثك
  • تضمين جميع الخصائص المطلوبة في كل حدث
الأسباب الشائعة:
  • أسماء خصائص التصفية لا تتطابق مع بيانات الحدث
  • المقارن الخاطئ لنوع البيانات (سلسلة مقابل عدد)
  • حساسية الحالة في مقارنات السلاسل
الحلول:
  • تحقق من أن أسماء الخصائص تتطابق تمامًا
  • استخدم المقارنات المناسبة لأنواع البيانات الخاصة بك
  • ضع في اعتبارك حساسية الحالة عند تصفية السلاسل