الإشعارات

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

النطاق: تُحدَّد القوالب والحملات لكل لعبة، أما صندوق الوارد فلكل لاعب.

لوحة التحكم
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، فإن رموز الأجهزة تُسجَّل بنجاح ولا يُسلَّم شيء البتة على تلك المنصّة. وهذا هو السبب الأشيع وراء «الإشعارات الفورية لا تعمل» — فجانب العميل يبلّغ بالنجاح لأن التسجيل نجح فعلًا.

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

using Flock;
using Flock.Models;
using UnityEngine;

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

// علّم أحدث إشعار مقروءًا، ثم كل الإشعارات.
if (inbox.Items.Length > 0)
    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، ومن ثمّ لا تستطيع حزمة التطوير شحنه كاعتمادية ولا تحاول ذلك عمدًا.
ما عدا ذلك (الحاسب المكتبي وأجهزة الكونسول والمحرّر) — يرمي الاستدعاءان استثناءً، لأن خادم الإشعارات الفورية لا قيمة لديه لتلك المنصّات.

using Flock;
using UnityEngine;

// iOS: تطلب الإذن وتسجّل رمز APNs في استدعاء واحد.
if (Application.platform == RuntimePlatform.IPhonePlayer)
    await FlockClient.Instance.Notification.RegisterThisDeviceAsync();

// Android: رمز FCM الذي تلقّته شيفرة Firebase للمراسلة لديك.
if (Application.platform == RuntimePlatform.Android)
    await FlockClient.Instance.Notification.RegisterDeviceTokenAsync(fcmToken);

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

using System;
using Flock;
using Flock.Models;

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

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

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

using Flock;
using Flock.Models;
using UnityEngine;

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 مرة واحدة لكل إشعار لم تعرضه حزمة التطوير من قبل، من الأقدم إلى الأحدث. وهو يعتمد على عمليات الجلب التي تجريها لعبتك أصلًا ولا يضيف أي حركة شبكية — إذ لا توجد قناة لحظية، وحزمة التطوير لا تستقصي عمدًا.

using Flock;
using Flock.Models;
using UnityEngine;

public class InboxBadge : MonoBehaviour
{
    private void OnEnable() => FlockEvents.OnNotificationReceived += ShowToast;
    private void OnDisable() => FlockEvents.OnNotificationReceived -= ShowToast;

    private void ShowToast(Notification notification)
    {
        Debug.Log($"New notification: {notification.Title}");
    }
}

#include "FlockSubsystem.h"

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

Notifications->GetNotifications([](TFlockResult<FFlockNotificationPage> Page)
{
    // Page.Value.Total is the whole inbox; Page.Value.Items is this page.
});

Notifications->GetSummary([](TFlockResult<FFlockNotificationSummary> Summary)
{
    // Summary.Value.UnreadCount, plus the newest few in Summary.Value.Items.
});

// NotificationId: an item's Id from the page.
Notifications->MarkRead(NotificationId, nullptr);
Notifications->MarkAllRead(nullptr);

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

// Token: the string your push plugin hands you.
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 عند وصولهما، وإنما مصدر النص فقط.

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

const TWeakObjectPtr<UFlockSubsystem> Flock = UFlockSubsystem::Get(this);

Flock->GetNotificationProvider()->ScheduleByTemplateName(TEXT("energy_refilled"),
    FDateTime::UtcNow() + FTimespan::FromHours(4),
    [Flock](TFlockResult<FFlockScheduledNotification> Pending)
    {
        // The player came back first: cancel it with the id the schedule returned.
        if (Pending.bSuccess && Flock.IsValid())
        {
            Flock->GetNotificationProvider()->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 كل تكرار في الإطار نفسه، ويعيد كل إلغاء كتابة قائمة الانتظار المخزَّنة عند اكتماله — فتتسابق عمليات الإلغاء، ويعيد آخرها انتهاءً إدخالاتٍ سبق أن أزالها غيره. أما العقدة المخصّصة فتمشي عليها بالتتابع لهذا السبب بالذات.

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

// In AMyActor's class, each handler is a UFUNCTION():
//   void HandleNotification(const FFlockNotification& Notification);
//   void HandleUnreadCount(int32 UnreadCount);
UFlockEvents* Events = UFlockSubsystem::Get(this)->GetEvents();
Events->OnNotificationReceived.AddDynamic(this, &AMyActor::HandleNotification);
Events->OnUnreadCountChanged.AddDynamic(this, &AMyActor::HandleUnreadCount);

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

يشغّل Event BeginPlay العقدة Bind Event to On Unread Count Changed، وهدفها Flock Get Events (عقدة بلا منافذ تنفيذ)، مربوطةً بحدث مخصّص Unread Changed يُحوَّل Unread Count فيه إلى نص (عقدة تحويل صغيرة) ويذهب إلى Print String — أبقِ شارة غير المقروء محدَّثة: اربط On Unread Count Changed مرة واحدة، عند Begin Play.

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.

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

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

المفاهيم

الميزات

المرجع

الإشعارات