إشعارات اللعبة

إشعارات اللعبة تتيح لك مخاطبة لاعبيك: الإعلان عن فعالية، أو الاحتفاء بإنجاز، أو استعادة مجموعة انقطعت عن اللعب. تكتب الرسالة مرة واحدة على هيئة قالب، وترسلها عبر حملة، فيستلمها اللاعبون على القنوات التي اخترتها — صندوق الوارد داخل اللعبة، أو البريد الإلكتروني، أو الإشعارات الفورية.

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

تجد الإشعارات ضمن التسويق:

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

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

Firebase Cloud Messaging (FCM) — تُسلِّم إلى Android والويب. الصق كامل محتوى ملف حساب الخدمة (service-account JSON) من Firebase.
Apple Push Notification service (APNs) — تُسلِّم إلى iOS. زوّدها بمفتاح التوقيع .p8، وKey ID الخاص به، وTeam ID لفريقك، وBundle ID للتطبيق. وفعّل Use APNs sandbox لإصدارات التطوير؛ إذ لا يقبل رمز البيئة التجريبية بيانات اعتماد الإنتاج، ولا العكس.

وما لم يظهر المزوّد بحالة Configured، فإن رموز الأجهزة تُسجَّل بنجاح ولا يُسلَّم شيء البتة على تلك المنصّة. وهذا هو السبب الأشيع وراء «الإشعارات الفورية لا تعمل» — فجانب العميل يبلّغ بالنجاح لأن التسجيل نجح فعلًا.

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

PaginatedResponse<Notification> inbox = await FlockClient.Instance.Notification.GetInboxAsync();
NotificationSummary summary = await FlockClient.Instance.Notification.GetSummaryAsync();
Debug.Log($"{summary.UnreadCount} unread");

await FlockClient.Instance.Notification.MarkReadAsync(inbox.Items[0]);
await FlockClient.Instance.Notification.MarkAllReadAsync();

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

iOS — تطلب RegisterThisDeviceAsync() إذن الإشعارات من النظام وتسجّل رمز APNs الناتج في استدعاء واحد. وتتطلّب وجود com.unity.mobile.notifications في المشروع.
Android — احصل على رمز FCM من Firebase بنفسك، ثم مرّره إلى RegisterDeviceTokenAsync(token). فعميل Firebase للمراسلة غير قابل للتثبيت عبر UPM، ومن ثمّ لا تستطيع حزمة التطوير شحنه كاعتمادية ولا تحاول ذلك عمدًا.
ما عدا ذلك (الحاسب المكتبي وأجهزة الكونسول والمحرّر) — يرمي الاستدعاءان استثناءً، لأن خادم الإشعارات الفورية لا قيمة لديه لتلك المنصّات.

وأعد التسجيل كلما أصدر النظام رمزًا جديدًا. وتزيل UnregisterDeviceTokenAsync رمزًا مسجَّلًا.تذكيرات تجدولها اللعبة بنفسها. جدوِل قالبًا ليصل لاحقًا — «امتلأت الطاقة بعد ٤ ساعات» — وألغِه إن عاد اللاعب قبل ذلك.

ScheduledNotification pending = await FlockClient.Instance.Notification.ScheduleAsync(
    "energy_refilled", TimeSpan.FromHours(4));

await FlockClient.Instance.Notification.CancelScheduledAsync(pending);

والوسيط الأول هو اسم القالب لا معرّفه. مرّر variables لملء عناصر القالب النائبة، وchannels لحصر قنوات التسليم، وlocale لاختيار لغة بعينها. أما الاسم غير المعروف فيرمي FlockErrorCode.NotificationTemplateNotFound قبل أن يُجدول أي شيء.ما لدى اللاعب من تذكيرات معلّقة. تسأل GetScheduledAsync() الخادمَ، فترى بذلك التذكيرات التي ضُبطت قبل إعادة التثبيت أو على جهاز اللاعب الآخر — لا ما أنشأته هذه النسخة وحدها.

PaginatedResponse<ScheduledNotification> pending =
    await FlockClient.Instance.Notification.GetScheduledAsync();

foreach (ScheduledNotification s in pending.Items)
    Debug.Log($"{s.Id} delivers at {s.DeliverAt}");

// تلغي كل تذكير معلّق لدى اللاعب، أيًّا كان مكان ضبطه.
int cancelled = await FlockClient.Instance.Notification.CancelAllScheduledAsync();

والحالة الافتراضية هي المعلّقة؛ مرّر ScheduledNotificationStatuses.Delivered أو .Canceled لعرض غيرها. وتبقى GetPendingSchedules() بديلًا متزامنًا لا يحتاج شبكة، يغطّي ما جدولته هذه النسخة — مفيد دون اتصال، لكن فضّل GetScheduledAsync متى أمكن الوصول إلى الخادم.قراءة الكتالوج. تسرد GetTemplatesAsync() القوالب التي يمكن للعبتك جدولتها، وتجلب GetTemplateByNameAsync(name, locale) قالبًا واحدًا. وكلتاهما على نطاق اللعبة لا اللاعب، ولذلك تعملان دون تسجيل دخول بخلاف بقية هذا المزوّد.التفاعل مع الوصول. يُطلَق FlockEvents.OnNotificationReceived مرة واحدة لكل إشعار لم تعرضه حزمة التطوير من قبل، من الأقدم إلى الأحدث. وهو يعتمد على عمليات الجلب التي تجريها لعبتك أصلًا ولا يضيف أي حركة شبكية — إذ لا توجد قناة لحظية، وحزمة التطوير لا تستقصي عمدًا.

FFlockNotificationProvider* Notifications = UFlockSubsystem::Get(this)->GetNotificationProvider();

Notifications->GetNotifications([](TFlockResult<FFlockNotificationPage> Page)
{
    // Page.Value.Total هو صندوق الوارد كاملًا، و Page.Value.Items هي هذه الصفحة.
});

Notifications->GetSummary([](TFlockResult<FFlockNotificationSummary> Summary)
{
    // Summary.Value.UnreadCount ومعه أحدث بضعة عناصر في Summary.Value.Items.
});

Notifications->MarkRead(NotificationId, nullptr);
Notifications->MarkAllRead(nullptr);

وتُعيد GetSummary عدد غير المقروء مع أحدث بضعة عناصر، فتحصل على الشارة والمعاينة باستدعاء واحد. وفضّلها على إعادة جلب صندوق الوارد كاملًا على فترات — فقراءات صندوق الوارد تُحتسب ضمن استخدام خطتك للواجهة البرمجية شأنها شأن أي استدعاء آخر.وقراءات صندوق الوارد مدعومة بالتخزين المؤقت دون اتصال، فتعرض شاشة الإشعارات آخر الرسائل المعروفة عند انقطاع الشبكة بدل رسالة خطأ. أما استدعاءات وضع العلامة كمقروء فلا تُصفّ أبدًا للإرسال لاحقًا: فإيصال قراءة يُعاد إرساله بعد ساعة سيضع علامة مقروء على رسائل لم يرها اللاعب.الإشعارات الفورية. تسجّل حزمة التطوير رمز الجهاز ولا تجلبه. احصل على الرمز من إضافة الإشعارات لديك — On Token Received في Firebase Cloud Messaging، أو OneSignal — ومرّر النص:

Notifications->RegisterDeviceToken(Token, [](TFlockResult<FFlockDeviceToken> Result) {});

وتُؤخذ المنصّة من الإصدار قيد التشغيل. أما على الحاسب المكتبي وأجهزة الكونسول وداخل المحرّر فيفشل الاستدعاء بخطأ تحقّق بدل تخمين منصّة — إذ إن الرمز المسجَّل تحت منصّة خاطئة يُقبل ثم لا يُسلَّم أبدًا. استدعِ Flock Get Current Device Platform أولًا لإخفاء خيار «تفعيل الإشعارات» حيث لا تعمل الإشعارات الفورية. وتزيل UnregisterDeviceToken رمزًا مسجَّلًا؛ وأعد التسجيل كلما أصدر النظام رمزًا جديدًا.ويختلف مصدر الرمز باختلاف المنصّة:

iOS — لا تحتاج شيئًا إضافيًا. إذ يوفّر Unreal رمز APNs بنفسه، ويتخاطب Flock مع APNs مباشرةً، فلا وجود لـ Firebase في هذا المسار. اربط FCoreDelegates::ApplicationRegisteredForRemoteNotificationsDelegate، وحوّل البايتات إلى صيغة ست عشرية، ثم مرّر النص.
Android — إضافة قائمة على Firebase، في الوقت الحالي. فإضافة Unreal الخاصة بالإشعارات على Android مبنية على Google Cloud Messaging التي أوقفتها Google عام 2019.

الحصول المدمج على الرمز قيد التطوير — غلاف باستدعاء واحد على iOS وربط أصلي على Android — بحيث لا تحتاج الإشعارات الفورية إلى إضافة خارجية. ولن يتغيّر RegisterDeviceToken عند وصولهما، وإنما مصدر النص فقط.

تذكيرات تجدولها اللعبة بنفسها. جدوِل قالبًا ليصل لاحقًا — «امتلأت الطاقة بعد ٤ ساعات» — وألغِه إن عاد اللاعب قبل ذلك.

Notifications->ScheduleByTemplateName(TEXT("energy_refilled"),
    FDateTime::UtcNow() + FTimespan::FromHours(4),
    [Notifications](TFlockResult<FFlockScheduledNotification> Pending)
    {
        Notifications->CancelScheduled(Pending.Value.Id, nullptr);
    });

والوسيط الأول هو اسم القالب لا معرّفه — إذ يُستخرج المعرّف داخليًا ويُحفظ في الذاكرة. مرّر Variables لملء عناصر القالب النائبة، وChannels لحصر قنوات التسليم؛ واترك أيًّا منهما فارغًا فتُطبَّق إعدادات القالب الافتراضية. أما الاسم غير المعروف فيفشل بخطأ تحقّق قبل أن يُجدول أي شيء.ولا يُعاد إرسال الجدولة بعد إخفاق غامض، حتى لا يترك انقطاع شبكي عابر لدى اللاعب تذكيرين متطابقين. أما الإلغاء فعمليته آمنة التكرار.قراءة الكتالوج. تسرد GetTemplates() القوالب التي يمكن للعبتك جدولتها، وتجلب GetTemplateByName(Name, Locale) قالبًا واحدًا. وكلتاهما على نطاق اللعبة لا اللاعب، ولذلك تعملان دون تسجيل دخول بخلاف بقية هذا المزوّد.ما لدى اللاعب من تذكيرات معلّقة. تسأل GetScheduled() الخادمَ، فترى بذلك التذكيرات التي ضُبطت قبل إعادة التثبيت أو على جهاز اللاعب الآخر — لا ما أنشأته هذه النسخة وحدها.

Notifications->GetScheduled([](TFlockResult<FFlockScheduledNotificationPage> Pending)
{
    for (const FFlockScheduledNotification& Entry : Pending.Value.Items)
    {
        // Entry.Id is what Cancel Scheduled Notification takes.
    }
});

// Cancels every pending reminder the player has, wherever it was set.
Notifications->CancelAllScheduled([](TFlockResult<int32> Result) { /* Result.Value cancelled */ });

والحالة الافتراضية هي «معلّق»؛ ومرّر FlockScheduledNotificationStatuses::Delivered أو ::Canceled لعرض غيرها. وفي Blueprint هذه هي عقدة Flock Get Scheduled Notifications، ويأخذ طرفها Status قيمة «معلّق» افتراضيًا — غذِّه من عقد Flock Schedule Status بدل كتابة القيمة، فالتهجئة على السلك هي canceled بلام واحدة.ولا تُخزَّن القائمة مؤقتًا أبدًا: إذ يُسلَّم التذكير من جهة الخادم دون ما يُعلم العميل، فالصفحة المخزَّنة ستعرض تذكيرًا انطلق فعلًا على أنه ما يزال معلّقًا. وهي تحتاج إلى شبكة وإلى لاعب مسجَّل الدخول.وتبقى GetPendingSchedules() بديلًا متزامنًا لا يحتاج شبكة، يغطّي ما جدولته هذه النسخة — مفيد دون اتصال، لكن فضّل GetScheduled متى أمكن الوصول إلى الخادم. ولا تلجأ CancelAllScheduled إليه إلا عند فشل القراءة من الخادم؛ ولا تُدمج القائمتان أبدًا.وفي Blueprint هذه العقد هي Flock Get Scheduled Notifications وFlock Cancel All Scheduled Notifications وFlock Get Pending Schedules. ويأخذ الطرف Status قيمة «معلّق» افتراضيًا — غذِّه من عقد Flock Schedule Status بدل كتابة القيمة، فالتهجئة على السلك هي canceled بلام واحدة. وعقدة Get Pending Schedules عقدة استدعاء عادية لا غير متزامنة: فهي لا تُجري أي اتصال بالشبكة.

استخدم Flock Cancel All Scheduled Notifications بدل تكرار Flock Cancel Scheduled Notification على قائمة. إذ تُطلق حلقة ForEach في Blueprint كل تكرار في الإطار نفسه، ويعيد كل إلغاء كتابة قائمة الانتظار المخزَّنة عند اكتماله — فتتسابق عمليات الإلغاء، ويعيد آخرها انتهاءً إدخالاتٍ سبق أن أزالها غيره. أما العقدة المخصّصة فتمشي عليها بالتتابع لهذا السبب بالذات.

التفاعل مع الوصول. يوفّر مركز الأحداث حدثين يغنيانك عن مقارنة الصفحات بنفسك:

UFlockEvents* Events = UFlockSubsystem::Get(this)->GetEvents();
Events->OnNotificationReceived.AddDynamic(this, &AMyActor::HandleNotification);
Events->OnUnreadCountChanged.AddDynamic(this, &AMyActor::HandleUnreadCount);

يُطلق OnNotificationReceived مرة واحدة لكل إشعار لم تعرضه الحزمة من قبل، من الأقدم إلى الأحدث. ويُطلق OnUnreadCountChanged كلما أبلغ الخادم بعدد — عند جلب عدد غير المقروء أو الملخّص، أو عند تعليم الكل كمقروء. وكلاهما يعتمد على عمليات الجلب التي تجريها لعبتك أصلًا ولا يضيف أي حركة شبكية: فلا توجد قناة لحظية، والحزمة لا تستطلع الخادم عمدًا، ولذلك يعني «الوصول» أول ظهور في عملية قراءة. وأول عملية جلب بعد تثبيت جديد صامتة، حتى لا يصل صندوق وارد قائم دفعةً واحدة من الأحداث عند الإقلاع.Blueprint. لكل استدعاء أعلاه عقدة — Flock Get Notifications وFlock Get Notification Summary وFlock Mark Notification Read وFlock Schedule Notification وFlock Register Device Token وغيرها — إضافة إلى العقد الصرفة Is Read وIs Pending وIs Delivered وIs Canceled. ويمكن ربط الحدثين مباشرة من Flock Get Events.

هذه الصفحة عن الرسائل الموجَّهة إلى اللاعبين. أما التنبيهات الموجَّهة إلى فريقك أنت — ارتفاع الأخطاء، ونتائج الإصدارات — فهي تنبيهات المطوّرين.

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

المفاهيم

حزم التطوير

الميزات

المرجع

إشعارات اللعبة