الأحداث المخصصة

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

ما هي الأحداث؟

الأحداث سجلات مؤرخة لإجراءات المستخدم:

{
  "userId": "user_123",
  "eventName": "Order Completed",
  "timestamp": "2024-01-20T14:30:00Z",
  "properties": {
    "orderId": "order_456",
    "total": 99.99,
    "currency": "USD",
    "items": 3,
    "paymentMethod": "credit_card"
  }
}

تتبع الأحداث

عبر SDK، من جانب العميل

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

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

// Simple event
joryio.track('Button Clicked');

// Event with properties
joryio.track('Order Completed', {
  orderId: 'order_456',
  total: 99.99,
  currency: 'USD',
  items: 3
});

// Page view
joryio.track('Page Viewed', {
  page: '/pricing',
  category: 'Marketing',
  title: 'Pricing Page'
});

عبر API، من جانب الخادم

fetch('https://api-eu1.joryio.com/api/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer jry_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user_123',
    eventName: 'Order Completed',
    properties: {
      orderId: 'order_456',
      total: 99.99,
      currency: 'USD'
    }
  })
});

التتبع على دفعات

يجمع SDK الأحداث تلقائياً لتحسين الأداء. توضع الأحداث في قائمة انتظار وتُرسل ضمن مجموعات:

// SDK automatically batches these events
joryio.track('Product Viewed', { productId: '123' });
joryio.track('Added To Cart', { productId: '123', price: 49.99 });
joryio.track('Cart Viewed', { itemCount: 1 });

// Events are sent together after 10 seconds or 20 events (configurable)

// To send immediately:
joryio.flush();

// API: POST /users/track - `events` accepts one object or an array (max 500)
POST /users/track
{
  "events": [
    {
      "externalId": "user_123",
      "name": "Product Viewed",
      "properties": { "productId": "123" }
    },
    {
      "externalId": "user_123",
      "name": "Added To Cart",
      "properties": { "productId": "123", "price": 49.99 }
    }
  ]
}

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

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

استخدم أسماء واضحة ومتسقة.

جيد، كائن + إجراء:

joryio.track('Product Viewed');
joryio.track('Cart Abandoned');
joryio.track('Order Completed');
joryio.track('Trial Started');

غير جيد:

joryio.track('view_product');      // Inconsistent case
joryio.track('clicked');           // Too generic
joryio.track('user_action_123');   // Not descriptive

اصطلاح التسمية

نوصي بالصيغة: الكائن + فعل بصيغة الماضي.

Product Viewed
Order Completed
Account Created
Feature Enabled
Video Watched
Form Submitted

خصائص الحدث

توفر الخصائص سياقاً للحدث.

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

// Product Viewed
joryio.track('Product Viewed', {
  productId: 'prod_123',
  productName: 'Premium Plan',
  category: 'Subscription',
  price: 99.99,
  currency: 'USD',
  inStock: true
});

// Order Completed
joryio.track('Order Completed', {
  orderId: 'order_456',
  total: 249.99,
  currency: 'USD',
  itemCount: 3,
  discount: 25.00,
  shippingCost: 10.00,
  paymentMethod: 'credit_card',
  products: [
    { id: 'prod_1', name: 'Item 1', price: 99.99 },
    { id: 'prod_2', name: 'Item 2', price: 149.99 }
  ]
});

// Cart Abandoned
joryio.track('Cart Abandoned', {
  cartValue: 149.99,
  itemCount: 2,
  cartAge: '2h 30m'
});

أحداث SaaS

// Trial Started
joryio.track('Trial Started', {
  plan: 'premium',
  trialDays: 14,
  source: 'pricing_page'
});

// Feature Used
joryio.track('Feature Used', {
  featureName: 'export',
  exportFormat: 'csv',
  recordCount: 1500,
  duration: 3.5 // seconds
});

// Subscription Upgraded
joryio.track('Subscription Upgraded', {
  fromPlan: 'starter',
  toPlan: 'professional',
  billingCycle: 'monthly',
  mrr: 199,
  effectiveDate: '2024-02-01'
});

أحداث المحتوى والوسائط

// Video Watched
joryio.track('Video Watched', {
  videoId: 'vid_123',
  videoTitle: 'Product Demo',
  duration: 120, // seconds
  percentWatched: 85,
  quality: '1080p',
  platform: 'web'
});

// Article Read
joryio.track('Article Read', {
  articleId: 'article_456',
  title: '10 Tips for Better Marketing',
  category: 'Marketing',
  author: 'John Doe',
  readTime: 5, // minutes
  scrollDepth: 90
});

أمثلة لأحداث شائعة

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

// Signup flow
joryio.track('Signup Started');
joryio.track('Signup Completed', {
  method: 'email',
  source: 'homepage_cta'
});
joryio.track('Email Verified');
joryio.track('Onboarding Completed', {
  stepsCompleted: 5,
  timeSpent: '8m 30s'
});

// Engagement
joryio.track('Session Started');
joryio.track('Feature Discovered', {
  featureName: 'advanced_filters'
});
joryio.track('Help Article Viewed', {
  articleId: 'help_123',
  query: 'how to export data'
});
joryio.track('Session Ended', {
  duration: '15m 20s',
  pagesViewed: 8
});

مسار التجارة الإلكترونية

// Browse
joryio.track('Product Searched', {
  query: 'wireless headphones',
  results: 45
});
joryio.track('Product Viewed', {
  productId: 'prod_123',
  price: 199.99
});
joryio.track('Product Compared', {
  productIds: ['prod_123', 'prod_456']
});

// Cart
joryio.track('Added To Cart', {
  productId: 'prod_123',
  quantity: 1,
  price: 199.99
});
joryio.track('Cart Viewed');
joryio.track('Coupon Applied', {
  code: 'SAVE20',
  discount: 39.99
});

// Checkout
joryio.track('Checkout Started', {
  value: 159.99
});
joryio.track('Payment Info Entered');
joryio.track('Order Completed', {
  orderId: 'order_789',
  revenue: 159.99
});

مقاييس SaaS

// Activation
joryio.track('Trial Started');
joryio.track('Integration Connected', {
  integration: 'salesforce'
});
joryio.track('First Report Created');
joryio.track('Team Member Invited');

// Engagement
joryio.track('Daily Active', {
  loginCount: 45
});
joryio.track('API Call Made', {
  endpoint: '/users',
  method: 'GET'
});

// Revenue
joryio.track('Subscription Created', {
  plan: 'professional',
  mrr: 199
});
joryio.track('Subscription Renewed', {
  plan: 'professional'
});
joryio.track('Subscription Cancelled', {
  reason: 'too_expensive'
});

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

الأنواع المدعومة

joryio.track('Event Name', {
  // String
  name: "John Doe",
  plan: "premium",

  // Number
  age: 30,
  price: 99.99,
  quantity: 5,

  // Boolean
  isActive: true,
  emailVerified: false,

  // Date (ISO 8601 string)
  createdAt: "2024-01-20T10:30:00Z",
  expiresAt: "2024-02-20T23:59:59Z",

  // Array
  tags: ["vip", "early-access"],
  categories: ["electronics", "accessories"],

  // Object
  address: {
    city: "San Francisco",
    state: "CA",
    zip: "94102"
  },
  metadata: {
    source: "web",
    campaign: "summer_sale"
  }
});

أسماء الخصائص المحجوزة

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

• $app_id - معرّف التطبيق
• $app_name - اسم التطبيق
• $platform - المنصة، مثل web أو ios أو android
• $session_id - معرّف الجلسة
• $anonymous_id - معرّف المستخدم المجهول
• $is_identified - ما إذا كان المستخدم معروفاً

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

استخدام الأحداث للتقسيم

أنشئ شرائح بناءً على سلوك الأحداث.

حدث تم تنفيذه

Segment: Active users
Filter: Performed "Session Started" within last 7 days

حدث لم يتم تنفيذه

Segment: Users who haven't upgraded
Filter: Has NOT performed "Subscription Upgraded"

عدد الأحداث

Segment: Power users
Filter: Performed "Feature Used" >= 50 times within last 30 days

خصائص الأحداث

Segment: High-value customers
Filter: Performed "Order Completed"
  WHERE properties.total >= 500
  within last 90 days

شرائح سلوكية معقدة

Segment: At-risk users
Filter Group 1 (AND):
  - Performed "Login" within last 90 days
  - Has NOT performed "Login" within last 14 days
  - Performed "Order Completed" at least 1 time

Use for: Re-engagement campaign

حملات تشغّلها الأحداث

شغّل الحملات بناءً على الأحداث.

مثال 1: التخلي عن السلة

Trigger: "Cart Abandoned" event
Wait: 1 hour
Condition: Has NOT performed "Order Completed"
Action: Send recovery email with discount

مثال 2: التهيئة

Trigger: "Signup Completed" event
Flow:
  → Welcome email (immediate)
  → Wait 2 days
  → Getting started guide
  → Wait 5 days
  → Check: Performed "First Report Created"?
     - Yes: Advanced tips email
     - No: Help offer email

حدود الأحداث والأداء

حدود المعدل

الخطة	الأحداث/الثانية	الأحداث اليومية
Free	10/ث	100,000
Starter	50/ث	500,000
Pro	100/ث	2,000,000
Enterprise	مخصص	غير محدود

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

1. يجمع SDK الأحداث تلقائياً:

   // SDK automatically batches these for you
   joryio.track(event1);
   joryio.track(event2);
   joryio.track(event3);
   // All three sent together after batchFlushInterval (default 5s) or batchSize (default 50) reached
   
   // For critical events that need immediate sending:
   joryio.track('Order Completed', {...});
   joryio.flush(); // Send immediately

2. لا تتبع بوتيرة عالية جداً:

   // Bad: Tracking every scroll
   window.addEventListener('scroll', () => {
     joryio.track('Page Scrolled');
   });
   
   // Good: Track scroll depth milestones
   joryio.track('Page Scrolled', {
     depth: 75 // %
   });

3. أبقِ الخصائص معقولة الحجم:

   • 50 خاصية كحد أقصى لكل حدث.
   • 10KB كحد أقصى للحجم الكلي للحدث.
   • تجنب السلاسل النصية الطويلة جداً.

تصحيح أخطاء الأحداث

تفعيل وضع التصحيح

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

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

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

مشاكل شائعة

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

• تحقق من تهيئة SDK.
• تأكد من تعريف المستخدم أو وجود معرّف مجهول.
• فعّل وضع التصحيح.
• راجع أخطاء وحدة تحكم المتصفح.

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

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

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

• ضبط سمات المستخدم
• إنشاء شرائح سلوكية
• بناء Canvas تشغله الأحداث
• مرجع Track API