مستندات

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

پاسخ کارشناسان و کمپین‌ها را حتی وقتی اپلیکیشن بسته است برسانید، همراه با یک 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 آن در پنل مدیریت به کانال اپلیکیشن خود اضافه کنید: Settings › Channels › Mobile SDK، بخش Mobile push. 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);
}