> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

تعرض تحليلات المنتج كيف يستخدم الناس تطبيقك. يقرأ LogBrew إجراءات المنتج
التي يرسلها تطبيقك، ومنها مشاهدات الصفحات ومشاهدات الشاشات والتفاعلات.
استخدم [التقاط أحداث المنتج](/ar/guides/product-events) لإرسال هذه الأحداث
مع سياق المستخدم والجلسة.

كل نتيجة تخص مشروعًا واحدًا ونطاقًا زمنيًا واحدًا. اسم الخدمة لا يحدد
المشروع. السجلات والمشكلات إشارات منفصلة. وجودها لا يعني وجود بيانات
تحليلات للنطاق نفسه.

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

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

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

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

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

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

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

تعرض لوحة التحكم أيضًا اتجاهين للمستخدمين للمشروع والتواريخ نفسها. يعرض
**هل يعود المستخدمون؟** الاحتفاظ بالمستخدمين. ويعرض **كيف تتغير قاعدة المستخدمين؟**
مجموعات دورة الحياة. يستخدم الاتجاهان كل النشاط المصنَّف للمستخدمين معروفي
الهوية. لا تختار حدثًا لهما.

## <span id="use-the-analytics-api">اقرأ النظرة العامة للمشروع</span>

```bash theme={null}
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`.

تحتوي النظرة العامة على مجاميع النشاط وسلسلة زمنية وأبرز الإجراءات والنشاط
المصنَّف. يعرض هذا المقتطف المجاميع وتغطيتها:

```json theme={null}
{
  "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`.

```bash theme={null}
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`:

```json theme={null}
{
  "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](/ar/reference/api-errors) استجابات الأخطاء
الأخرى.

تأخذ مسارات التحليلات `POST` أدناه نص JSON فيه حقول `project_id` و`since`
و`until` و`service_name` و`release` و`environment` نفسها. تُرفض حقول النص
غير المعروفة.

## <span id="measure-a-funnel">قِس قمع التحويل</span>

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

```bash theme={null}
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`. تعرض
[استجابة قمع التحويل المرتب](/ar/reference/telemetry-response-shapes#ordered-funnel-response)
نص الطلب والاستجابة.

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

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

```bash theme={null}
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`.

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

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

```bash theme={null}
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`:

```bash theme={null}
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`
للنطاقات الأطول.

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

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

```bash theme={null}
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`:

```json theme={null}
{
  "project_id": "<project_id>",
  "since": "30d",
  "response_version": 2,
  "interval": "day",
  "history_period_count": 7
}
```

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

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

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

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

لتكرار مقارنة، دوّن معرّف المشروع ونطاقي UTC كليهما والفاصل الزمني وعوامل
التصفية والوحدة والتغطية وحالات الاقتطاع. لا تدوّن معرّفات المستخدمين الخام.

لحقول الاستجابة والأخطاء، اقرأ
[Telemetry API](/ar/reference/telemetry-api)
و[أخطاء API](/ar/reference/api-errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.