Events API

تتبّع أحداث المستخدم وسلوكه برمجياً عبر REST API.

كل نقاط النهاية في هذه الصفحة نسبية إلى عنوان الأساس: https://api-eu1.joryio.com/api - راجع نظرة عامة على API.

المصادقة

تتطلب جميع الطلبات مصادقة بمفتاح API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

حدث الشراء

تقارير الإيرادات والإسناد وCLV والنماذج التنبؤية جميعها تقرأ حدثًا واحدًا. إذا أرسلت عمليات الشراء باسم مختلف، فلن تُحتسب - في أي مكان.


اسم الحدث	`Order Completed`
الخصائص المطلوبة	`total`, `currency`
موصى بها	`total_base`, `base_currency`, `orderId`

{
  "eventName": "Order Completed",
  "userId": "user_123",
  "properties": {
    "total": 149.90,
    "currency": "EUR",
    "total_base": 162.35,
    "base_currency": "USD",
    "orderId": "1024"
  }
}

لماذا اسم واحد فقط

تستخدم منصات أخرى أسماء أخرى - Placed Order وpurchase (GA4). نحن لا نقبلها عمدًا، لأن قبول عدة أسماء يعني جمعها معًا: متجر يشغّل وسم GA4 إلى جانب موصّلنا سيرسل عملية بيع واحدة باسمين ويرى إيراداته مضاعفة. رقم إيرادات مضاعف بصمت أصعب بكثير في الاكتشاف من رقم يساوي صفرًا بوضوح.

لذلك القاعدة هي عقد واحد منشور. إذا لم تظهر طلباتك، يكون السبب واضحًا فورًا عند الإعداد - وقابلًا للإصلاح - بدلًا من أن يكون خاطئًا بصمت لأشهر.

عن المبالغ

total وtotal_base رقمان مختلفان، وليسا بديلين:

total - ما دفعه العميل، بالعملة التي دفع بها (presentment).
total_base + base_currency - الطلب نفسه محوّلًا إلى عملة تقاريرك. أرسلهما إذا كنت تبيع بأكثر من عملة، لتُجمع الإجماليات عبر العملات بشكل صحيح.

أرسل total وحده إذا كانت لديك عملة واحدة. orderId اختياري لكنه موصى به: فهو يمنع ازدواج طلب يصل أكثر من مرة (إعادة محاولة، تحديث صفحة الدفع).

إذا كنت ترسل بالفعل اسمًا آخر

تُحفظ أحداثك السابقة، لكنها لا تُعامل كطلبات. حوّل الطلبات الجديدة إلى Order Completed، وتبدأ تقارير الإيرادات من تلك النقطة. نحن لا نعيد كتابة الأحداث القديمة، لذا لا يُعاد تفسير أي شيء بصمت من تحتك.

رموز القسائم في الحدث

عندما يأتي الطلب من متجر متصل أو من Orders API، يحمل Order Completed أيضًا:

الخاصية	النوع	الوصف
`coupon_codes`	string[]	كل رموز القسائم في الطلب بأحرف صغيرة (`["summer10", "vip"]`)؛ `[]` عند عدم وجودها
`coupon_count`	number	عدد الرموز المستخدمة في الطلب

يمكن أن تبدأ رحلة عند Order Completed حيث يحتوي coupon_codes على summer10 - تتجاهل المطابقة حالة الأحرف وتفحص كل رمز.

المتجر وقناة البيع في الحدث

تحمل الأحداث Order Completed وOrder Refunded وOrder Cancelled مكان بيع الطلب ومتجره:

الخاصية	النوع	الوصف
`sales_channel`	string	`online` أو `pos` أو `app` أو `phone` أو `marketplace` أو `other` - موجودة دائمًا
`store_id`	string	المتجر الذي ينتمي إليه الطلب (معرّف متجر متصل، أو `storeId` الذي أرسله طلب API لديك) - فقط عند وجوده

يمكن للتطبيق إرسالها في حدث Order Completed الخاص به: sales_channel (يُقبل أيضًا باسم salesChannel؛ وتُحفظ القيمة غير الموجودة في القائمة كـother) وstore_id وstore_name. بدون sales_channel يكون الطلب المسجل من تطبيق iOS أو Android هو app ومن موقع ويب online. يمكن أن تبدأ رحلة عند Order Completed حيث sales_channel هي pos. انظر المتجر وقناة البيع.

إرسال الأحداث

تُستقبل الأحداث عبر POST /users/track، الذي يأخذ السمات والأحداث وعمليات الشراء في استدعاء واحد.

curl -X POST https://api-eu1.joryio.com/api/users/track \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": {
      "externalId": "user_123",
      "name": "Product Viewed",
      "properties": { "productId": "SKU-456", "price": 49.99 }
    }
  }'

يقبل events كائنًا واحدًا أو مصفوفة بحد أقصى 500. راجع Track للمرجع الكامل للحقول وقواعد الهوية وشكل الاستجابة.

Order Completed لا يُرسل كحدث

يُصدر تلقائيًا من عملية شراء. أرسل عمليات الشراء في مصفوفة purchases بدلًا من ذلك - راجع حدث الشراء أعلاه لمعرفة لماذا يؤدي إرساله يدويًا إمّا إلى تسجيل إيراد بلا طلب خلفه، أو إلى احتساب البيع مرتين.

الاستعلام عن الأحداث

استرجع الأحداث بالتصفية والترقيم. لا توجد نقطة نهاية لجلب حدث بمعرّفه - صفِّ هذا الاستعلام بدلًا منها.

نقطة النهاية

GET /events/query

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
`userId`	string	-	تصفية بمعرّف المستخدم
`eventName`	string	-	تصفية باسم الحدث
`startDate`	string	-	تصفية الأحداث بعد هذا التاريخ (ISO 8601)
`endDate`	string	-	تصفية الأحداث قبل هذا التاريخ (ISO 8601)
`limit`	number	100	النتائج في الصفحة (بحد أقصى 1000)
`offset`	number	0	عدد الأحداث التي يجب تجاوزها

مثال لطلب

# Get all "Order Completed" events in January 2024
curl -X GET "https://api-eu1.joryio.com/api/events/query?eventName=Order+Completed&startDate=2024-01-01T00:00:00Z&endDate=2024-02-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer jry_live_your_api_key"

الاستجابة

مصفوفة JSON مجردة، الأحدث أولًا. تستخدم حقول الحدث snake_case (لأنها تأتي من مخزن التحليلات):

[
  {
    "event_id": "9b2f6c1e-4a8d-4f0b-9c3d-2e1f5a6b7c8d",
    "user_id": "665f1e2a9b3c4d5e6f7a8b9c",
    "anonymous_id": "",
    "event_name": "Order Completed",
    "properties": {
      "orderId": "order_456",
      "total": 99.99
    },
    "timestamp": "2024-01-20 14:30:00",
    "session_id": "",
    "device_id": ""
  },
  {
    "event_id": "1c3e5a7b-9d2f-4b6c-8e0a-3f5d7b9c1e2a",
    "user_id": "665f1e2a9b3c4d5e6f7a8b9d",
    "anonymous_id": "",
    "event_name": "Order Completed",
    "properties": {
      "orderId": "order_789",
      "total": 149.99
    },
    "timestamp": "2024-01-19 10:15:00",
    "session_id": "",
    "device_id": ""
  }
]

تجميع الأحداث

احصل على إحصاءات أحداث مجمعة بالتجميع والمقاييس.

نقطة النهاية

POST /events/aggregate

نص الطلب

الحقل	النوع	مطلوب	الوصف
`eventName`	string	نعم	اسم الحدث المراد تجميعه
`startDate`	string	لا	تاريخ البدء (ISO 8601)
`endDate`	string	لا	تاريخ النهاية (ISO 8601)
`groupBy`	string	لا	التجميع الزمني: `hour` أو `day` أو `week` أو `month` (الافتراضي: `day`)
`metrics`	array	لا	المقاييس المراد حسابها: `count` و`sum` و`avg` و`min` و`max` (الافتراضي: `['count']`)
`sumField`	string	مشروط	اسم مفتاح `properties` للجمع أو التجميع (مثل `total`). مطلوب عندما يتضمن `metrics` القيم `sum` أو `min` أو `max`
`avgField`	string	مشروط	اسم مفتاح `properties` لحساب المتوسط. مطلوب عندما يتضمن `metrics` القيمة `avg`

المقياس بدون حقله مرفوض

اسم مقياس غير معروف، أو مقياس يفتقد حقله (sum بدون sumField)، يعيد 400. كان كلاهما يعيد 200 مع غياب المقياس ببساطة من النتيجة، وهو ما لا يمكن تمييزه عن صفر حقيقي.

مثال لطلب

curl -X POST https://api-eu1.joryio.com/api/events/aggregate \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "Order Completed",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-02-01T00:00:00Z",
    "groupBy": "day",
    "metrics": ["count", "sum"],
    "sumField": "total"
  }'

الاستجابة

{
  "success": true,
  "data": {
    "eventName": "Order Completed",
    "groupBy": "day",
    "metrics": ["count", "sum"],
    "results": [
      {
        "period": "2024-01-01T00:00:00Z",
        "count": 45,
        "sum_value": 4567.89
      },
      {
        "period": "2024-01-02T00:00:00Z",
        "count": 52,
        "sum_value": 5123.45
      },
      {
        "period": "2024-01-03T00:00:00Z",
        "count": 38,
        "sum_value": 3890.12
      }
    ],
    "total": 3
  }
}

المقاييس المدعومة

count: العدد الإجمالي للأحداث
sum: مجموع قيم الحقل المحدد
avg: متوسط قيم الحقل المحدد
min: أدنى قيمة للحقل المحدد
max: أعلى قيمة للحقل المحدد

مثال: تحليل الإيرادات

# Get daily revenue from purchases
curl -X POST https://api-eu1.joryio.com/api/events/aggregate \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "Order Completed",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T00:00:00Z",
    "groupBy": "day",
    "metrics": ["count", "sum", "avg"],
    "sumField": "total"
  }'

مثال: استخدام ميزة بحسب الساعة

# Track feature usage patterns by hour
curl -X POST https://api-eu1.joryio.com/api/events/aggregate \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "Feature Used",
    "startDate": "2024-01-20T00:00:00Z",
    "endDate": "2024-01-21T00:00:00Z",
    "groupBy": "hour",
    "metrics": ["count"]
  }'

اكتشاف ما ترسله مساحة العمل

قبل أن تبني على أحداث مساحة عمل، اسألها عمّا تتلقاه فعلًا. هذه المسارات الأربعة هي الطريقة التي يعرف بها التكامل بدل أن يخمّن.

قائمة أسماء الأحداث

GET /events/names

كل اسم حدث ظهر في مساحة العمل هذه، كمصفوفة JSON مجردة مرتبة أبجديًا. هذه هي المفردات الحقيقية، لا التي قصدها أحدهم.

الاستجابة:

["Order Completed", "Page Viewed", "Product Viewed"]

إحصاءات الأحداث

GET /events/stats?startDate=2026-08-20T00:00:00Z&endDate=2026-08-27T00:00:00Z

الحجم لكل حدث خلال نافذة زمنية - أسرع طريقة للتأكد من أن التكامل ما زال يرسل البيانات، ولملاحظة توقف أحدها بصمت. startDate وendDate طابعان زمنيان اختياريان بصيغة ISO 8601 (لا يوجد معامل days)؛ وبدونهما يُحسب التاريخ كله.

الاستجابة - مصفوفة JSON، الأحداث الأكثر ازدحامًا أولًا، بحد أقصى 1,000 صف. count هو عدد الأحداث المميزة، وunique_users عدد الأشخاص المميزين:

[
  { "event_name": "Page Viewed", "count": 1204331, "unique_users": 88012 },
  { "event_name": "Order Completed", "count": 48210, "unique_users": 31877 }
]

مخططات الأحداث

GET /events/schema?limit=50&offset=0
GET /events/schema/Order%20Completed

يصفّح مسار القائمة كل حدث تلقته مساحة العمل (limit افتراضيه 50 وأقصاه 1000؛ وoffset افتراضيه 0) مع الأعداد ومن دون الخصائص. أما مسار الحدث الواحد فيأخذ اسم الحدث في المسار، مرمَّزًا بترميز URL - لا يوجد معامل استعلام ?event= - ويعيد الخصائص التي رُصدت عليه فعلًا: النوع الذي استقرت عليه كل خاصية ومن أين جاء (typeSource إما declared أو canonical أو inferred)، وفي كم حدث تظهر (occurrences)، وقيمًا نموذجية، وما إذا كانت القيم تبدو كمعرّف. لا يوجد حقل fillRate - اقسم occurrences على totalCount الخاص بالحدث من مسار القائمة. الخاصية المعلنة التي لا تُرسل أبدًا هي السبب المعتاد لشريحة لا تطابق أحدًا.

استجابة القائمة:

{
  "data": [
    { "name": "Order Completed", "totalCount": 48210, "uniqueUsers": 31877,
      "lastSeen": "2026-08-27T09:12:00.000Z", "propertyCount": 6,
      "description": "A purchase was completed", "descriptionSource": "platform", "isPlatform": true }
  ],
  "pagination": { "total": 42, "limit": 50, "offset": 0, "hasMore": false }
}

استجابة الحدث الواحد:

{
  "eventName": "Order Completed",
  "properties": [
    { "name": "total", "type": "number", "typeSource": "canonical", "typeDeclared": false,
      "typeMixed": false, "typeCounts": { "string": 0, "number": 48210, "boolean": 0, "array": 0, "object": 0 },
      "typeReason": "single", "occurrences": 48210, "exampleValues": [129.9, 42.5],
      "cardinalityVerdict": "high_cardinality", "uniquenessRatio": 0.31, "looksLikeIdentifier": false,
      "pii": false },
    { "name": "coupon", "type": "string", "typeSource": "inferred",
      "typeMixed": false, "typeCounts": { "string": 3857, "number": 0, "boolean": 0, "array": 0, "object": 0 },
      "typeReason": "single", "occurrences": 3857, "exampleValues": ["SPRING10"],
      "cardinalityVerdict": "low_cardinality", "uniquenessRatio": 0.004, "looksLikeIdentifier": false,
      "pii": false }
  ]
}

يكون exampleValues فارغًا لخاصية PII عندما لا يُسمح للمستدعي بعرض PII (pii يبيّن أيها). ويشير typeMixed مع typeCounts إلى خاصية تصل قيمها بأكثر من نوع واحد.

إعلان مخطط حدث

POST /events/schema

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

جسم الطلب:

{ "name": "Order Completed", "description": "A purchase was completed" }

الاستجابة:

{ "success": true, "message": "Event schema defined successfully",
  "data": { "name": "Order Completed", "description": "A purchase was completed" } }

تُكتب أوصاف الخصائص عبر PUT /events/schema/:eventName ({ "description"?, "properties"?: [{ "name", "description" }] }). أما POST /events/schema/:eventName/properties ({ "name", "type", "description"? }) فيُعلن نوع الخاصية - string أو number أو boolean أو date - في قاموس البيانات نفسه؛ ثم يبلّغ عنه مسار الحدث الواحد بـ typeSource: "declared" وتقارن به مرشحات الشرائح. يُرفض النوع غير المعروف، وكذلك الخاصية القياسية التي تحدد المنصة نوعها (total وprice...)، بالرمز 400.

كتالوج أحداث المنصة

GET /events/platform-catalog

الأحداث القياسية التي يفهمها Joryio أصلًا، مع الخصائص التي يتوقعها كل منها. طابق هذه الأسماء فتعمل التقارير والمشغّلات وميزات التجارة الإلكترونية المدمجة دون أي تخطيط؛ استخدم أسماءك الخاصة فلن تعمل.

أحداث شائعة

أحداث التجارة الإلكترونية

// Product Viewed
POST /users/track
{
  "userId": "user_123",
  "eventName": "Product Viewed",
  "properties": {
    "productId": "prod_456",
    "productName": "Premium Plan",
    "category": "Subscription",
    "price": 99.99,
    "currency": "USD"
  }
}

// Added To Cart
POST /users/track
{
  "userId": "user_123",
  "eventName": "Added To Cart",
  "properties": {
    "productId": "prod_456",
    "quantity": 1,
    "price": 99.99
  }
}

// Order Completed
POST /users/track
{
  "userId": "user_123",
  "eventName": "Order Completed",
  "properties": {
    "orderId": "order_789",
    "total": 249.99,
    "currency": "USD",
    "itemCount": 3,
    "discount": 25.00,
    "paymentMethod": "credit_card"
  }
}

أحداث دورة حياة المستخدم

// Signup Completed
POST /users/track
{
  "userId": "user_123",
  "eventName": "Signup Completed",
  "properties": {
    "method": "email",
    "source": "homepage_cta"
  }
}

// Onboarding Completed
POST /users/track
{
  "userId": "user_123",
  "eventName": "Onboarding Completed",
  "properties": {
    "stepsCompleted": 5,
    "timeSpent": "8m 30s"
  }
}

// Trial Started
POST /users/track
{
  "userId": "user_123",
  "eventName": "Trial Started",
  "properties": {
    "plan": "premium",
    "trialDays": 14
  }
}

أحداث التفاعل

// Feature Used
POST /users/track
{
  "userId": "user_123",
  "eventName": "Feature Used",
  "properties": {
    "featureName": "export",
    "exportFormat": "csv",
    "recordCount": 1500
  }
}

// Page Viewed
POST /users/track
{
  "userId": "user_123",
  "eventName": "Page Viewed",
  "properties": {
    "page": "/pricing",
    "category": "Marketing",
    "referrer": "google"
  }
}

خصائص الحدث

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

استخدم أسماء خصائص وصفية:

جيد:

{
  "properties": {
    "productId": "prod_123",
    "productName": "Premium Plan",
    "price": 99.99,
    "currency": "USD"
  }
}

غير جيد:

{
  "properties": {
    "pid": "prod_123",
    "n": "Premium Plan",
    "p": 99.99
  }
}

أنواع البيانات المدعومة

{
  "properties": {
    "string": "value",
    "number": 99.99,
    "integer": 5,
    "boolean": true,
    "date": "2024-01-15T10:30:00Z",
    "array": ["tag1", "tag2"],
    "object": {
      "nested": "value",
      "deep": {
        "property": "value"
      }
    }
  }
}

الخصائص المحجوزة

الخصائص التي تبدأ بـ $ محجوزة لاستخدام النظام:

$app_id - معرّف التطبيق
$app_name - اسم التطبيق
$platform - المنصة (web أو ios أو android)
$session_id - معرّف الجلسة
$anonymous_id - معرّف المستخدم المجهول

لا تستخدم هذه الأسماء لخصائص مخصصة.

أسماء الأحداث المحجوزة

أسماء الأحداث التي تبدأ بـ canvas. محجوزة لأحداث رحلات Joryio - لا يسجّل canvas.step.entered وcanvas.step.left وcanvas.experiment.entered وأي اسم آخر يبدأ بـ canvas. إلا محرك الرحلات (أحداث المنصة). يُرفض أي حدث ترسله باسم يبدأ بـ canvas. (غيّر اسمه) - يُدرج الحدث كفاشل مع السبب في استجابة POST /users/track، ورفض دائم (rejectedIndices) في دفعة SDK، وصف يتم تخطيه مع السبب في استيراد CSV أو مزامنة مستودع البيانات. كما تُزال الخاصية $emitted_by من كل حدث ترسله.

الأسماء التي تبدأ بـ message. أو in_app. محجوزة بالطريقة نفسها لأحداث الرسائل في Joryio - لا يسجّل الإرسال والتسليم والفتح والنقر (message.sent وmessage.opened وmessage.clicked، ...) وعرض رسائل in-app والنقر عليها وإغلاقها (in_app.displayed وin_app.clicked، ...) إلا Joryio، حتى لا يُحتسب حدث مخصص أبدًا كواحد منها في التقارير أو فلاتر الشرائح أو مشغّلات الرحلات. يُرفض أي حدث ترسله بمثل هذا الاسم بالطريقة نفسها، بما في ذلك الصفوف في استيراد CSV تاريخي أو مزامنة مستودع البيانات - غيّر اسمه (مثلًا Newsletter Opened). يتجاهل الفحص حالة الأحرف. إيصالات التسليم ونقرات Push التي تبلّغ عنها حزم SDK، وأحداث in-app المُبلّغ عنها عبر نقاط نهاية in-app في حزم SDK، هي أحداث Joryio نفسها وتستمر في العمل.

حدود الأحداث

حدود الحجم

الحد	القيمة
أقصى طول لاسم الحدث	255 حرفًا
أقصى طول للمعرّف (userId وanonymousId وsessionId وdeviceId وclientEventId)	255 حرفًا
أقصى عدد لمفاتيح الخصائص العليا لكل حدث	200
أقصى حجم للخصائص (JSON)	50 KB
أقصى عمق لتداخل الخصائص	5 مستويات
أقصى عدد للأحداث في طلب بنص مصفوفة	500

حدود المعدل

لا تملك Events API اليوم حدود معدل ثابتة لكل نقطة نهاية - راجع نظرة عامة على API: حدود المعدل.

استجابات الأخطاء

تستخدم كل الأخطاء نص الخطأ القياسي - راجع نظرة عامة على API: استجابة الخطأ.

400 طلب غير صالح - فشل التحقق

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/api/users/track",
  "errors": [
    "eventName should not be empty"
  ]
}

400 طلب غير صالح - خصائص ضخمة

{
  "statusCode": 400,
  "message": "Event properties exceed maximum size of 50KB (received 63KB)",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/api/users/track"
}

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

1. اجمع الأحداث على دفعات عند الإمكان

جيد - أرسل أحداثًا متعددة بنص مصفوفة:

await fetch('/api/users/track', {
  method: 'POST',
  body: JSON.stringify([event1, event2, event3])
});

غير جيد - طلبات منفردة:

await fetch('/api/users/track', { method: 'POST', body: JSON.stringify(event1) });
await fetch('/api/users/track', { method: 'POST', body: JSON.stringify(event2) });
await fetch('/api/users/track', { method: 'POST', body: JSON.stringify(event3) });

2. استخدم تسمية أحداث متسقة

اتبع نمط «كائن + فعل بصيغة الماضي»:

جيد: Product Viewed وOrder Completed وTrial Started غير جيد: view_product وclicked وuser_action_123

3. ضمّن الطوابع الزمنية

للأحداث التاريخية، ضمّن دائمًا طوابع زمنية دقيقة:

{
  "userId": "user_123",
  "eventName": "Order Completed",
  "timestamp": "2024-01-15T10:30:00.000Z", // Actual event time
  "properties": { ... }
}

4. أبقِ الخصائص مختصرة

ضمّن الخصائص ذات الصلة فقط:

جيد:

{
  "eventName": "Order Completed",
  "properties": {
    "orderId": "order_123",
    "total": 99.99,
    "currency": "USD"
  }
}

غير جيد:

{
  "eventName": "Order Completed",
  "properties": {
    "orderId": "order_123",
    "total": 99.99,
    "currency": "USD",
    "userAgent": "Mozilla/5.0...", // Too much detail
    "sessionData": { /* large object */ },
    "cookies": [ /* array of cookies */ ]
  }
}

5. تعامل مع الأخطاء بأمان

نفّذ منطق إعادة المحاولة بتراجع أسي:

async function trackWithRetry(event, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('/api/users/track', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(event)
      });

      if (response.ok) return await response.json();

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
        await sleep(retryAfter * 1000);
        continue;
      }

      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000); // 1s, 2s, 4s
    }
  }
}

التصحيح

تفعيل وضع التصحيح (SDK)

عند استخدام Web SDK:

import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  enableDebug: true // Log all events to console
});

التحقق من الأحداث في لوحة التحكم

انتقل إلى المستخدمون ← ابحث عن المستخدم
انقر تبويب النشاط
راجع جميع الأحداث المتتبعة

مشاكل شائعة

الأحداث لا تظهر:

تحقق من صحة مفتاح API
تحقق من أن المستخدم معرّف
تأكد من صحة اسم الحدث وخصائصه
تحقق من حدود المعدل

الخصائص لا تظهر:

تحقق من صحة أسماء الخصائص
تحقق من أن أنواع البيانات مدعومة
تجنب أسماء الخصائص المحجوزة (البادئة $)

SDKs

للتكامل الأسهل، استخدم SDKs الرسمية:

Web SDK: دليل التكامل
iOS SDK: Swift Package / CocoaPods
Android SDK: Gradle
React Native SDK: npm install @joryio/react-native-sdk

المصادقة​

حدث الشراء​

لماذا اسم واحد فقط​

عن المبالغ​

إذا كنت ترسل بالفعل اسمًا آخر​

رموز القسائم في الحدث​

المتجر وقناة البيع في الحدث​

إرسال الأحداث​

الاستعلام عن الأحداث​

نقطة النهاية​

معاملات الاستعلام​

مثال لطلب​

الاستجابة​

تجميع الأحداث​

نقطة النهاية​

نص الطلب​

مثال لطلب​

الاستجابة​

المقاييس المدعومة​

مثال: تحليل الإيرادات​

مثال: استخدام ميزة بحسب الساعة​

اكتشاف ما ترسله مساحة العمل​

قائمة أسماء الأحداث​

إحصاءات الأحداث​

مخططات الأحداث​

إعلان مخطط حدث​

كتالوج أحداث المنصة​

أحداث شائعة​

أحداث التجارة الإلكترونية​

أحداث دورة حياة المستخدم​

أحداث التفاعل​

خصائص الحدث​

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

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

الخصائص المحجوزة​

أسماء الأحداث المحجوزة​

حدود الأحداث​

حدود الحجم​

حدود المعدل​

استجابات الأخطاء​

400 طلب غير صالح - فشل التحقق​

400 طلب غير صالح - خصائص ضخمة​

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

1. اجمع الأحداث على دفعات عند الإمكان​

2. استخدم تسمية أحداث متسقة​

3. ضمّن الطوابع الزمنية​

4. أبقِ الخصائص مختصرة​

5. تعامل مع الأخطاء بأمان​

التصحيح​

تفعيل وضع التصحيح (SDK)​

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

مشاكل شائعة​

SDKs​

الخطوات التالية​

المصادقة

حدث الشراء

لماذا اسم واحد فقط

عن المبالغ

إذا كنت ترسل بالفعل اسمًا آخر

رموز القسائم في الحدث

المتجر وقناة البيع في الحدث

إرسال الأحداث

الاستعلام عن الأحداث

نقطة النهاية

معاملات الاستعلام

مثال لطلب

الاستجابة

تجميع الأحداث

نقطة النهاية

نص الطلب

مثال لطلب

الاستجابة

المقاييس المدعومة

مثال: تحليل الإيرادات

مثال: استخدام ميزة بحسب الساعة

اكتشاف ما ترسله مساحة العمل

قائمة أسماء الأحداث

إحصاءات الأحداث

مخططات الأحداث

إعلان مخطط حدث

كتالوج أحداث المنصة

أحداث شائعة

أحداث التجارة الإلكترونية

أحداث دورة حياة المستخدم

أحداث التفاعل

خصائص الحدث

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

أنواع البيانات المدعومة

الخصائص المحجوزة

أسماء الأحداث المحجوزة

حدود الأحداث

حدود الحجم

حدود المعدل

استجابات الأخطاء

400 طلب غير صالح - فشل التحقق

400 طلب غير صالح - خصائص ضخمة

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

1. اجمع الأحداث على دفعات عند الإمكان

2. استخدم تسمية أحداث متسقة

3. ضمّن الطوابع الزمنية

4. أبقِ الخصائص مختصرة

5. تعامل مع الأخطاء بأمان

التصحيح

تفعيل وضع التصحيح (SDK)

التحقق من الأحداث في لوحة التحكم

مشاكل شائعة

SDKs

الخطوات التالية