تكامل Web SDK

يتيح لك Joryio Web SDK تتبع سلوك المستخدمين وإرسال الأحداث وإدارة ملفات المستخدمين على موقعك.

التثبيت

عبر npm أو yarn

npm install @joryio/web-sdk
# or
yarn add @joryio/web-sdk

عبر CDN

يمكنك تحميل SDK من CDN الخاص بـ Joryio إما بإصدار مثبّت، وهو موصى به للإنتاج، أو بقناة latest التي تتحدث تلقائياً للتطوير أو الاستخدام الداخلي.

<!-- Pinned: production-safe, immutable cache. You upgrade by changing the URL. -->
<script src="https://cdn.joryio.com/sdk/web/1.0.0/joryio.min.js"></script>

<!-- Latest: auto-upgrades within ~5 minutes of every SDK release. -->
<script src="https://cdn.joryio.com/sdk/web/latest/joryio.min.js"></script>

متى تستخدم كل خيار

• المثبت، /1.0.0/: لمواقع الإنتاج التي تريد فيها تحكماً حتمياً في وقت ترقية SDK. تُخدم الحزمة بذاكرة تخزين مؤقت غير قابلة للتغيير لمدة سنة؛ فيجلبها الزائر العائد مرة واحدة ثم لا يحتاج إلى شبكة في التحميلات التالية.
• Latest: للوحات الداخلية وبيئات staging والعملاء الصغار الذين يرغبون في تلقي تحديثات SDK تلقائياً. تُخزن 5 دقائق مع نافذة stale-while-revalidate لساعتين تقريباً، فتنتشر الإصدارات الجديدة خلال دقائق من الإصدار.

ترقية تكامل مثبت. عندما يصدر Joryio نسخة SDK جديدة، غيّر الرقم في المقتطف:

<!-- Before -->
<script src="https://cdn.joryio.com/sdk/web/1.0.0/joryio.min.js"></script>
<!-- After -->
<script src="https://cdn.joryio.com/sdk/web/1.1.0/joryio.min.js"></script>

يعامل المتصفح URL الجديد كملف جديد، ويخزنه بلا تغيير ويشغّل SDK الجديد. تبقى مداخل التخزين القديمة حتى انتهاء TTL أو مسح المستخدم للذاكرة المؤقتة.

التحقق من الإصدار المشغّل. تتضمن كل استجابة SDK رأسي تشخيص:

الرأس	مثال	المعنى
X-SDK-Version-Served	1.0.0	إصدار SDK المنشور حالياً من جهة Joryio.
X-SDK-Version-Requested	1.0.0	الإصدار الذي طلبه URL للمقتطف، ويظهر فقط في المسارات المثبتة.

افتح DevTools ← Network ← ابحث عن joryio.min.js ← Response Headers. إذا اختلف Requested عن Served، يشير مقتطف HTML إلى URL إصدار أقدم من الإصدار المنشور، وقد يحصل الزوار على الحزمة الأحدث مخزنة تحت URL الأقدم.

البدء السريع

1. تهيئة SDK

هيئ SDK أولاً بمفتاح SDK الخاص بك. تجده في لوحة Joryio ضمن الإعدادات ← التطبيقات.

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

// Initialize the SDK
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_your_sdk_key_here',
  enableDebug: false, // Enable debug logging in development
});

عند التحميل من CDN بدلاً من npm، تتوفر الفئة نفسها كـ window.Joryio:

const joryio = new Joryio({
  sdkKey: 'jry_sdk_web_your_sdk_key_here',
});

2. تعريف المستخدمين

عرّف المستخدمين عند التسجيل أو تسجيل الدخول:

// Identify a user
joryio.identify('user_123');

// Set profile attributes separately
joryio.setAttributes({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  plan: 'premium',
  signupDate: '2024-01-15',
});

3. تتبع الأحداث

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

// Track a custom event
joryio.track('Product Viewed', {
  product_id: 'prod_123',
  product_name: 'Premium Plan',
  price: 99.99,
  currency: 'USD',
});

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

خيارات الإعداد

الخيار	النوع	الافتراضي	الوصف
sdkKey	string	مطلوب	مفتاح SDK من لوحة Joryio
apiEndpoint	string	https://api-eu1.joryio.com	تجاوز عنوان API الأساسي، ولا يلزم إلا للاختبار أو النشرات المخصصة.
enableDebug	boolean	false	تفعيل سجل التصحيح في وحدة التحكم.
batchFlushInterval	number	5000	وتيرة إرسال الأحداث المجمعة إلى الخادم بالميلي ثانية. توضع محلياً وتُرسل كل 5 ثوان لتقليل طلبات الشبكة.
batchSize	number	50	أقصى أحداث في الانتظار قبل الإرسال التلقائي؛ عند تراكم 50 حدثاً قبل المؤقت تُرسل فوراً لمنع فقد البيانات.
sendImmediately	boolean	false	إرسال كل حدث فوراً من دون تجميع، ولا يوصى به للإنتاج.
sessionTimeout	number	1800000	انتهاء الجلسة بالميلي ثانية، الافتراضي 30 دقيقة. تبدأ جلسة جديدة بعد هذه المدة من عدم النشاط.
trackSessionStart	boolean	true	تتبع حدث Session Start تلقائياً عند بدء جلسة جديدة.
trackPageViews	boolean	false	تتبع Page Viewed تلقائياً عند تحميل الصفحة.
captureUTM	boolean	true	التقاط معاملات UTM تلقائياً من URL لإسناد الحملة.
resetSessionOnNewCampaign	boolean	false	بدء جلسة جديدة عند تغير UTM، وهو مفيد لتحليلات الجلسات لكل حملة.
trackDeviceProperties	boolean	true	تضمين معلومات الجهاز في Session Start.
persistQueue	boolean	true	حفظ الأحداث المنتظرة في localStorage لتنجو من إعادة تحميل الصفحة.
inApp.allowHtmlJsInAppMessages	boolean	false	يسمح برسائل in-app من نوع HTML التي تنفذ JavaScript كتبها المؤلف داخل iframe معزول في صفحتك. تُعرض الرسائل الأصلية على أي حال. راجع رسائل In-app.

تجميع الأحداث وتفريغها

تجمع الأحداث محلياً وترسل إلى الخادم في مجموعات لتحسين استخدام الشبكة:

• تفريغ تلقائي: كل batchFlushInterval ميلي ثانية، الافتراضي 5 ثوان.
• تفريغ بالحجم: فور تراكم batchSize أحداث، الافتراضي 50.
• تفريغ يدوي: استدعِ joryio.flush() لإرسال الأحداث المنتظرة فوراً.
• عند مغادرة الصفحة: تُفرغ الأحداث تلقائياً عبر sendBeacon عندما يغادر المستخدم الصفحة.
• حد قائمة الانتظار: تحتفظ القائمة المحلية بحد أقصى 1000 حدث. إذا تجاوزته، مثل فترات طويلة بلا اتصال، تُحذف الأقدم مع تحذير في وحدة التحكم.

// Send events immediately instead of batching
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sendImmediately: true  // Send each event immediately
});

// Or configure batching behavior
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  batchFlushInterval: 10000,  // Flush every 10 seconds
  batchSize: 20  // Or when 20 events accumulate
});

// Or manually flush at any time
joryio.track('Important Event', {...});
joryio.flush(); // Send now

إدارة الجلسات

تتبع الجلسات نشاط المستخدم المتواصل وتُدار تلقائياً:

• انتهاء الجلسة: 30 دقيقة من عدم النشاط افتراضياً، ويمكن ضبطه عبر sessionTimeout.
• تبدأ جلسة جديدة عندما:
  1. يحمل المستخدم الصفحة للمرة الأولى.
  2. تمر مدة انتهاء الجلسة بلا أحداث.
  3. يستدعي المستخدم joryio.reset()، مثل تسجيل الخروج.
  4. يُكتشف Campaign جديد إذا كان resetSessionOnNewCampaign مفعلاً.

ضبط مهلة الجلسة:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sessionTimeout: 3600000  // 1 hour in milliseconds
});

// Or shorter session timeout
const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  sessionTimeout: 600000  // 10 minutes
});

نصيحة

تُدار الجلسات تلقائياً بناءً على نشاط المستخدم؛ كل حدث متتبع يعيد ضبط مؤقت عدم النشاط.

تتبع Session Start

يتتبع SDK افتراضياً حدث Session Start كلما بدأت جلسة جديدة. هذا الحدث:

• يمكن استخدامه كمحفز في الحملات ومسارات الرحلات.
• يحمل كل سياق الجلسة: معاملات UTM والمرجع وصفحة الهبوط وبيانات الجهاز عند تفعيل trackDeviceProperties.
• يُخزن في ملف المستخدم كأي حدث، لذا تستطيع الشرائح والتحليلات عد الجلسات لكل مستخدم.

مثال لحدث بداية جلسة:

// Automatically tracked when user visits your site
{
  event: "Session Start",
  properties: {
    utm_source: "google",       // If UTM parameters present
    utm_medium: "cpc",
    utm_campaign: "spring_sale",
    referrer: "https://google.com",
    landing_page: "https://example.com/..."
  },
  userId: "user_123",           // If identified
  anonymousId: "anon_456",
  sessionId: "sess_789"
}

بيانات الجلسة التلقائية

يثري Web SDK أحداث Session Start ببيانات الجهاز والبيئة:

• $user_agent
• $timezone
• $screen_width / $screen_height
• $viewport_width / $viewport_height
• $language / $languages
• $platform
• $browser
• $device_id
• country، رمز ISO-3166-1 alpha-2 مستخرج من IP عند بدء الجلسة.

حالات استخدام:

1. رحلات الترحيب: استخدم Session Start محفزاً للرحلة للوصول إلى المستخدمين عند وصولهم إلى موقعك.
2. شرائح الجلسات: تخزن أحداث Session Start لكل مستخدم، فتعدها شروط الشرائح القائمة على الأحداث؛ مثلاً «نفذ Session Start 10 مرات على الأقل» للمستخدمين المتقدمين أو «لم ينفذها في آخر 7 أيام» لإعادة التفاعل.
3. إسناد الحملات: صفِّ التحليلات على Session Start وجمّعها حسب utm_campaign لمعرفة الحملات التي تقود أكبر عدد من الجلسات.

إيقاف تتبع بداية الجلسة:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  trackSessionStart: false  // Disable automatic session start events
});

رسائل In-app

تعرض حزمة SDK رسائل داخل الصفحة نيابةً عنك. تظهر الحملات المؤهلة من تلقاء نفسها، وتُقاس مرات الظهور والنقرات والإغلاق تلقائيًا.

رموز التسليم (delivery tokens)

عندما يقدّم الخادم حملة مؤهّلة، فإنه يصدر لها أيضًا رمز تسليم موقّعًا وقصير الأجل. يعيد الـ SDK إرسال هذا الرمز عند الإبلاغ عن ظهور أو نقرة أو إغلاق، ويتحقق الخادم من التوقيع قبل تسجيل أي شيء.

لا يتعيّن عليك فعل أي شيء - الـ SDK يتولى ذلك نيابة عنك. وهو موثّق هنا لأنه يغيّر ما يحدث للعميل الذي لا يرسل رمزًا:

POST /v1/in-app/track   (no deliveryToken)
{ "success": false, "error": "A delivery token is required" }

الرمز هو ما يجعل الظهور جديرًا بالثقة: بدونه، يستطيع أي شخص يملك مفتاح الـ SDK - وهو مضمّن في كل تطبيق وكل صفحة - الإبلاغ عن ظهورات ونقرات لحملة لم تُعرض قط، وستحتسبها تقاريرك.

المواقع التي تحمّل الحزمة المستضافة من /sdk/web/latest/joryio.min.js تحصل على ذلك تلقائيًا.

نوعان من المحتوى

المحتوى	ما هو	كيف يُعرض
الأصلي (Native)	بيانات منظمة - عنوان ونص وصورة وأزرار	عناصر DOM عادية تُدرج كعُقد نصية. بدون iframe ودون تنفيذ أي script.
HTML	HTML و‑CSS و‑JavaScript كتبها المؤلف	iframe معزول داخل صفحتك.

السماح برسائل HTML

رسائل HTML معطلة افتراضيًا. تُنفذ رسالة HTML شيفرة JavaScript كتبها المؤلف على موقعك، لذا فإن تفعيلها قرار يتخذه فريقك:

joryio.init({
  sdkKey: 'jry_sdk_web_YOUR_KEY',
  inApp: {
    allowHtmlJsInAppMessages: true,   // الافتراضي: false
  },
});

تركه معطلًا لا يعطل الرسائل داخل الصفحة. تستمر الرسائل الأصلية في الظهور، لأنها بيانات تُكتب في عُقد نصية داخل DOM - دون أي مفسّر. تُتجاهل حملات HTML وتُسجَّل في الكونسول.

إذا كانت سياسة أمان المحتوى (CSP) لديك تمنع السكربتات المضمّنة أو المحتوى داخل iframe، فاترك الإعداد معطلًا وأنشئ حملاتك كرسائل أصلية.

تنسيق الرسائل الأصلية من CSS الخاص بك

الرسالة الأصلية هي DOM حقيقي داخل صفحتك، لا iframe، فيمكنك تنسيقها مثل أي عنصر تملكه. ويصدر المُصيِّر نقاط ارتساء ثابتة:

.joryio-inapp-native                     /* البطاقة */
.joryio-inapp-native h2                  /* العنوان */
.joryio-inapp-native p                   /* نص الرسالة */
.joryio-inapp-native img                 /* الصورة */
.joryio-inapp-native button.primary      /* الزر الأول */
.joryio-inapp-native button.secondary    /* البقية */
.joryio-inapp-close                      /* الإغلاق */
.joryio-inapp-backdrop                   /* طبقة التعتيم */
.joryio-inapp-modal / -banner / -slideup / -fullscreen   /* حسب النوع */

فضِّل المتغيرات على المحدِّدات. فكل ما يمكن للحملة ضبطه يُقرأ من متغير CSS، وضبطه على :root يمنحك أسلوبًا موحّدًا يظل بإمكان الحملة تجاوزه لرسالة بعينها:

:root {
  --joryio-inapp-bg: #0A1240;
  --joryio-inapp-fg: #FFFFFF;
  --joryio-inapp-primary: #00C8B7;
  --joryio-inapp-primary-fg: #041028;
  --joryio-inapp-radius: 18px;
  --joryio-inapp-font: 'Inter', system-ui, sans-serif;
  --joryio-inapp-size: 15px;
  --joryio-inapp-align: start;      /* start | center | end */
  --joryio-inapp-title-weight: 700;
}

ترتيب الأولوية من الأعلى:

1. ما تضبطه الحملة في Style (optional)، ويُكتب inline على البطاقة
2. قيمك أنت في --joryio-inapp-*
3. الإعدادات الافتراضية للحزمة، وهي ألوان النظام

فالحملة التي لا تضبط شيئًا ترث أسلوبك، والتي تضبط خلفية تفوز لتلك الرسالة وحدها. دون !important في أي موضع.

وإن استخدمت المحدِّدات بدلًا من ذلك، فورقة أنماط الحزمة تُحقن وقت العرض، أي أنها تأتي بعد أنماطك في ترتيب المستند فتفوز عند التعادل. زد التخصيص - .joryio-inapp .joryio-inapp-native {…} - بدل قاعدة بفئة واحدة.

والاتجاه مضبوط تلقائيًا: تحمل البطاقة dir="auto"، فتُحاذى الرسالة العربية أو العبرية إلى اليمين داخل صفحة تسير من اليسار إلى اليمين.

أنواع الرسائل

1. Modal - وسط الشاشة مع خلفية معتمة
2. Banner - أعلى الصفحة
3. Slide-Up - إشعار صغير من الأسفل
4. Full-Screen - رسالة تملأ الشاشة
5. Custom - صفحتك تحدد الموضع

Callbacks

joryio.init({
  sdkKey: 'jry_sdk_web_YOUR_KEY',
  inApp: {
    onMessageDisplay: (message) => console.log('shown', message.id),
    onMessageClick: (message, action) => console.log('clicked', action),
    onMessageDismiss: (message) => console.log('dismissed', message.id),
  },
});

مرجع API

التهيئة

const joryio = new JoryioSDK(config)

هيئ SDK بإعداداتك. يعيد المنشئ singleton؛ فإذا أنشأته مرة ثانية يعيد المثيل القائم.

Identify

joryio.identify(userId)

اربط معرّف مستخدم بالجلسة الحالية.

المعاملات:

• userId، string: المعرّف الفريد للمستخدم.

مثال:

joryio.identify('user_123');
joryio.setAttributes({
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
});

Track

joryio.track(eventName, properties?)

تتبّع حدثاً مخصصاً مع خصائص اختيارية.

المعاملات:

• eventName، string: اسم الحدث.
• properties، object اختياري: خصائص الحدث.

مثال:

joryio.track('Order Completed', {
  order_id: 'order_789',
  total: 149.99,
  items: 3,
});

تتبع مشاهدات الصفحة

فعّل تتبع مشاهدات الصفحة التلقائي:

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

Alias

joryio.alias(newUserId)

اربط مستخدماً مجهولاً بمعرّف مستخدم معروف، وهو مفيد بعد التسجيل.

المعاملات:

• newUserId، string: معرّف المستخدم الجديد المراد الربط به.

مثال:

// Before signup (anonymous tracking)
joryio.track('Viewed Landing Page');

// After signup
joryio.alias('user_123');
joryio.identify('user_123');
joryio.setAttributes({ email: 'user@example.com' });

Add Alias

joryio.addAlias(aliasLabel, aliasName)

أضف alias مُسمى للمستخدم الحالي المعرّف.

joryio.addAlias('crm', 'crm_98765');

Reset

joryio.reset()

امسح جلسة المستخدم الحالية، وهو مفيد عند تسجيل الخروج. يمسح كذلك كل بيانات UTM بما فيها إسناد اللمسة الأولى والأخيرة.

// On user logout
function handleLogout() {
  joryio.reset();
  // ... other logout logic
}

الحصول على Anonymous ID

joryio.getAnonymousId()

يعيد معرّف المجهول الحالي، وهو المعرّف الذي يعيّنه Joryio لكل زائر قبل تعريفه. يولّد عند التهيئة الأولى ويحفظ في localStorage ويظل ثابتاً عبر تحميلات الصفحة طوال حياة الزائر المجهول؛ وتعيد reset() توليده عند تسجيل الخروج. وهو anonymousId الدقيق الملحق بكل حدث يرسله track()، فاستخدمه لربط حدث من الخادم أو سجل موافقة بالملف نفسه.

الإرجاع:

• string - معرّف مجهول موجود دائماً.

اقرأه بعد تحميل SDK

مع المقتطف غير المتزامن، يكون window.joryio قائمة أوامر حتى ينتهي تحميل SDK، ولا يمكن لاستدعاء في الانتظار إعادة قيمة. اقرأ المعرّف من المثيل بعد التحميل أو ضمن ready() أدناه.

joryio.ready(function (sdk) {
  const anonId = sdk.getAnonymousId();
  // attach it to your own consent log / server event
  fetch('/consent', { method: 'POST', body: JSON.stringify({ anonymousId: anonId }) });
});

الحصول على User ID

joryio.getUserId()

يعيد معرّف المستخدم الحالي المعرّف، أو null إن كان الزائر مجهولاً وما زال identify() لم يُستدعَ.

الإرجاع:

• string | null

joryio.ready(function (sdk) {
  const userId = sdk.getUserId(); // null until you call joryio.identify(...)
});

Ready

joryio.ready(callback)

شغّل callback(sdk) عند تحميل SDK وتهيئته. هذه هي الطريقة الآمنة لقراءة قيمة، مثل getAnonymousId() أو getUserId()، لا يستطيع مقتطف قائمة الأوامر إعادتها قبل التحميل. يتلقى callback مثيل SDK، ويعمل فوراً إذا كان محملاً أصلاً.

joryio.ready(function (sdk) {
  console.log('anon:', sdk.getAnonymousId(), 'user:', sdk.getUserId());
});

الحصول على بيانات UTM

joryio.getUTMData()

احصل على معاملات UTM الحالية ولمسة الأولى واللمسة الأخيرة.

الإرجاع: كائن يحوي بيانات UTM في current وfirstTouch وlastTouch.

const utmData = joryio.getUTMData();
console.log(utmData.current?.utm_source); // "google"
console.log(utmData.firstTouch?.utm_campaign); // "awareness_campaign"
console.log(utmData.lastTouch?.utm_campaign); // "conversion_campaign"

تحديث UTM

joryio.updateUTM()

حدّث معاملات UTM يدوياً من URL الحالي. وهو مفيد لتطبيقات الصفحة الواحدة التي تغير URL بلا إعادة تحميل.

// React Router
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    joryio.updateUTM();
  }, [location]);
}

// Vue Router
router.afterEach(() => {
  joryio.updateUTM();
});

سمات المصفوفة

joryio.addToArray(key, value)
joryio.removeFromArray(key, value)

عدّل سمات المصفوفة بكفاءة.

المعاملات:

• key، string: اسم السمة.
• value، any: القيمة المطلوب إضافتها أو إزالتها.

// Add tags to user
joryio.addToArray('tags', 'vip');
joryio.addToArray('tags', 'premium');
// Result: tags = ['vip', 'premium']

// Add duplicate (no-op, prevents duplicates)
joryio.addToArray('tags', 'vip');
// Result: tags = ['vip', 'premium'] (unchanged)

// Remove tag
joryio.removeFromArray('tags', 'vip');
// Result: tags = ['premium']

// Common use cases
joryio.addToArray('interests', 'technology');
joryio.addToArray('purchasedProducts', 'prod_123');
joryio.addToArray('featureFlags', 'beta-access');

السلوك:

• تضيف addToArray() القيمة فقط إن لم تكن موجودة، فتمنع التكرارات.
• تنشئ addToArray() مصفوفة جديدة إن لم تكن السمة موجودة.
• تزيل removeFromArray() كل مثيلات القيمة.
• تتزامن التغييرات تلقائياً مع الخلفية للمستخدمين المعروفين والمجهولين.

بيانات الجلسة التلقائية

يثري Web SDK تلقائياً أحداث Session Start ببيانات الجهاز والبيئة. تحفظ هذه القيم في ملف المستخدم وسجلات الجهاز:

• $user_agent
• $timezone
• $screen_width / $screen_height
• $viewport_width / $viewport_height
• $language / $languages
• $platform
• $browser
• $device_id
• country، رمز ISO-3166-1 alpha-2 مستخرج من IP عند بدء الجلسة.

خصائص الحدث

الخصائص القياسية

يحمل كل حدث مخزن هذه الخصائص: يلحق SDK $device_id، وتضيف قناة الاستقبال في Joryio الباقي عند تلقي الحدث:

• $device_id: معرّف جهاز ثابت لكل متصفح.
• $session_id: معرّف الجلسة الحالية.
• $anonymous_id: معرّف المستخدم المجهول قبل التعريف.
• $app_id: معرّف تطبيقك.
• $app_name: اسم تطبيقك.
• $platform: دائماً web لـ Web SDK.
• $is_identified: ما إذا كان المستخدم معرّفاً.

البادئة $ محجوزة، فلا تستخدمها لخصائصك.

الخصائص المخصصة

أضف أي خصائص مخصصة إلى أحداثك:

joryio.track('Video Played', {
  video_id: 'vid_123',
  video_title: 'Product Demo',
  duration: 120,
  autoplay: false,
  // Any other custom data
});

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

1. هيّئ مبكراً

هيّئ SDK في أقرب وقت ممكن في تطبيقك:

// In your main app file
import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({
  sdkKey: process.env.JORYIO_SDK_KEY,
  enableDebug: process.env.NODE_ENV === 'development',
});

2. تتبّع الأحداث المهمة

ركز على الأحداث المهمة لنشاطك:

// Good: Specific, actionable events
joryio.track('Trial Started', { plan: 'premium' });
joryio.track('Feature Used', { feature: 'export', format: 'csv' });

// Avoid: Overly generic events
joryio.track('Button Clicked'); // Too generic

3. استخدم تسمية متسقة

استخدم اصطلاحاً متسقاً للأحداث والخصائص:

// Good: Clear, consistent naming
joryio.track('Subscription Upgraded', {
  from_plan: 'basic',
  to_plan: 'premium',
  billing_cycle: 'monthly',
});

// Avoid: Inconsistent naming
joryio.track('upgraded_subscription', {
  FromPlan: 'basic',
  'to-plan': 'premium',
});

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

عالج تعريف المستخدم وإدارة الجلسة بصورة سليمة:

// On login
function handleLogin(userId, userInfo) {
  joryio.identify(userId);
  joryio.setAttributes({
    email: userInfo.email,
    name: userInfo.name,
  });
}

// On logout
function handleLogout() {
  joryio.reset();
}

// On signup
function handleSignup(userId, userInfo) {
  joryio.alias(userId);
  joryio.identify(userId);
  joryio.setAttributes(userInfo);
}

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

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

1. تحقق من مفتاح SDK وتأكد من أنه يبدأ بـ jry_sdk_web_.
2. تحقق من وحدة التحكم وفعّل وضع التصحيح لرؤية سجلات مفصلة.
3. تحقق من التهيئة وتأكد من تنفيذ new JoryioSDK(config) قبل أي دوال أخرى.

أخطاء CORS

تستجيب نقاط تتبع SDK بـ Access-Control-Allow-Origin: *، لذلك لا تحتاج إلى قائمة سماح نطاقات. إذا استمر ظهور أخطاء CORS، تحقق من أن apiEndpoint يشير إلى عنوان الأساس الصحيح، https://api-eu1.joryio.com، ومن أن إضافة متصفح أو proxy لا يحجب الطلب أو يزيل رؤوس CORS.

مشاكل تتبع الجلسات

يستخدم SDK localStorage لحفظ الجلسة. تأكد من:

• تقديم موقعك عبر HTTPS، وهو مطلوب للسياقات الآمنة.
• أن المستخدمين لم يعطلوا localStorage.
• أنك لا تستدعي reset() من دون قصد.

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

• Web SDK: UTM والإسناد - إسناد Campaign واللمسة الأولى والأخيرة والتقاط UTM.
• تتبع التجارة الإلكترونية - أحداث المنتج والسلة والدفع والطلب.
• تتبع الأحداث المخصصة
• ضبط سمات المستخدم
• إنشاء الشرائح
• بناء الحملات