ما تحليلات المنتج؟ المقاييس وعودة المستخدمين

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

الأحداث والمستخدمون والجلسات

الوحدة	المعنى
الحدث	إجراء واحد مُدوَّن. يمكن لشخص واحد أن يرسل أحداثًا كثيرة.
مستخدم معروف الهوية	معرّف كيان ثابت ومبهم يرسله التطبيق، ونوعه `user`.
كيان مجهول الهوية	معرّف كيان له نوع، لكنه ليس مستخدمًا. لا يُحسب مستخدمًا أبدًا.
الجلسة	معرّف جلسة صريح يرسله التطبيق. يمكن لشخص واحد أن تكون له جلسات كثيرة.

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

افتح نظرة عامة في لوحة التحكم

افتح التحليلات في لوحة تحكم LogBrew.
اختر مشروعًا واحدًا.
اختر 24 ساعة أو 7 أيام أو 14 يومًا أو 30 يومًا أو مخصص.
اقرأ مخطط النشاط، ثم أبرز الأحداث وأبرز الواجهات.
افتح التغطية والحدود قبل أن تقرأ أعداد المستخدمين.

في مخصص، اختر اليوم الأول واليوم الأخير، ثم اختر تطبيق. اليومان كلاهما جزء من النطاق. مثلًا، من 12 أبريل إلى 16 أبريل 5 أيام. تستخدم لوحة التحكم تواريخ UTC. النطاق المخصص 31 يومًا على الأكثر، ولا يمكن أن يتضمن تواريخ مستقبلية. تعرض لوحة التحكم أيضًا اتجاهين للمستخدمين للمشروع والتواريخ نفسها. يعرض هل يعود المستخدمون؟ الاحتفاظ بالمستخدمين. ويعرض كيف تتغير قاعدة المستخدمين؟ مجموعات دورة الحياة. يستخدم الاتجاهان كل النشاط المصنَّف للمستخدمين معروفي الهوية. لا تختار حدثًا لهما.

اقرأ النظرة العامة للمشروع

logbrew analytics overview --project "<project_id>" --since 7d --json

أضف --until <RFC3339> لتحديد وقت نهاية غير مشمول في النطاق. يقبل --interval القيم auto و1m و5m و15m و1h و6h و1d. يحدد --top-limit عدد الصفوف في كل قائمة من القوائم الأبرز، من 1 إلى 20. القيمة الافتراضية 10. أضف --service أو --release أو --environment للتصفية حسب سياق مطابق تمامًا. نقطة نهاية API هي GET /api/telemetry/analytics/overview. تحتوي النظرة العامة على مجاميع النشاط وسلسلة زمنية وأبرز الإجراءات والنشاط المصنَّف. يعرض هذا المقتطف المجاميع وتغطيتها:

{
  "schema_version": 3,
  "analysis_level": "user_and_session",
  "summary": {
    "actions": 120,
    "active_identified_users": 18,
    "active_anonymous_subjects": 7,
    "sessions": 24
  },
  "coverage": {
    "identified_actions": 100,
    "anonymous_actions": 20,
    "subject_coverage": {
      "index_version": 1,
      "identified_user_events": 100,
      "anonymous_subject_events": 8,
      "legacy_unknown_kind_events": 4,
      "missing_subject_events": 6,
      "historical_unindexed_events": 2
    },
    "sessionized_actions": 90,
    "traced_actions": 60,
    "top_actions_truncated": true
  },
  "next_action": { "code": "build_product_funnel" }
}

مجموع أعداد subject_coverage الخمسة يساوي summary.actions. وحده identified_user_events يُحسب ضمن المستخدمين. يشمل anonymous_actions الحالات الأربع الأخرى. في هذا المثال، تأتي 8 أحداث لكيانات مجهولة الهوية من نحو 7 كيانات مجهولة الهوية مختلفة. لا يمثّل أيٌّ من الرقمين عدد مستخدمين. القائمة الأبرز المقتطَعة لا تثبت غياب الأحداث الأقل حجمًا. قيمة analysis_level هي no_data أو event_only أو user_level أو user_and_session. توضح الأسئلة التي تستطيع البيانات الإجابة عنها. المستوى هو أعلى مستوى يدعمه summary أو classified_activity. ولا يعني أن المجموعتين كلتيهما فيهما مستخدمون أو جلسات.

افصل بين مجموعتي النشاط

حقول الاستجابة	الأحداث المحسوبة
`summary`، `coverage`، `series`، `top_actions`	أحداث إجراءات المنتج، ومنها الإجراءات التي ليس لها تصنيف مدعوم.
`classified_activity`	مشاهدات الصفحات ومشاهدات الشاشات والتفاعلات. مشاهدات الصفحات ليست إجراءات.

مشاهدات الشاشات والتفاعلات المصنَّفة إجراءات أيضًا. لا تجمع summary.actions مع classified_activity.summary.events. اقرأ تغطية المجموعة التي تستخدمها. مجموع أعداد الكيانات في classified_activity.coverage.subject_coverage يساوي classified_activity.summary.events. قد تكون قيمة summary.actions هي 0 بينما توفر مشاهدات الصفحات المصنَّفة أعداد المستخدمين والجلسات. افحص classified_activity قبل أن تستنتج أنه لا يوجد نشاط للمنتج.

اتّبع الإجراء التالي

يحتوي next_action على code وtarget وreason. ويعرض أهم فجوة في الالتقاط أو خطوة التحليل التالية:

`next_action.code`	المعنى
`capture_product_activity`	لا توجد أحداث منتج تطابق النطاق.
`classify_product_activity`	توجد أحداث، لكن لا يوجد بينها مشاهدة صفحة أو مشاهدة شاشة أو تفاعل.
`identify_product_users`	لا يوجد حدث له كيان من النوع `user`.
`sessionize_product_activity`	لا يوجد حدث له معرّف جلسة.
`capture_funnel_steps`	توجد أقل من حدثين مصنَّفين لهما اسم.
`build_product_funnel`	تستطيع البيانات دعم قمع تحويل.

أجرِ تغيير الالتقاط في التطبيق، ثم افحص حدثًا جديدًا. الأحداث الأقدم لا تثبت أن التغيير يعمل.

استدعِ API مباشرةً

أرسل رمز Bearer للحساب. أرسل response_version=3 لتحصل على الاستجابة نفسها التي يقرؤها CLI. إذا حذفت response_version، فسيعيد API الإصدار 1، وهو بلا أعداد للكيانات مجهولة الهوية وبلا subject_coverage.

curl -sS -G "https://api.logbrew.co/api/telemetry/analytics/overview" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<project_id>" \
  --data-urlencode "since=7d" \
  --data-urlencode "response_version=3"

قيمة since مدة موجبة، مثل 24h أو 7d أو 30d، أو طابع زمني بتنسيق RFC3339. وقيمة until طابع زمني اختياري بتنسيق RFC3339. يشمل النطاق since ولا يشمل until. إذا حذفت until، فسينتهي النطاق عند وقت الطلب. لا يمكن أن يزيد النطاق على 31 يومًا. للفترة من 12 أبريل إلى 16 أبريل 2026، أرسل 2026-04-12T00:00:00Z في since و2026-04-17T00:00:00Z في until. النطاق الأطول من 31 يومًا يعيد HTTP 422:

{
  "error": "product analytics range must not exceed 31 days",
  "code": "validation_failed",
  "next": "use a shorter range or query consecutive bounded windows",
  "next_action": { "code": "fix_request", "target": "request" }
}

اقرأ code وnext_action في منطق البرنامج. واعرض error وnext على الشخص. تسرد صفحة أخطاء API استجابات الأخطاء الأخرى. تأخذ مسارات التحليلات POST أدناه نص JSON فيه حقول project_id وsince وuntil وservice_name وrelease وenvironment نفسها. تُرفض حقول النص غير المعروفة.

قِس قمع التحويل

يقيس قمع التحويل التحويل عبر خطوتين إلى 8 خطوات مرتبة:

logbrew analytics funnel --project "<project_id>" --since 7d \
  --step page-view /pricing \
  --step interaction checkout_started \
  --step interaction checkout_completed \
  --json

يجب أن يكون الطابع الزمني لكل خطوة لاحقة بعد الطابع الزمني للخطوة التي قبلها. لا يمكن لحدث واحد أن يُكمل خطوتين. الوحدة الافتراضية هي الجلسة. استخدم --unit identified-user لعدّ المستخدمين عبر الجلسات. انسخ أسماء الأحداث من النظرة العامة. نسبة مجموعين غير مرتبطين ليست معدل تحويل. يجب أن تقع الخطوة الأخيرة داخل فترة التحويل التي تبدأ عند الخطوة الأولى. حدّدها باستخدام --conversion-window، مثل 30m أو 1h. القيمة الافتراضية 24 ساعة، أو النطاق كله إذا كان النطاق أقصر. لا يمكن أن تكون الفترة أطول من النطاق. مسار API هو POST /api/telemetry/analytics/funnel. تعرض استجابة قمع التحويل المرتب نص الطلب والاستجابة.

استكشف المسارات حول حدث واحد

تعرض المسارات أكثر تسلسلات الأحداث المسماة شيوعًا بعد حدث مرجعي واحد أو قبله:

logbrew analytics paths following --project "<project_id>" --since 24h \
  --anchor-kind page-view --anchor-event /pricing \
  --json

استخدم preceding بدل following للأحداث التي تسبق الحدث المرجعي. يحدد --depth عدد الأحداث في ذلك الجانب، من 1 إلى 8. القيمة الافتراضية 4. ويحدد --path-limit عدد المسارات، من 1 إلى 20. القيمة الافتراضية 10. الأحداث المتطابقة المتتالية تُحسب حدثًا واحدًا. أضف --keep-repeated للإبقاء على كل واحد منها. تستخدم المسارات معرّفات الجلسات. يبدأ المسار اللاحق عند أول حدث مرجعي في كل جلسة. وينتهي المسار السابق عند آخر حدث مرجعي. لا تعدّ المسارات المستخدمين، ولا توضح سبب فشل إجراء. مسار API هو POST /api/telemetry/analytics/paths.

اقرأ الاحتفاظ بالمستخدمين

يوضح الاحتفاظ بالمستخدمين ما إذا كان المستخدمون معروفو الهوية يعودون بعد حدث البداية:

logbrew analytics retention --project "<project_id>" --since 30d \
  --start-kind page-view --start-event /signup \
  --return-kind interaction --return-event report_opened \
  --json

قيمة --interval هي hour أو day أو week أو thirty-day. تعني thirty-day مدة 30 يومًا، لا شهرًا تقويميًا. تتراوح --interval-count من 1 إلى 31. القيمة الافتراضية 10. يعدّ --mode return-on العودات في كل فترة بعينها. ويعدّ return-on-or-after العودات في كل فترة أو بعدها. يجب أن تقع العودة بعد حدث البداية الخاص بالمستخدم. يبدأ كل مستخدم مرة واحدة، عند أول حدث بداية في النطاق. وهذا الحدث ليس دائمًا أول حدث للمستخدم على الإطلاق. المستخدم الذي يعود أكثر من مرة في فترة واحدة يُحسب مرة واحدة لتلك الفترة. اقرأ عدد المستخدمين المحتفَظ بهم مع عدد المستخدمين المؤهلين لكل فترة. المستخدمون الذين لم تنتهِ فترتهم بعد غير مؤهلين. ولا يُحسبون مفقودين. مثلًا، عودة 40 مستخدمًا من أصل 100 مستخدم مؤهل تعني احتفاظًا بالمستخدمين بنسبة 40%. انخفاض معدل العودة لا يوضح سبب مغادرة الناس.

اطلب الاحتفاظ بالمستخدمين لكل النشاط

مسار API هو POST /api/telemetry/analytics/retention. لقياس الاحتفاظ بالمستخدمين دون أسماء أحداث، أرسل response_version بالقيمة 2 واحذف start_event وreturn_event:

curl -sS "https://api.logbrew.co/api/telemetry/analytics/retention" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "since": "14d",
    "response_version": 2,
    "interval": "day",
    "interval_count": 10,
    "mode": "return_on",
    "cohort_mode": "first_in_range"
  }'

تضبط الاستجابة query.activity_scope على all_classified_activity. أي مشاهدة صفحة أو مشاهدة شاشة أو تفاعل لاحق يُحسب عودة. لاختيار أحداث، احذف response_version وأرسل start_event وreturn_event كليهما بالشكل { "kind": "page_view", "event_name": "/signup" }. ناتج قسمة النطاق على الفاصل الزمني، مضروبًا في interval_count، يجب أن يكون 500 أو أقل. مثلًا، 14 يومًا مع day و10 فترات تساوي 140. إذا حذفت interval، فسيستخدم API القيمة hour للنطاقات حتى 48 ساعة، وday للنطاقات الأطول.

اقرأ دورة الحياة

تضع دورة الحياة المستخدمين معروفي الهوية الذين نفّذوا حدثًا واحدًا في مجموعة واحدة لكل فترة:

logbrew analytics lifecycle --project "<project_id>" --since 30d \
  --event-kind interaction --event report_opened \
  --json

المجموعة	المعنى
جديد ضمن التاريخ المرصود	نشط الآن، وليس له حدث سابق ضمن التاريخ المرصود.
عائد	نشط الآن وفي الفترة السابقة.
مستعاد	نشط الآن بعد انقطاع.
خامل	نشط في الفترة السابقة، لكنه غير نشط الآن.

«جديد ضمن التاريخ المرصود» لا يعني عميلًا لأول مرة. قد يقع نشاط سابق خارج التاريخ المرصود، الذي تحدده باستخدام --history-periods. لا تجمع مجاميع الفترات لعدّ المستخدمين الفريدين عبر النطاق. تتراوح --history-periods من 2 إلى 31 فترة قبل since. القيمة الافتراضية 2. لا يمكن أن يزيد التاريخ المرصود على 62 يومًا. يمكن أن يحتوي النطاق على 100 فترة على الأكثر. لكل فترة الحقل fully_observed، وقيمته false عندما لا تكون الفترة قد انتهت. «خامل» يعني غير نشط في الفترة الحالية، لا مفقودًا بشكل دائم. مسار API هو POST /api/telemetry/analytics/lifecycle. لاستخدام كل النشاط المصنَّف بدل حدث واحد، أرسل response_version بالقيمة 2 واحذف event:

{
  "project_id": "<project_id>",
  "since": "30d",
  "response_version": 2,
  "interval": "day",
  "history_period_count": 7
}

قارن بين فترتين

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

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

عندما تشير نتيجة إلى فشل، اقرأ المشكلات والسجلات المرتبطة للمشروع والوقت نفسيهما. افتح تتبّعًا فقط عندما يكون للحدث رابط تتبّع مطابق تمامًا. النطاق الزمني المشترك لا يثبت أن خطأً تسبب في الانخفاض. لتكرار مقارنة، دوّن معرّف المشروع ونطاقي UTC كليهما والفاصل الزمني وعوامل التصفية والوحدة والتغطية وحالات الاقتطاع. لا تدوّن معرّفات المستخدمين الخام. لحقول الاستجابة والأخطاء، اقرأ Telemetry API وأخطاء API.

البدء

المفاهيم

التثبيت والإرسال

التحقيق

CLI والوكلاء

الدعم

ما تحليلات المنتج؟ المقاييس وعودة المستخدمين

الأحداث والمستخدمون والجلسات

افتح نظرة عامة في لوحة التحكم

اقرأ النظرة العامة للمشروع

افصل بين مجموعتي النشاط

اتّبع الإجراء التالي

استدعِ API مباشرةً

قِس قمع التحويل

استكشف المسارات حول حدث واحد

اقرأ الاحتفاظ بالمستخدمين

اطلب الاحتفاظ بالمستخدمين لكل النشاط

اقرأ دورة الحياة

قارن بين فترتين

​الأحداث والمستخدمون والجلسات

​افتح نظرة عامة في لوحة التحكم

​اقرأ النظرة العامة للمشروع

​افصل بين مجموعتي النشاط

​اتّبع الإجراء التالي

​استدعِ API مباشرةً

​قِس قمع التحويل

​استكشف المسارات حول حدث واحد

​اقرأ الاحتفاظ بالمستخدمين

​اطلب الاحتفاظ بالمستخدمين لكل النشاط

​اقرأ دورة الحياة

​قارن بين فترتين

الأحداث والمستخدمون والجلسات

افتح نظرة عامة في لوحة التحكم

اقرأ النظرة العامة للمشروع

افصل بين مجموعتي النشاط

اتّبع الإجراء التالي

استدعِ API مباشرةً

قِس قمع التحويل

استكشف المسارات حول حدث واحد

اقرأ الاحتفاظ بالمستخدمين

اطلب الاحتفاظ بالمستخدمين لكل النشاط

اقرأ دورة الحياة

قارن بين فترتين