تتبّع الأحداث عبر المنصّات: كتالوج أحداث واحد للويب وiOS وAndroid

إذا كان فريق الويب لديك يسمّيه "purchase_completed"، وفريق iOS يسمّيه "orderPlaced"، وفريق Android يسمّيه "buy_event"، فأنت لا تملك تحليلات — بل تملك ثلاثة صوامع بيانات غير متوافقة. يبدأ تتبّع الأحداث عبر المنصّات بمفردات مشتركة، وهو واحد من أصعب المشكلات في تحليلات المنتجات لأنه يتطلّب تنسيقاً عبر الفِرق وقواعد التعليمات البرمجية ودورات الإصدار.

تحلّ Gurulu هذا عبر كتالوج أحداث مرجعي: مجموعة موحّدة من 18 حدثاً تعمل بشكل متطابق عبر الويب وiOS وAndroid. ولكلّ حدث مخطَّط مُحدَّد الأنواع، ومساعِدات SDK خاصة بكل منصّة، وتطبيع تلقائي لأسماء الأحداث القديمة. يأخذك هذا الدليل خطوةً بخطوة عبر الكتالوج، وحِزَم SDK، وعملية الإعداد.

مشكلة الأحداث غير المتّسقة

عندما تختلف أسماء الأحداث عبر المنصّات، ينهار كلّ نظام لاحق. فلا يمكن بناء مسارات التحويل التي تمتدّ عبر الويب والأجهزة المحمولة لأن الخطوات تحمل أسماء مختلفة. وتُحصِي نماذج الإسناد التحويلات بشكل خاطئ لأن عملية شراء على iOS تكون غير مرئية للنموذج الذي يتمحور حول الويب. وتستبعد شرائح نظام إدارة علاقات العملاء (CRM) مستخدمي الأجهزة المحمولة لأن الحدث المؤهِّل غير موجود في مساحة أسماء منصّتهم. وعندما يسأل مدير منتج "كم عدد المستخدمين الذين أكملوا الإعداد الأولي؟"، يقضي فريق البيانات يومَين في التوفيق بين ثلاثة مخطَّطات أحداث مختلفة قبل أن يتمكّن من الإجابة.

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

كتالوج الأحداث المرجعي في Gurulu

تحدّد Gurulu 18 حدثاً قياسياً، يُسبَق كلّ منها بالرمز $ لتمييزها عن الأحداث المخصّصة. وتغطّي هذه الأحداث دورة حياة المستخدم الأساسية: الاكتساب، والتفعيل، والتفاعل، وتحقيق الدخل، والاحتفاظ. وكلّ حزمة SDK من Gurulu — للويب وiOS وAndroid — تنفّذ هذه الأحداث بأسماء متطابقة، ومخطَّطات خصائص متطابقة، ودلالات متطابقة.

// Gurulu Canonical Events (subset of 18)
$page_view    // Web, iOS, Android
$session_start
$sign_up
$login
$purchase
$add_to_cart
$search
$share
$app_install  // iOS, Android only
$first_open   // iOS, Android only

مساعِدات SDK مُحدَّدة الأنواع

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

// Web (JavaScript)
import { gurulu } from '@gurulu/web';
gurulu.track('$purchase', {
  value: 49.99,
  currency: 'USD',
  items: [{ id: 'sku_001', name: 'Pro Plan' }],
});

// iOS (Swift)
import GuruluSDK

Gurulu.track("$purchase", properties: [
  "value": 49.99,
  "currency": "USD",
  "items": [["id": "sku_001", "name": "Pro Plan"]]
])

// Android (Kotlin)
import io.gurulu.sdk.Gurulu

Gurulu.track("\$purchase", mapOf(
  "value" to 49.99,
  "currency" to "USD",
  "items" to listOf(mapOf("id" to "sku_001", "name" to "Pro Plan"))
))

لاحِظ أن اسم الحدث، ومفاتيح الخصائص، وأنواع الخصائص متطابقة عبر المنصّات الثلاث جميعها. وعندما تصل هذه الأحداث إلى نقطة استيعاب (ingest) Gurulu، تُخزَّن في المخطَّط نفسه بغضّ النظر عن المصدر. وتعمل مسارات التحويل والإسناد وشرائح نظام إدارة علاقات العملاء (CRM) عبر المنصّات دون أي تعيين إضافي.

تعيين التطبيع

إذا كانت لديك قاعدة تعليمات برمجية قائمة بأسماء أحداث غير قياسية، فلست بحاجة إلى إعادة كتابة جميع تجهيزاتك دفعةً واحدة. تدعم Gurulu تعيين التطبيع: تكوين يترجم تلقائياً أسماء الأحداث الواردة إلى مكافئاتها المرجعية. ويمكنك تعريف عمليات التعيين في لوحة المعلومات ضمن الإعدادات، أو عبر واجهة برمجة التطبيقات (API).

// Normalization mapping examples
order_completed    → $purchase
signed_up          → $sign_up
item_added_to_cart → $add_to_cart
page_loaded        → $page_view
user_registered    → $sign_up

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

إعداد التتبّع عبر المنصّات

الخطوة الأولى: ثبِّت حزمة Gurulu SDK على كلّ منصّة. حزمة Web SDK هي وسم برمجي نصّي (script tag) أو حزمة npm. وحزمة iOS SDK متاحة عبر Swift Package Manager أو CocoaPods. وحزمة Android SDK موجودة على Maven Central. وتُهيّأ كلّ حزمة SDK بمُعرّف موقعك ورمزك المميّز، وتتتبّع تلقائياً مشاهدات الصفحات، وبدايات الجلسات، وأحداث دورة حياة التطبيق.

الخطوة الثانية: جهِّز أحداثك الرئيسية باستخدام الأسماء المرجعية. ابدأ بالأحداث الأكثر أهمية لعملك — وهي عادةً $sign_up و$purchase و$add_to_cart. استخدِم المساعِدات المُحدَّدة الأنواع لضمان الاتّساق. لا تحاول تجهيز جميع الأحداث الـ 18 دفعةً واحدة؛ بل ابدأ بمسار التحويل لديك ثم توسّع.

الخطوة الثالثة: كوِّن عمليات تعيين التطبيع لأي أحداث قديمة لا تستطيع إعادة تسميتها فوراً. وهذا يمنحك تحليلات موحّدة عبر المنصّات بينما ترحِّل قاعدة تعليماتك البرمجية تدريجياً. وتُكمِل معظم الفِرق الترحيل خلال سباقَين إلى أربعة سباقات (sprints)، بالعمل على منصّة واحدة في كلّ مرة.