تتبع الأحداث

الأحداث هي المادة الخام لكل شيء في Joryio: الشرائح ومشغلات الرحلات وفلاتر الحملات والتحليلات كلها تعمل على الأحداث التي ترسلها تطبيقاتك. يغطي هذا الدليل الاصطلاحات والآليات المشتركة بين كل SDKs: الويب وiOS وAndroid وReact Native. للتثبيت والإعداد الخاص بكل منصة، راجع صفحات SDK الفردية.

كيفية عمل التتبع

تتبع كل SDK المسار نفسه:

تستدعي track(eventName, properties) في تطبيقك.
تضع SDK الحدث محليًا في طابور (مع استمرار العمل دون اتصال) وترسله على دفعات، افتراضيًا كل 5 ثوانٍ أو كل 50 حدثًا، أيهما أولًا.
تُسلّم الدفعة إلى POST /v1/track/batch، بمصادقة مفتاح SDK لتطبيقك (التنسيق jry_sdk_<platform>_<random>، واحد لكل تطبيق؛ راجع نظرة عامة على التطبيقات).
يحل الخادم المستخدم (مجهولًا أو معرّفًا) ويخزن الأحداث ويوزعها إلى الشرائح ومشغلات الرحلات والتحليلات.

يمكن أن تحتوي الدفعة على 500 حدث على الأكثر. تضبط SDK الطوابع الزمنية عند وقت الاستدعاء؛ ويقبل الخادم ميلي ثانية epoch أو سلاسل ISO-8601 ويعود إلى وقت الخادم إذا كان الطابع الزمني مفقودًا أو غير صالح، فلا تؤدي ساعة جهاز خاطئة إلى رفض حدث.

اصطلاحات تسمية الأحداث

اسم الحدث سلسلة تصل إلى 255 حرفًا. لا تفرض Joryio تنسيقًا بعد ذلك، لكن الاتساق مهم لأن أسماء الأحداث هي كيفية العثور عليها لاحقًا في منشئي الشرائح ومشغلات الرحلات ومستكشف الأحداث.

توصيات:

استخدم Title Case مع مسافات. تتبع أحداث Joryio المدمجة تصنيف أحداث التجارة الإلكترونية المعياري في المجال (الكائن + فعل بالماضي، Title Case): Product Viewed وProduct Added وCheckout Started وOrder Completed من تكاملات المتاجر، لذلك تبقي الأحداث المخصصة بـ Title Case مثل Trial Started وSignup Completed الكتالوج موحدًا. تعمل snake case أيضًا، لكن اختر اصطلاحًا واحدًا والتزم به؛ فالمزج ينشئ أحداثًا تبدو مكررة.
سمّ الفعل لا واجهة المستخدم. يبقى Order Completed صالحًا بعد إعادة تصميم؛ أما Green Button Clicked فلا.
استخدم الكائن + فعلًا بالماضي. مثل Subscription Upgraded وVideo Played وSearch Performed.
أبقِ التغير في الخصائص لا الأسماء. حدث Product Viewed واحد له خاصية category أفضل من خمسين حدث Viewed <Category>؛ تطابق الشرائح والمشغلات اسم الحدث أولًا ثم تصفي الخصائص.
تجنب الأحداث العامة جدًا. لا يخبرك Clicked بلا خصائص بشيء يمكنك التصرف بناءً عليه.

أسماء الأحداث حساسة لحالة الأحرف: order_placed وOrder_Placed حدثان مختلفان.

الخصائص وأنواع البيانات

الخصائص كائن JSON ملحق بكل حدث. تُقبل أي قيمة JSON:

النوع	المثال	الملاحظات
سلسلة	`"currency": "USD"`	استخدمه أيضًا للتواريخ كسلاسل ISO-8601
رقم	`"total": 149.99`	أعداد صحيحة وعشرية
Boolean	`"first_order": true`
مصفوفة	`"item_ids": ["SKU-1", "SKU-2"]`
كائن	`"shipping": { "method": "express" }`	الكائنات المتداخلة مسموحة

حدود الخادم لكل حدث:

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

تُرفض الأحداث التي تتجاوز هذه الحدود. تتبع أسماء الخصائص النصيحة نفسها لأسماء الأحداث: اختر اصطلاحًا (product_id، لا productId أحيانًا) وحافظ على ثبات الأنواع؛ فـ order_id الذي يكون سلسلة في حدث ورقمًا في آخر يجعل التصفية غير موثوقة.

تُضاف الخصائص التي تبدأ بـ $، مثل $platform و$session_id و$app_id، تلقائيًا: بعضها من SDKs ($device_id وبيانات الجهاز في Session Start) وبعضها من مسار إدخال Joryio عند استقبال الحدث ($app_id و$session_id و$is_identified). عامل هذه البادئة كمحجوزة ولا تستخدمها لخصائصك.

قواعد تسمية مفاتيح سمات المستخدم

لمفاتيح السمات (الكائن الذي تمرّره إلى setAttributes / setAttribute) قيدان إضافيان، والمفتاح الذي يخالف أيًا منهما يُسقَط - وتُحفظ بقية الاستدعاء كالمعتاد:

غير مسموح	السبب
`.` في أي موضع من المفتاح	النقطة تُقرأ كفاصل مسار لا كحرف. فـ `"profile.email"` سيُخزَّن متداخلًا `profile: { email }`، ولن يطابق أي شريحة.
`$` في البداية	محجوز، تمامًا كخصائص الأحداث أعلاه.
مفتاح فارغ	لا شيء لتخزينه.

تُسقَط المفاتيح ولا يُعاد تسميتها عمدًا: إعادة التسمية ستُبلغ عن نجاح بينما تضع بياناتك في مكان لا تستعلم عنه أبدًا.

identify مقابل track

يقوم الاستدعاءان الأساسيان بمهام مختلفة:

identify(userId) يقول من هو المستخدم. يربط الجهاز/الجلسة الحاليين بمعرّف المستخدم الثابت لديك ويدمج أي سجل مجهول في ذلك الملف. تصف السمات المضبوطة بـ setAttributes المستخدم (Email والخطة والاسم) وتعيش في الملف الشخصي.
track(eventName, properties) يقول ما الذي حدث. تصف الخصائص الحدث لا المستخدم، ولا تتغير بعد تسجيله.

قواعد عملية:

استدعِ identify بمجرد معرفتك المستخدم، عند الدخول وعند بدء التطبيق إذا استعيدت جلسة. استخدم معرّف المستخدم نفسه في كل منصة حتى يصل نشاط الويب والهاتف إلى ملف واحد (راجع التتبع متعدد المنصات).
قبل identify، تُتبع الأحداث بمعرّف مجهول. عند التعريف لاحقًا، يدمج الخادم السجل المجهول في الملف المعرّف، فلا تضيع أحداث ما قبل التسجيل (الزيارة الأولى والإسناد).
استخدم alias(userId) عند التسجيل لربط المستخدم المجهول صراحة بالحساب الجديد، ثم identify(userId).
ضع بيانات كل حدوث في خصائص الحدث (total وcoupon) والحقائق الدائمة عن الشخص في السمات (plan وlifetime_value).
استدعِ reset() عند تسجيل الخروج حتى لا يرث المستخدم التالي على الجهاز الملف الشخصي.

الحدث نفسه في كل SDK

استدعاء track متعمد أن يكون بالشكل نفسه في SDKs. إليك حدث Order Completed نفسه على المنصات الأربع.

Web (JS)
iOS (Swift)
Android (Kotlin)
React Native

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

const joryio = new JoryioSDK({ sdkKey: 'jry_sdk_web_...' });

joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

Joryio.shared.track("Order Completed", properties: [
    "order_id": "ORD-2024-001",
    "total": 149.99,
    "currency": "USD",
    "item_count": 3,
    "coupon": "SAVE10"
])

Joryio.track("Order Completed", mapOf(
    "order_id" to "ORD-2024-001",
    "total" to 149.99,
    "currency" to "USD",
    "item_count" to 3,
    "coupon" to "SAVE10"
))

import Joryio from '@joryio/react-native-sdk';

Joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

لأن الاسم والخصائص متطابقان، يطابق شرط شريحة أو مشغّل رحلة واحد الحدث مهما كانت المنصة التي أتى منها.

لنشاط التجارة الإلكترونية القياسي (مشاهدات المنتجات والسلات وإتمام الشراء والطلبات)، فضّل متتبعات التجارة الإلكترونية المدمجة في SDKs؛ فهي تصدر أسماء الأحداث المعيارية التي تتوقعها ميزات التجارة الإلكترونية في Joryio. راجع دليل تتبع التجارة الإلكترونية عبر SDKs.

ما يحدث على الخادم

بعد قبول دفعة، فإن كل حدث:

يُخزن في مخزن التحليلات، ملحقًا بملف المستخدم المحلول (معرّف أو مجهول).
يُقيّم مقابل مشغلات الرحلات. تسجل الرحلة التي يطابق مشغّل دخولها اسم الحدث (وفلاتر الخصائص) المستخدم فورًا؛ وهكذا تبدأ رحلات «السلة المتروكة» أو «الترحيب».
يغذي الشرائح. تتحدث شروط الشرائح القائمة على الأحداث («نفذ Order Completed في آخر 30 يومًا») من تدفق الأحداث، وتلتقط الحملات التي تستهدف تلك الشرائح التغيير.
يظهر في التحليلات: مستكشف الأحداث والمسارات وتحليلات كل تطبيق.
يمكن أن يحدّث الملف الشخصي. بعض الأحداث لها آثار جانبية يديرها الخادم؛ مثلًا، تحدّث أحداث Session Start سجل جهاز المستخدم وتضبط سمات الملف مثل country (المشتق من IP الطلب).

سلوكان للخادم يجدر معرفتهما:

تعليم الروبوتات. تُعلّم الطلبات من وكلاء مستخدم روبوت معروفين (تُوسم الأحداث وتستبعدها التحليلات)؛ وتتخطى استدعاءات تغيير الملف مثل identify وsetAttributes للروبوتات. لذلك قد لا تنشئ الزيارات من متصفحات عديمة الرأس في أتمتة اختباراتك ملفات شخصية.
تحقق مرن. تُزال الحقول الإضافية غير المعروفة من الحمولة بدل رفضها، فلا يسقط عدم تطابق إصدار SDK أحداثك.

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

تحقق من وصول حدث

شغّل الحدث في تطبيقك.
في لوحة تحكم Joryio، افتح التحليلات → مستكشف الأحداث. صفِّ باسم الحدث وستراه خلال ثوانٍ من دفع SDK للدفعة (فاصل الدفع الافتراضي: 5 ثوانٍ).
لعرض كل تطبيق، افتح الإعدادات → التطبيقات وانقر عرض التحليلات في التطبيق؛ يعرض إجمالي الأحداث وطابع آخر حدث وأسماء أعلى الأحداث، ما يؤكد بسرعة ما إذا كان أي شيء من مفتاح SDK يصل.

إذا لم تظهر الأحداث

افرض الدفع. الأحداث مجمعة؛ استدعِ flush()، المتاح في كل SDK، للإرسال فورًا بدل انتظار المؤقت.
فعّل سجل التصحيح. تملك كل SDK خيار enableDebug يسجل كل حدث في الطابور وكل طلب شبكة مع استجابته.
افحص مفتاح SDK. يجب أن يطابق منصة التطبيق: jry_sdk_web_... لـ Web SDK وjry_sdk_ios_... لـ iOS وjry_sdk_android_... لـ Android. يبطل المفتاح المعاد إنشاؤه المفتاح القديم فورًا.
تحقق من نشاط التطبيق في الإعدادات → التطبيقات؛ تُرفض الأحداث المرسلة بمفتاح تطبيق معطل.
راقب استجابة الشبكة. تتضمن استجابة الدفعة success وعند الفشل الجزئي failedIndices الذي يخبرك أي أحداث الدفعة لم تخزن. الخصائص الكبيرة جدًا (أكثر من 50 KB أو 200 مفتاح أو عمق يزيد عن 5 مستويات) هي السبب المعتاد للأحداث المرفوضة.
الويب فقط: تسمح نقاط نهاية تتبع SDK بأي أصل (Access-Control-Allow-Origin: *)، لذلك تعني أخطاء CORS غالبًا apiEndpoint خاطئًا أو إضافة متصفح حاجبة؛ افحص وحدة التحكم. أكد أيضًا أن الموقع يعمل بـ HTTPS ليستمر طابور localStorage.
تختبر بالأتمتة؟ تذكر تعليم الروبوتات أعلاه؛ تحقق بمتصفح أو جهاز حقيقي.

كيفية عمل التتبع​

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

الخصائص وأنواع البيانات​

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

identify مقابل track​

الحدث نفسه في كل SDK​

ما يحدث على الخادم​

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

تحقق من وصول حدث​

إذا لم تظهر الأحداث​

ذات صلة​