التوثيق

كيف يعمل

أربع أفكار تشرح تقريبًا كل ما يفعله Gurulu. حين تستقر هذه الأفكار، يصبح بقية المنتج مجرد تنفيذ دقيق لها.

1. نواة الكون — إلزامية من اليوم الأول

كل حدث وكل صف وكل نقطة نهاية في Gurulu تحمل المجموعة نفسها من الحقول. منذ أول عملية استيعاب. لا يوجد "سنضيف ذلك العمود لاحقًا". النواة إلزامية.

الحقول المطلوبة هي:

  • tenant_id — حسابك
  • workspace_id — المشروع داخل حسابك
  • anonymous_id أو person_id — من أطلق هذا
  • session_id — الزيارة التي ينتمي إليها
  • source_context — من أين جاء: الجهاز، المتصفح، البلد، المُحيل، نطاق المصدر، UTM
  • confidence — مدى يقيننا من الهوية
  • consent_state — بماذا وافق المستخدم، حسب فئة GCM v2
  • health_status — هل اجتاز هذا الحدث بوابة التحقق

لماذا يهم هذا: كل منصة تحليلات استخدمناها تنمو حقولها مع الوقت. وحين تحتاج إلى التقسيم حسب المتصفح، يكون نصف أحداثك التاريخية بلا هذا الحقل. تضمن نواة الكون أن أي استعلام يخطر ببالك يعمل على كل حدث أرسلته يومًا — بما في ذلك الأول.

الواجهة تصل على مراحل. أما شكل البيانات فلا يتّسع لاحقًا.

2. ثلاثة أصناف من الأحداث، لا تختلط أبدًا

الأحداث ليست كيسًا واحدًا. هناك ثلاثة أصناف، وتبقى منفصلة منذ لحظة دخولها النظام.

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

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

3. أربع قنوات، أربعة أدوار، لا التباس

هناك بالضبط أربع طرق يصل بها الحدث إلى Gurulu، ولكل قناة دور صارم:

  • سكربت المتصفح (@gurulu/web). يراقب الصفحة. يلتقط التفاعلات تلقائيًا. لا يرسل نتائج أبدًا.
  • Playground. أداة بناء بصرية فوق موقعك الحي. تتيح لغير المهندس أن يشير إلى زر ويقول "هذا تسجيل". تضيف قاعدة إلى السجل — لا تنشئ أحداثًا.
  • SDK الخادم (@gurulu/web بدالتي identify وtrack، إضافة إلى @gurulu/node). يرسل الأحداث المعرّفة والنتائج المتحقَّق منها من واجهتك الخلفية. من هنا تُرسل حركة الأموال.
  • الوكيل وسطر الأوامر وخادم MCP (@gurulu/cli مع @gurulu/mcp-server). واعٍ بالسجل. يقرأ محررك الذكي السجل ويعرف أن اسم الحدث هو bet_placed لا bet.placed. الوكيل لا يخترع حدثًا أبدًا.

حين تبقى القنوات صارمة، يتوقف أمران: النتائج غير الجديرة بالثقة القادمة من المتصفح، وانزلاق أسماء الأحداث عبر قاعدة الكود.

4. الحدث عقد

السجل هو مصدر الحقيقة لأسماء الأحداث وأشكالها. ويترتب على ذلك ثلاثة أمور:

  • مفاتيح الأحداث بصيغة snake_case. يفرض السجل النمط ^[a-z0-9_]+$. يُقبل bet_placed. ويُرفض bet.placed وbetPlaced.
  • لا يرسل SDK نصوصًا حرة. تُولَّد الأنواع من السجل. وإن كان السجل لا يعرف signup_completed، فكودك لا يُترجم.
  • يمر كل حدث ببوابة تحقق عند الاستيعاب. أربع نتائج ممكنة: قبول، تحذير، حجر، رفض. ويُسجَّل القرار وسببه.

في التكامل المستمر، يُسقط الانزلاق طلب الدمج. يُلتقط الحدث المكسور في مراجعة الطلب، لا بعد ثلاثة أسابيع في اللوحة.

5. إسناد يحدّده العميل

لا نختار نموذج الإسناد نيابة عنك. أنت تحدّد سياسة: أول لمسة، آخر لمسة، خطّي، تناقص زمني، قائم على الموضع، أو مدفوع بالبيانات. أنت تختار نافذة الرجوع. وأنت تختار كيف تُوزن القنوات.

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

إن أردت أن تعرف لماذا نُسبت عملية بيع إلى البحث المجاني بدل المدفوع، فالجواب موجود في قاعدة البيانات. ليست صندوقًا أسود.

6. هوية قابلة للتفسير

يدمج محرك الهوية سجلّين حين تتفق سبع خطوات من الأدلة. وكل دمج:

  • قابل للتراجع. دفتر الدمج للإضافة فقط. وفك الدمج عملية كتابة واحدة.
  • مُقيَّم بالثقة. لكل دمج مستوى — عالٍ، متوسط، منخفض — وقائمة إشارات.
  • قابل للتدقيق. يمكنك أن ترى متى اندمج سجلّان، وبأي دليل، وعلى أي قناة.

لا يوجد "رسم مستخدمين" غامض تثق به على عماه. بل دفتر يمكنك قراءته.

7. الخصوصية افتراضيًا

المنطقة الافتراضية هي الاتحاد الأوروبي. وتحصل الخطة المجانية على الإقامة الأوروبية نفسها التي تحصل عليها الخطط المدفوعة. تُلتقط حالة الموافقة عند كل حدث بفئات Google Consent Mode v2، ويُصفّي خط المعالجة الوجهات اللاحقة بناءً على ما وافق عليه المستخدم. وتعمل طلبات التصدير والنسيان (DSR) على طابور باتفاقية مستوى خدمة قدرها 60 ثانية.

لا نلتقط ما لا نحتاجه. الأسطح الحساسة — صفحات الدفع، ومعرفة العميل، وإعدادات الحساب — مُقنَّعة في إعادة التشغيل افتراضيًا. يمكنك توسيع الالتقاط؛ لكن الافتراضي ضيّق.

إلى أين بعد ذلك

العودة إلى التوثيق