إنشاء التطبيقات

يمثل التطبيق منصة واحدة تتتبع عليها المستخدمين - موقعك أو تطبيق iOS أو تطبيق Android - ويملك مفتاح SDK الذي يستخدمه إصدار تلك المنصة. تشرح هذه الصفحة إنشاء تطبيق وبدء تدفق الأحداث الأولى.

تُنشأ التطبيقات داخل مساحة عمل، وتحتاج إلى إذن الكتابة على الإعدادات في تلك المساحة.

1. أنشئ التطبيق

1. من لوحة تحكم Joryio، انتقل إلى الإعدادات → التطبيقات.
2. انقر إنشاء تطبيق.
3. أدخل اسم التطبيق؛ اجعله واضحًا، مثل «موقع الإنتاج» أو «iOS - App Store».
4. اختر المنصة: الويب أو iOS أو Android. لا يمكن تغيير المنصة لاحقًا؛ أنشئ تطبيقًا جديدًا بدلًا من ذلك. (تُنشأ تطبيقات Shopify وWooCommerce وMagento تلقائيًا من تكاملاتها، وليس من هذا الحوار.)
5. انقر إنشاء.

إذا كنت تنشر على عدة منصات، فأنشئ تطبيقًا لكل منصة؛ راجع التتبع متعدد المنصات. بالنسبة إلى React Native، أنشئ تطبيق iOS وتطبيق Android.

2. انسخ مفتاح SDK

يظهر التطبيق الجديد في جدول التطبيقات مع مفتاح SDK الذي أُنشئ له، بالتنسيق jry_sdk_<platform>_<random>:

jry_sdk_web_4f2a9c...

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

3. وصّل SDK

ثبّت وابدأ SDK المطابق لمنصة التطبيق، مع تمرير المفتاح الذي نسخته:

المنصة	دليل SDK	التهيئة باستخدام
الويب	Web SDK	new JoryioSDK({ sdkKey: 'jry_sdk_web_...' })
iOS	iOS SDK	Joryio.shared.initialize(sdkKey: "jry_sdk_ios_...")
Android	Android SDK	Joryio.initialize(context, "jry_sdk_android_...")
React Native	React Native SDK	Joryio.initialize(key, apiHost) باستخدام مفتاح iOS أو Android وفق Platform.OS

يجب أن يطابق المفتاح المنصة؛ فلا يسجل مفتاح jry_sdk_web_... داخل iOS SDK ذلك الإصدار بوصفه تطبيق iOS.

بعد ذلك، عرّف المستخدمين وتتبع أول حدث:

// Web SDK example - the other platforms use the equivalent calls
const joryio = new JoryioSDK({ sdkKey: 'jry_sdk_web_...' });

joryio.identify('user_123');
joryio.track('order_placed', { order_id: 'ORD-001', total: 149.99 });

4. تحقق من وصول الأحداث

1. شغّل حدثًا في تطبيقك (أو حمّل صفحة فحسب؛ يتتبع SDK حدث Session Start تلقائيًا).
2. افتح التحليلات → مستكشف الأحداث في لوحة التحكم وابحث عن الحدث. تجمع SDKs الأحداث وتدفعها كل بضع ثوانٍ، لذا امنحها مهلة قصيرة أو استدعِ flush() للإرسال فورًا.
3. للتحقق من كل تطبيق، عُد إلى الإعدادات → التطبيقات وانقر عرض التحليلات في التطبيق: يعرض إجمالي الأحداث والمستخدمين النشطين وطابع آخر حدث زمنيًا لمفتاح SDK هذا.

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

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

من صف التطبيق في الإعدادات → التطبيقات يمكنك أيضًا:

• ضبط بيانات اعتماد Push - APNS لنظام iOS وFCM لنظام Android، أو تفعيل Web Push ‏(VAPID) لتطبيقات الويب.
• تعطيل تطبيق - تُرفض الأحداث المرسلة بمفتاح تطبيق معطل؛ وتبقى الأحداث التاريخية محفوظة.
• إعادة إنشاء مفتاح SDK - تدوير فوري يوقف المفتاح السابق.
• تفعيل مصادقة SDK - اطلب اختياريًا JWT موقّعًا من عميلك (في ترويسة X-Joryio-Auth) مع كل طلب إدخال للتطبيق، ويتحقق منه مقابل مفتاح عام تسجله.
• حذف التطبيق - يوقف التتبع لهذا المفتاح نهائيًا؛ وتبقى الأحداث التاريخية محفوظة.

تأمين الهوية: مصادقة SDK (موصى بها)

مفتاح SDK قابل للنشر؛ أي إنه يُضمّن في موقعك أو تطبيقك، ويمكن لأي شخص استخراجه بحكم تصميمه. لا يثبت المفتاح وحده إلا هوية التطبيق لا المستخدم النهائي: مثل كل SDK تحليلات من جهة العميل، يحمل الطلب userId أو anonymousId يقدمه العميل لتحديد جهة الاتصال المقصودة، لكنه لا يثبت أن المتصل يسيطر على تلك الجهة.

لا تمثل هذه مشكلة في معظم حالات تتبع الأحداث. ولكن في عمليات الهوية الحساسة - تغيير الموافقة أو تسجيل وجهة Push أو دمج الملفات الشخصية عبر identify - قد يتمكن شخص يملك مفتاح SDK ومعرّف جهة اتصال معروف (غالبًا Email) من تنفيذ إجراء على تلك الجهة. لمعالجة ذلك، فعّل مصادقة SDK:

• يوقّع خادمك الخلفي JWT قصير العمر (RS256/ES256) يكون موضوعه المستخدم المعرّف، ويرسله SDK في X-Joryio-Auth. تتحقق Joryio منه باستخدام المفتاح العام الذي تسجله، فيرتبط الطلب بمستخدم تم إثباته. هذا هو النموذج القياسي لمصادقة تعامل SDK من جهة العميل.
• بعد التفعيل، تُرفض الكتابات الحساسة للمستخدمين المجهولين فقط (لا يمكن ربط anonymousId تشفيريًا)؛ استدعِ identify(userId) أولًا. لا يتأثر تتبع الأحداث العادي.

لأعلى مستوى من الصرامة، فعّل هوية SDK الصارمة في التطبيق: فهي تتطلب userId تم التحقق منه عبر مصادقة SDK لكل تغيير حساس (الموافقة أو تسجيل Push أو identify)، وترفض المحاولات المجهولة وغير المصادق عليها مباشرةً.

نوصي بتفعيل مصادقة SDK لأي تطبيق يتيح للمستخدمين النهائيين إدارة الموافقة أو تلقي Push.

اختر userId لا يمكن تخمينه

مصادقة SDK اختيارية، وقرار تفعيلها يعود إليك. وإلى أن تفعّلها، يكون userId هو الشيء الوحيد الفاصل بين الطلب وجهة الاتصال - لذا فإن اختيار المعرّف هو بحد ذاته قرار أمني.

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

تجنّب

• عناوين البريد الإلكتروني وأرقام الهاتف. كل من يستطيع تسمية عميلك يستطيع اشتقاق معرّفه. والتجزئة (hash) لا تساعد: من يعرف البريد الإلكتروني يمكنه حساب التجزئة نفسها.
• معرّفات قاعدة البيانات المتسلسلة أو التلقائية. معرّف واحد معروف يكشف كل الباقي، بمجرد العدّ.
• أي قيمة عامة بالفعل - قيم تظهر في الروابط أو مصدر الصفحة أو تأكيدات الطلبات أو تذاكر الدعم.

فضّل

• قيمة معتمة وعشوائية لكل مستخدم - UUIDv4 يُنشأ مرة واحدة ويُخزَّن مع سجل المستخدم لديك.
• ثابتة طوال عمر الحساب. تغييرها يقسم شخصًا واحدًا إلى جهتي اتصال، مما يكسر السجل والموافقة.

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

ذات صلة

• نظرة عامة على التطبيقات
• التتبع متعدد المنصات
• تتبع الأحداث