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

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

النطاق: تُجمَّع الأحداث والتحليلات لكل لعبة.

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

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

التحليلات

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

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

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

تبدأ الجلسات وتنتهي تلقائيًا حول تسجيل الدخول. وتخبرك مشاهدات الشاشات أين يقضي اللاعبون وقتهم، والمشتريات التي تمرّ عبر Flock تُبلغ عن معاملاتها بنفسها دون أي استدعاء منك. وأحداث اللعب — مرحلة اكتملت، أو عنصر شوهد — تمرّ عبر TrackEvent، لا عبر قيد سجلّ أبدًا. وتعمل الأمثلة داخل دالة async؛ وreceiptId يمثّل إيصال متجرك أنت.

using System.Collections.Generic;
using Flock;
using Flock.Analytics;

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

// حدث لعب، مع خصائص تستطيع اللوحات رسمها. قيمته false حين يُرفض
// (لا موافقة، أو اسم فارغ أو محجوز)؛ ويذكر الـ Console السبب.
bool tracked = FlockClient.Instance.Analytics.TrackEvent("level_complete",
    new Dictionary<string, object> { { "level", 3 }, { "flawless", true } }, "progression");

// شراء لم تُجرِه Flock (متجرك أنت، مثلًا): سجّل معاملته بنفسك.
await FlockClient.Instance.Analytics.RecordTransactionAsync(4.99, "USD",
    paymentProvider: "my_store", externalTransactionId: receiptId);

// اختياري: انتظر تسليم كل ما في الطابور (قبل لحظة حرجة).
// تَعُدّ النتيجة ما أُرسل وما رفضه الخادم نهائيًا.
FlockFlushResult flushed = await FlockClient.Instance.Analytics.FlushAsync();

تُكتب الأحداث على القرص وتُسلَّم ما دام لاعب مسجَّل الدخول. ولا تسجّل بنفسك أبدًا شراءً تمّ عبر متجر Flock: فهو مُبلَغ عنه بالفعل، وسيُحسب مرّتين. وكل ما هنا متوقّف حين يُلغى تحديد Analytics Enabled (تبويب Advanced Settings).طلب الموافقة. لتسأل اللاعب قبل التتبّع، حدّد Analytics Require Explicit Consent (تبويب Advanced Settings، Analytics Settings): فلا يُتتبَّع شيء حتى تسجّل لعبتك الجواب. ويُحفظ الجواب عبر مرّات التشغيل.

using Flock;

// من أزرار شاشة الموافقة لديك.
FlockClient.Instance.Analytics.SetConsent(true);    // وافق: يبدأ التتبّع.
FlockClient.Instance.Analytics.SetConsent(false);   // رفض أو سحب موافقته: يتوقّف التتبّع.

bool tracking = FlockClient.Instance.Analytics.HasConsent;

وسحب الموافقة لا يحذف ما بقي في الطابور على الجهاز؛ بل يحذفه EraseLocalAnalyticsData(). وتُسجَّل المعاملات في الحالتين، إذ تُحفظ من أجل الشراء نفسه.

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

حدث مخصّص Level Completed، ثم Make Flock Event Properties، ثم Flock Event Property (Integer) بالقيمة stars مساوية 3، ثم Flock Track Event باسم level_completed مع تلك الخصائص — تتبّع حدث لعب بخاصية رقمية تستطيع اللوحات رسمها.

#include "FlockSubsystem.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

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

استدعاءات السجلّ متزامنة ولا تعطّل اللعب أبدًا: إذ تُضاف إلى مخزن مؤقّت على القرص، وتتولّى الحزمة تجميعها وتسليمها نيابةً عنك. والاستثناءات التي لا يلتقطها أحد تُلتقط لك (Analytics Capture Exceptions، تبويب Advanced Settings، Exceptions). وLoadSaveFile يمثّل شيفرتك أنت.

using System;
using System.Collections.Generic;
using Flock;

// تصحيح: Diagnostics → Events
FlockClient.Instance.Analytics.LogDiagnosticEvent("matchmaking started",
    new Dictionary<string, object> { { "queue", "ranked" } });

// خطأ: شيء خاطئ لم يرمِ استثناءً، مع رمزك أنت والفحص الذي أخفق
FlockClient.Instance.Analytics.LogDiagnosticError("quest ended with no reward",
    logicalExpression: "rewards.Count > 0", errorCode: "QUEST_NO_REWARD",
    errorData: new Dictionary<string, object> { { "quest", "q_17" } });

// استثناء: إخفاق التقطته
try
{
    LoadSaveFile();
}
catch (Exception ex)
{
    FlockClient.Instance.Analytics.LogDiagnosticException(ex);
}

وكانت هذه تُسمّى LogEvent وLogError وLogException من قبل؛ ولا تزال الأسماء القديمة تُترجم، مع تحذير يذكر الأسماء الجديدة.

حدث مخصّص Level Loaded موصول بـ Flock Log Diagnostic Event برسالة Loaded the forest level — سجّل مدخل تشخيص: رسالته Message، وبياناته الإضافية Extra Data المبنية بعُقد Flock Metadata حين يحتاج إليها.

#include "FlockSubsystem.h"
#include "Analytics/FlockMetadata.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

Sdk->LogDiagnosticEvent(TEXT("matchmaking started"),
    FFlockMetadata().Add(TEXT("queue"), TEXT("ranked")));

FFlockLogDetails Details;
Details.ErrorCode = TEXT("QUEST_NO_REWARD");                // your own code for this fault
Details.LogicalExpression = TEXT("Rewards.Num() > 0");     // the check that failed
Details.ErrorData = FFlockMetadata().Add(TEXT("quest"), TEXT("q_17")).Values;   // what was wrong
Sdk->LogDiagnosticError(TEXT("quest ended with no reward"), Details);

تصف FFlockLogDetails خطأً أو استثناءً: ErrorCode وLogicalExpression (رمزك الخاص والتحقّق الذي فشل)، وErrorData (ما الذي كان خاطئًا) وExtraData (أين كان اللاعب).يعود التسجيل فورًا: تُكتب المدخلات على القرص وتُسلَّم لاحقًا، فيكون الاستدعاء زهيد التكلفة ولا يضيع شيء بسبب انهيار أو شبكة معطّلة. أمّا التشغيل الذي ينتهي دون خروج نظيف فيُبلَّغ عنه في التشغيل التالي.وهذه العُقد تقع تحت 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 أبدًا.

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

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

المفاهيم

الميزات

المرجع

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

التحليلات

الجلسات

أحداث السجل

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

​التحليلات

​الجلسات

​أحداث السجل

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

التحليلات

الجلسات

أحداث السجل

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