مستندات

نوتیفیکیشن‌های پوش

پاسخ کارشناسان و کمپین‌ها را حتی وقتی اپلیکیشن بسته است برسانید، همراه با یک deep link مستقیم به همان گفت‌وگوی درست. زیرسیستم پوش مال اپلیکیشن شماست؛ SDK توکن‌ها را ثبت می‌کند و گفت‌وگوها را باز می‌کند.

Respondo چه چیزی می‌فرستد#

  • پوش پیام — پاسخ یک کارشناس یا هوش مصنوعی در گفت‌وگویی که بازدیدکننده در آن حضور دارد.
  • پوش کمپین — کمپین‌های پوش خروجی، که یک beacon باز شدن هم گزارش می‌کنند.

پوش‌های پیام همیشه یک deep link به این شکل با خود دارند: respondo://conversation/<id>. پوش کمپین، deep linkِ پیکربندی‌شده روی کمپین را دارد — اختیاری است و اگر تنظیم نشده باشد، پوش هیچ deep link ندارد.

Apple (APNs)#

پوش iOS مستقیم روی APNs کار می‌کند — بدون وابستگی به Firebase. از حساب Apple Developer خود این‌ها را بگیرید:

  • یک APNs Auth Key (کلید توکن .p8).
  • مقدار Key ID همان کلید.
  • مقدار Team ID شما.
  • مقدار bundle id اپلیکیشن.

Google (FCM)#

پوش Android از راه Firebase Cloud Messaging می‌رود. از پروژهٔ Firebase خود این‌ها را بگیرید:

  • یک JSON حساب سرویس با نقش Cloud Messaging.
  • مقدار Firebase project ID (کنسول Firebase ← Project settings) — در فرم پوشِ پنل مدیریت به‌صورت فیلد جداگانه کنار JSON حساب سرویس وارد می‌شود.
  • مقدار package name اپلیکیشن Android، و اپلیکیشن را به همان پروژهٔ Firebase وصل کنید (google-services.json).

پیکربندی در Respondo#

کلید APNs و حساب سرویس FCM را همراه project ID آن در پنل مدیریت به کانال ویجت خود اضافه کنید. Respondo برای فرستادن به هر دو پلتفرم به همین اندازه نیاز دارد.

تنظیم این اعتبارنامه‌ها از راه API و مرجع کامل فیلدها در راهنمای راه‌اندازی پوش آمده است که همراه دسترسی SDK به شما داده می‌شود.

قالب payload#

payload همیشه زیر کلید ریشهٔ respondo می‌نشیند — وجود همین کلید است که به SDK می‌گوید پوش مال خودش است یا نه (در 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 هم دارند که برای گزارش beacon باز شدن به کار می‌رود، و ممکن است کلیدهای رشته‌ای تختِ دیگری از دادهٔ پوش کمپین همراه داشته باشند.

مدیریت ضربه و حالت پیش‌زمینه#

وقتی روی اعلان ضربه زده شد، payload خام را به SDK بدهید. SDK آن را تجزیه می‌کند و گفت‌وگوی درست را باز می‌کند، و اگر پوش متعلق به Respondo نباشد false برمی‌گرداند (در آن صورت خودتان مدیریتش کنید).

مدیریت ضربه (به تفکیک پلتفرم)text
Android:  RespondoPushPayload.from(data)?.let { Respondo.handlePush(it) }
iOS:      Respondo.handlePush(userInfo: userInfo)
Flutter:  Respondo.handlePushData(message.data)

پیام‌های تکراری بر اساس message_id در هم ادغام می‌شوند، و تا وقتی همان گفت‌وگو در پیش‌زمینه باز است اعلان سیستمی نمایش داده نمی‌شود — SDK هر دو را خودکار انجام می‌دهد.

ثبت توکن دستگاه#

اپلیکیشن شما توکن دستگاه را از زیرسیستم پوش خودش می‌گیرد و به setPushToken می‌دهد. هنگام خروج، clearPushToken را صدا بزنید.

کدام توکن را بدهید. backend هر ارسال را بر اساس پلتفرم مسیردهی می‌کند — iOS مستقیم به APNs می‌رود و Android به FCM — پس باید توکن انتقال بومیِ همان پلتفرم را ثبت کنید، نه هر چیزی که کتابخانهٔ پوش شما تحویل می‌دهد:
  • Android — توکن ثبت FCM از FirebaseMessaging.getToken().
  • iOS (بومی) — توکن دستگاه APNs (به‌صورت hex) از 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);
}