توثيق Intlayer Analytics

@intlayer/analytics هي حزمة مساعدة اختيارية تخبرك بالمحتوى الذي يتم عرضه بالفعل لزوارك — أي صفحة، بأي لغة (locale)، وأي جزء محدد من المحتوى المترجم — حتى تتمكن من فهم جمهورك وإجراء اختبارات A/B على المحتوى.

جدول المحتويات

ما الذي يتم تتبعه

تجمع حزمة @intlayer/analytics ثلاثة أنواع من الأحداث المجهولة في دفعات:

يتم جمع الأحداث في الذاكرة وإرسالها كـ طلب دفعة واحد كل 20 ثانية تقريبًا — وليس عند كل ضغطة زر أو كل عملية تصيير (render) — لذا فإن التحليلات لا تؤثر أبدًا على وقت التصيير الأول ولا تضيف طلبًا عند كل تفاعل.

كيف يدعم اختبارات A/B على المحتوى

يسمح لك Intlayer بالفعل بتعريف متغيرات المحتوى (Variants) (على سبيل المثال، قاموس hero-banner مع متغير control ومتغير black_friday). حزمة @intlayer/analytics تغلق الدائرة:

1. دالة getVariant(experimentKey, variants) تخصص بشكل حتمي كل جلسة مجهولة لمتغير — وهي دالة بحتة تعتمد على معرف الجلسة ومفتاح التجربة، لذا فإن التخصيص يكون مستقرًا طوال الجلسة ولا يتطلب أي اتصال بالخادم (server round-trip) قبل التصيير الأول (بدون وميض، وبدون تحول في التخطيط).
2. كل حدث content_exposure يحمل الـ variant الذي تم عرضه.
3. تتيح لك useConversion() نسبة هدف (مثل "cta_click") إلى ذلك المتغير.
4. تقارن نقطة نهاية (endpoint) نتائج التجربة في لوحة التحكم معدلات التحويل لكل متغير، بما في ذلك الدلالة الإحصائية (اختبار z).

التثبيت

حزمة @intlayer/analytics هي تبعية نظيرة واختيارية (peer, optional) — لا يتم تثبيتها تلقائيًا أبدًا بواسطة حزم إطارات العمل. أضفها جنبًا إلى جنب مع intlayer:

npm install @intlayer/analytics

إذا لم تقم بتثبيتها، فإن كل نقطة تكامل تتحول إلى عملية لا تفعل شيئًا (no-op) — انظر تكلفة صفرية عند عدم التثبيت أدناه.

التكوين (Configuration)

التحليلات تعيد استخدام كتلة التكوين editor الحالية — لا يوجد مخطط تكوين analytics منفصل لملئه:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // يستخدم أيضًا كنقطة نهاية لاستيعاب أحداث التحليلات
    clientId: "your-client-id", // يستخدم أيضًا كمفتاح مشروع التحليلات
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — عنوان URL الأساسي الذي يتم إرسال أحداث التحليلات إليه (POST {backendURL}/api/analytics/events).
• editor.clientId — مفتاح المشروع العام المنسوب إلى كل حدث يتم استيعابه. وهو يعمل أيضًا كـ مفتاح تفعيل: تظل التحليلات معطلة تمامًا (ومحذوفة كتعليمات برمجية ميتة، انظر أدناه) حتى يتم تكوين clientId.

إذا قمت بالاستضافة الذاتية لـ Intlayer (self-host)، فإن التحليلات تشير تلقائيًا إلى النسخة الخاصة بك لأنها تتشارك editor.backendURL.

دعم إطارات العمل

التحليلات مدمجة في IntlayerProvider المشترك من react-intlayer، لذا فهي متاحة اليوم في أي مكان يُستخدم فيه هذا المزود:

الاستخدام

التتبع التلقائي على مستوى المزود

لا توجد تغييرات برمجية مطلوبة. بمجرد تثبيت @intlayer/analytics وتكوين editor.clientId، يقوم IntlayerProvider تلقائيًا بـ:

• تهيئة عميل التحليلات عند التحميل (mount)،
• تسجيل page_view عند التحميل الأولي،
• تسجيل page_view عند كل تغيير في اللغة (locale)،
• بدء حلقة الإرسال كل ~20 ثانية وإرسال أي أحداث متبقية عند إزالة التحميل / إغلاق التبويب (عبر navigator.sendBeacon، مع العودة إلى fetch(..., { keepalive: true })).

التتبع التلقائي على مستوى العقدة (Node)

في كل مرة يقوم فيها useIntlayer بحل جزء من المحتوى لعرضه، يقوم المفسر بالإبلاغ عن حدث content_exposure لذلك الـ dictionaryKey المحدد + مسار المفتاح + اللغة — مرة أخرى، لا توجد تغييرات برمجية مطلوبة. يتم تجميع مرات العرض المتكررة لنفس العقدة داخل نافذة الإرسال في حدث واحد مع count (عدد)، لذلك فإن القائمة التي تتم إعادة تصييرها 50 مرة لا ترسل 50 حدثًا.

تتبع التحويلات (Conversions) لاختبارات A/B

استخدم useConversion() لنسبة هدف إلى المتغير الذي شاهدته الجلسة:

حل متغير على جانب العميل

الخصوصية والأداء

• مجهول حسب التصميم: يتم تحديد الجلسات بواسطة معرّف متغير (rotating id)؛ وتقوم الواجهة الخلفية (backend) دائمًا بتخزين تجزئة SHA-256 فقط لهذا المعرف — ولا تقوم أبدًا بتخزين المعرف الخام، ولا تقوم أبدًا بتخزين عنوان IP.
• الموقع تقريبي: فقط رمز الدولة، المستمد من رؤوس تحديد الموقع الجغرافي الخاصة بشبكة CDN (مثل cf-ipcountry، x-vercel-ip-country، ...) — لا يتم قراءة أو تخزين أي IP.
• تستبعد عناوين URL معلمات البحث افتراضيًا، لذلك لا يتم التقاط سلاسل الاستعلام (query strings) أبدًا.
• أخذ العينات (Sampling): يتيح لك sampleRate الاحتفاظ بجزء بسيط فقط من أحداث عرض المحتوى في التطبيقات ذات حركة المرور العالية.
• معالجة مجمعة (Batched): طلب واحد تقريبًا كل 20 ثانية (flushInterval)، أو في وقت مبكر إذا امتلأت الذاكرة المؤقتة (maxBufferSize) — لا يتم أبدًا إرسال طلب واحد لكل حدث.

تكلفة صفرية عند عدم التثبيت

تتبع @intlayer/analytics نفس نمط التبعية الاختيارية المتبع في @intlayer/editor:

• تقوم كل نقطة تكامل بتحميل الحزمة عبر استيراد ديناميكي import() مغلف بـ try/catch — التطبيق الذي لم يقم أبدًا بتثبيت @intlayer/analytics لا يدفع أي تكلفة لحجم الحزمة أو وقت التشغيل، ولا يرى خطأ أبدًا؛
• متغير البيئة في وقت التجميع (INTLAYER_ANALYTICS_ENABLED)، والذي يتم تعيينه تلقائيًا إلى 'false' بواسطة @intlayer/config كلما لم يتم تكوين editor.clientId، يسمح للمجمعين (bundlers) بـ إزالة التعليمات البرمجية الميتة (dead-code-eliminate) للتكامل بأكمله؛
• يتم تعطيل التحليلات داخل نافذة إطار المعاينة (iframe) الخاصة بمحرر Intlayer / CMS، لذا لا يتم حساب جلسات المحرر كحركة مرور حقيقية أبدًا.

لوحة التحكم (Dashboard): صفحة التحليلات

بمجرد أن يجمع مشروعك الأحداث، فإن صفحة التحليلات (Analytics) في لوحة تحكم Intlayer (تظهر في الشريط الجانبي بمجرد تحديد المشروع) تعرض:

• المستخدمين النشطين — الزوار الفريدين خلال النافذة الزمنية المحددة (7 / 30 / 90 يومًا).
• المستخدمين اليوم و المستخدمين خلال آخر 7 أيام.
• مشاهدات الصفحة خلال النافذة المحددة.
• رسم بياني للتطور للزوار الفريدين اليوميين.
• علامات تبويب لتحليل اللغات (Locales) و الموقع (Location)، مما يصنف جمهورك حسب اللغة وحسب البلد.

مرجع واجهة برمجة تطبيقات الواجهة الخلفية (Backend API)

تتطلب جميع نقاط نهاية القراءة المصادقة؛ استيعاب البيانات عام وينسب إلى clientId.

يمكنك أيضًا استدعاء هذه النقاط برمجيًا باستخدام CMS SDK:

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

روابط مفيدة

• القواميس الديناميكية - المجموعات والمتغيرات
• Intlayer CMS - CMS SDK
• محرر Intlayer المرئي
• مرجع التكوين
• دليل الاستضافة الذاتية (Self-Hosting)