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

تبلّغ لعبتك Flock عبر سطحين منفصلين. كلٌّ منهما يجيب عن سؤال مختلف، ويقرأه أشخاص مختلفون، ويظهر على لوحة مختلفة. واختيار السطح الخطأ يضع بياناتك في مكان حقيقي لكنه عديم الفائدة — لذا تستحق هذه الدقيقتان أن تُقضى الآن.

	التحليلات (Analytics)	أحداث السجل (Log events)
تجيب عن	ماذا فعل اللاعبون؟	ما الذي أخفق؟
يقرأها	التصميم والمنتج وفريق التشغيل	الهندسة
تشمل	الجلسات، ومشاهدات الشاشات، والمعاملات	مدخلات التتبّع، والأخطاء المنطقية، والاستثناءات
أين تقرأها	Dashboards → Game Metrics	Diagnostics → Events و Diagnostics → Errors

الانهيار ليس خطوة في مسار اللعب. وإرساله عبر السطح الآخر لا يفشل ولا يُصدر تحذيرًا — بل يُقبل المدخل ويُخزَّن ويُعرض على لوحة لم يكن أحد ينظر إليها.

التحليلات

التفاعل والاحتفاظ باللاعبين وتحقيق الدخل، مبنيّة على الجلسات ومشاهدات الشاشات والمعاملات التي تبلّغ عنها لعبتك. تُقرأ في Dashboards → Game Metrics.

لوحة التحكم
Unity
Unreal

لوحات التحليلات — لوحات التفاعل والاحتفاظ وتحقيق الدخل في Flock.

تبدأ الجلسات وتنتهي تلقائيًا حول تسجيل الدخول. وتخبرك مشاهدات الشاشات أين يقضي اللاعبون وقتهم، بينما تبلّغ عمليات الشراء عن معاملاتها بنفسها دون أي استدعاء منك.

FlockClient.Instance.Analytics.RecordScreenView("shop");

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

كل ما هنا يتوقّف عند تعطيل التحليلات في إعداداتك، ويحترم قرار موافقة اللاعب في الألعاب التي تطلبها.

عُقد Flock | Analytics لا تحتاج إلى دبوس Target، وهي آمنة ولا تفعل شيئًا قبل تهيئة حزمة التطوير. وتبدأ الجلسات وتنتهي تلقائيًا حول تسجيل الدخول، وتبلّغ عمليات الشراء عن معاملاتها بنفسها. أمّا أحداث اللعب — إتمام مرحلة، أو مشاهدة عنصر — فتمرّ عبر Flock Track Event (TrackAnalyticsEvent)، لا عبر مدخل سجل أبدًا؛ فمدخلات السجل صارت في درج خاص بها هو Flock | Diagnostics.وابنِ خصائص الحدث بعُقد Flock Event Property، فهي تُبقي الرقم رقمًا كي تتمكّن اللوحات من رسمه.

Sdk->RecordAnalyticsScreenView(TEXT("shop"));
Sdk->TrackAnalyticsEvent(TEXT("level_complete"),
    FFlockCommandData().Set(TEXT("level"), 3).Set(TEXT("flawless"), true), TEXT("progression"));

تُكتب الأحداث على القرص وتُسلَّم ما دام لاعب مسجّلًا دخوله؛ والحدث الذي يُسجَّل قبل أن يسجّل أحد دخوله يُنسَب إلى أول من يسجّل الدخول بعده. وكل ما هنا يتوقّف عند إلغاء تحديد Analytics Enabled.

الجلسات

الجلسة هي الوحدة التي يُنسَب إليها كل شيء آخر، وحزمة التطوير تدير دورة حياتها كاملةً نيابةً عنك.


تبدأ	عند تسجيل الدخول لا عند الإقلاع — فالجلسة تخصّ لاعبًا، ولا يوجد قبل ذلك من تُنسَب إليه
تنتهي	عند تسجيل الخروج، وعند الخروج من اللعبة، وعند انتهاء المهلة
الانتقال إلى الخلفية	لا ينهي الجلسة — بل يوقفها مؤقتًا، والوقت المقضيّ في الخلفية لا يُحتسب وقت لعب
المهلة	اللاعب الذي يعود بعد غياب أطول من إعداد مهلة الجلسة (30 ثانية افتراضيًا) يحصل على جلسة جديدة، وتُغلق الجلسة القديمة

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

الجلسات مرتبطة بتسجيل الدخول، فالجهاز المشترك يُبلِّغ عن جلسة لكل لاعب لا عن جلسة لكل تشغيل. وتسجيل الخروج يُغلق الجلسة قبل أن يبدأ اللاعب التالي جلسته.

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

أحداث السجل

تشخيصات للمطوّرين، في ثلاث فئات بالضبط. والفئة التي تختارها هي ما يحدّد مكان ظهور المدخل.

الفئة	تظهر في	استخدمها لـ
Debug	Diagnostics → Events	التتبّع والسياق — أمور ليست أعطالًا
Error	Diagnostics → Errors	خطأ وقع دون أن يرفع استثناءً
Exception	Diagnostics → Errors	إخفاق تم التقاطه، مع أثر المكدّس

هذه للتشخيص لا للّعب. فإتمام مرحلة يُسجَّل كمدخل Debug ينتهي في Diagnostics → Events، حيث لن يجده أحد ممّن يبنون مخطّط احتفاظ باللاعبين — ولن يظهر في Game Metrics إطلاقًا.

Unity
Unreal

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

FlockClient.Instance.Analytics.LogEvent("matchmaking started");        // debug
FlockClient.Instance.Analytics.LogError("quest ended with no reward"); // logic error
FlockClient.Instance.Analytics.LogException(ex);                       // exception

عقدة Flock Log Diagnostic Event مع بنّائي بيانات وصفية متسلسلين — سجّل مدخلًا وابنِ بياناته الوصفية بعُقد بنّاء متسلسلة.

Sdk->LogDiagnosticEvent(TEXT("matchmaking started"),
    FFlockMetadata().Add(TEXT("queue"), TEXT("ranked")));
Sdk->LogDiagnosticError(TEXT("quest ended with no reward"), Details);

يعود التسجيل فورًا: تُكتب المدخلات على القرص وتُسلَّم لاحقًا، فيكون الاستدعاء زهيد التكلفة ولا يضيع شيء بسبب انهيار أو شبكة معطّلة. أمّا التشغيل الذي ينتهي دون خروج نظيف فيُبلَّغ عنه في التشغيل التالي.وهذه العُقد تقع تحت Flock | Diagnostics، بعيدًا عن عُقد التحليلات، وبياناتها الإضافية خريطة نصوص تُبنى بعُقد Flock Metadata. وكان اسمها Flock Log Event وError وException (LogAnalyticsEvent وأخواتها) قبل الإصدار 1.21.0 من حزمة التطوير؛ والأسماء القديمة ما زالت تعمل، والمحرّر يدلّ على الجديدة.

اكتشاف الإنهاء غير المتوقّع

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

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

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

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

بدء الاستخدام

المفاهيم

حزم التطوير

الميزات

المرجع

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

التحليلات

الجلسات

أحداث السجل

اكتشاف الإنهاء غير المتوقّع

​التحليلات

​الجلسات

​أحداث السجل

​اكتشاف الإنهاء غير المتوقّع

التحليلات

الجلسات

أحداث السجل

اكتشاف الإنهاء غير المتوقّع