التوثيق

الإشعارات الفورية

سلّم ردود موظفي الدعم والحملات بينما يكون التطبيق مغلقاً، مع رابط عميق مباشر إلى المحادثة الصحيحة. يمتلك تطبيقك نظام الدفع الفرعي؛ وتسجّل الحزمة الرموز وتفتح المحادثات.

ما يرسله Respondo#

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

تحمل دفعات الرسائل دائماً رابطاً عميقاً بالصيغة respondo://conversation/<id>. أما دفعات الحملات فتحمل الرابط العميق المضبوط على الحملة — وهو اختياري، وعند عدم ضبطه لا تحتوي الدفعة على رابط عميق.

Apple (APNs)#

يعمل دفع iOS على APNs مباشرة — بلا تبعية على Firebase. من حساب Apple Developer الخاص بك، احصل على:

  • مفتاح مصادقة APNs (مفتاح رمز .p8).
  • الـ Key ID لذلك المفتاح.
  • الـ Team ID الخاص بك.
  • الـ bundle id للتطبيق.

Google (FCM)#

يمر دفع Android عبر Firebase Cloud Messaging. من مشروع Firebase الخاص بك، احصل على:

  • ملف service account JSON بدور Cloud Messaging.
  • الـ Firebase project ID (وحدة تحكم Firebase ← إعدادات المشروع) — يُدخل كحقل مستقل في نموذج الدفع في لوحة التحكّم إلى جانب ملف service account JSON.
  • الـ package name لتطبيق Android، واربط التطبيق بمشروع Firebase نفسه (google-services.json).

الإعداد في Respondo#

أضف مفتاح APNs وحساب خدمة FCM مع معرّف مشروعه إلى قناة الأداة لديك في لوحة التحكّم. هذا كل ما يحتاجه Respondo للإرسال إلى كلتا المنصتين.

ضبط بيانات الاعتماد عبر الـ API والمرجع الكامل للحقول مشمولان في دليل إعداد الدفع المُسلَّم مع وصولك إلى الحزمة.

صيغة الحمولة#

تعيش الحمولة دائماً تحت مفتاح جذر respondo — ووجوده هو الطريقة التي تميّز بها الحزمة دفعها عن غيره (على iOS في userInfo، وعلى Android كسلسلة JSON في data["respondo"]).

respondo payloadjson
{
  "respondo": {
    "type": "message",
    "conversation_id": "a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90",
    "message_id": "e9a3c1f6-4b8d-4e0a-b5f3-1d7b2a4e9c63",
    "deep_link": "respondo://conversation/a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90"
  }
}

جميع القيم سلاسل نصية مسطّحة. يُسلَّم عنوان الإشعار ومتنه عبر نقل المنصة — aps.alert على APNs و message.notification على FCM — لا داخل كائن respondo.

تتضمن دفعات الحملات أيضاً delivery_id يُستخدم للإبلاغ عن منارة الفتح، وقد تحمل مفاتيح نصية مسطّحة إضافية من بيانات الدفع الخاصة بالحملة.

معالجة النقرات والمقدمة#

عند النقر على إشعار، سلّم الحمولة الخام إلى الحزمة. تحلّل الحزمة الحمولة وتفتح المحادثة الصحيحة، وتعيد false إذا لم يكن الدفع دفعَ Respondo (عالجه بنفسك في هذه الحالة).

معالجة نقرة (لكل منصة)text
Android:  RespondoPushPayload.from(data)?.let { Respondo.handlePush(it) }
iOS:      Respondo.handlePush(userInfo: userInfo)
Flutter:  Respondo.handlePushData(message.data)

تُدمَج التكرارات وفق message_id، وبينما تكون المحادثة نفسها مفتوحة في المقدمة يُكبَت إشعار النظام — تعالج الحزمة كليهما تلقائياً.

تسجيل رموز الأجهزة#

يحصل تطبيقك على رمز الجهاز من نظام الدفع الفرعي لديه ويمرّره إلى setPushToken. استدعِ clearPushToken عند تسجيل الخروج.

أي رمز تمرّر. توجّه الخلفية كل تسليم حسب المنصة — iOS يذهب إلى APNs مباشرة، وAndroid يذهب إلى FCM — لذا يجب أن تسجّل رمز النقل الأصلي للمنصة، لا أيًّا كان ما تصادف أن تعيده مكتبة الدفع لديك:
  • Android — رمز تسجيل FCM من FirebaseMessaging.getToken().
  • iOS (الأصلي) — رمز جهاز APNs (ست عشري) من didRegisterForRemoteNotificationsWithDeviceToken.
  • iOS عبر Flutter (firebase_messaging) — استخدم getAPNSToken()، لا getToken(). فتمرير رمز FCM على iOS يرسله إلى APNs، حيث لا يكون رمز جهاز صالحاً ولا تصل الدفعات أبداً. getAPNSToken() قد يكون null في اللحظات الأولى بعد الإطلاق — أعِد المحاولة بعد تأخير قصير إن حدث ذلك.
Android — FirebaseMessagingServicekotlin
override fun onNewToken(token: String) {
    Respondo.setPushToken(token)
}
iOS — AppDelegateswift
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Respondo.setPushToken(token)
}
Flutter — firebase_messagingdart
// يحتاج iOS رمز APNs؛ ويحتاج Android رمز FCM.
final token = Platform.isIOS
    ? await FirebaseMessaging.instance.getAPNSToken()
    : await FirebaseMessaging.instance.getToken();
if (token != null) Respondo.setPushToken(token);

// يدوّر FCM رمز تسجيله؛ أبقِ Android متزامناً.
if (!Platform.isIOS) {
  FirebaseMessaging.instance.onTokenRefresh.listen(Respondo.setPushToken);
}