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

# التحليلات والأحداث

> أرسل أحداث اللعب وافهم لاعبيك.

export const Scope = ({children}) => <Info>
    <b>النطاق:</b> {children}
  </Info>;

تستقبل Flock **الأحداث** من لعبتك وتحوّلها إلى تحليلات — التفاعل، والاحتفاظ باللاعبين، وتحقيق
الدخل، وغير ذلك.

<Scope>تُجمَّع الأحداث والتحليلات لكل **لعبة**.</Scope>

<Tabs>
  <Tab title="لوحة التحكم">
    اطّلع على لوحات التفاعل والاحتفاظ وتحقيق الدخل داخل Flock — وهي مبنيّة على الأحداث
    والمعاملات التي تبلّغ عنها لعبتك.

    <Frame caption="لوحات التفاعل والاحتفاظ وتحقيق الدخل في Flock.">
      <img src="https://mintcdn.com/qwacks/TGGmq_oWzDacAqHl/images/guides/analytics.png?fit=max&auto=format&n=TGGmq_oWzDacAqHl&q=85&s=6989a90273f294de969e66c05ac9e67a" alt="لوحات التحليلات" width="1366" height="636" data-path="images/guides/analytics.png" />
    </Frame>
  </Tab>

  <Tab title="Unity">
    أرسل الأحداث عبر حزمة التطوير أثناء لعب اللاعبين — إتمام مرحلة، أو عملية شراء، أو محطّة في
    الجلسة. واستدعاءات التسجيل **متزامنة ولا تعطّل اللعب أبدًا**: فهي تضع الحدث في طابور على
    القرص، ثم تتولّى حزمة التطوير تجميع الأحداث وتسليمها نيابةً عنك.

    ```csharp theme={null}
    FlockClient.Instance.Analytics.LogEvent("level_complete", new Dictionary<string, object>
    {
        { "level", 3 },
        { "duration_s", 92 }
    });

    // Optional: await delivery of everything queued (before a critical moment)
    await FlockClient.Instance.Analytics.FlushAsync();
    ```

    وللجلسات ومشاهدات الشاشات ومعاملات الشراء استدعاءات مخصّصة كذلك
    (`RecordScreenView` و`RecordTransactionAsync`).
  </Tab>

  <Tab title="Unreal">
    عقد *Flock | Analytics* لا تحتاج إلى طرف Target، وهي آمنة ولا تفعل شيئًا قبل تهيئة حزمة
    التطوير. وتبدأ الجلسات وتنتهي تلقائيًا حول تسجيل الدخول.

    <Frame caption="سجّل حدثًا وابنِ بياناته الوصفية عبر عقد بناء متسلسلة.">
      <img src="https://mintcdn.com/qwacks/xJEjgQCFVIWLhvHB/images/sdk/unreal/analytics-log-event.png?fit=max&auto=format&n=xJEjgQCFVIWLhvHB&q=85&s=3c719ec5406690550730bc465a029a4f" alt="عقدة Flock Log Event مع عقد بناء بيانات وصفية متسلسلة" width="666" height="343" data-path="images/sdk/unreal/analytics-log-event.png" />
    </Frame>

    ```cpp theme={null}
    Sdk->LogAnalyticsEvent(TEXT("level_complete"),
        FFlockMetadata().Add(TEXT("level"), 3).Add(TEXT("flawless"), true));
    ```

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

    وتبلّغ المشتريات عن معاملاتها تلقائيًا، ويتوقّف كل ما سبق عند إلغاء تحديد
    **Analytics Enabled**.
  </Tab>
</Tabs>

<h2 id="unexpected-termination-detection">
  كشف الإنهاء غير المتوقّع
</h2>

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

| الخاصية                     | المعنى                                                                                                            |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `classification`            | `background_kill` (أُنهيت وهي في الخلفية — أمر طبيعي على الهواتف) أو `abnormal` (توقّفت وهي في المقدّمة دون خروج) |
| `previous_session_id`       | الجلسة التي توقّفت                                                                                                |
| `last_alive_at`             | الوقت التقريبي للتوقّف                                                                                            |
| `unhandled_exception_count` | الاستثناءات التي ظهرت في ذلك التشغيل — سياق مساعد، لا دليل على انهيار                                             |

<Tip>
  راقب معدّل `abnormal` لكل إصدار لعبة — فقفزته بعد إطلاق نسخة هي أبكر إشارة تصلك عن استقرار
  اللعبة، دون الحاجة إلى أداة تقارير انهيار. أما إغلاق اللعبة بشكل طبيعي (الخروج من داخل
  اللعبة، أو Alt-F4، أو إزاحة التطبيق) فلا يُحتسب `abnormal` أبدًا.
</Tip>

<Tip>
  تتبّع أحداثًا ذات معنى وبأسماء واضحة، مع مجموعة صغيرة من الخصائص. فتوحيد أسماء الأحداث يجعل
  قراءة اللوحات أسهل بكثير.
</Tip>