إعداد واجهة مستخدم صندوق الوارد لـ Pushwoosh على Android

توفر واجهة مستخدم صندوق الوارد لـ Pushwoosh (Pushwoosh Inbox UI) شاشة صندوق وارد جاهزة للاستخدام على Android (صندوق وارد التطبيق الذي يظهر على شكل “أيقونة الجرس”) فوق الواجهة الخلفية لصندوق الوارد الخاص بـ Pushwoosh. تقوم بعرض الرسائل في واحد من خمسة أنواع من البطاقات، وتدعم أزرار CTA المضمنة، وهي مفتوحة لتخصيص النمط من خلال سمات XML أو الكود.

المتطلبات الأساسية

أن يكون Pushwoosh Android SDK الأساسي مدمجًا بالفعل ويرسل الإشعارات.
دعم Kotlin في وحدة تطبيقك (apply plugin: 'kotlin-android').

إضافة المكتبة

أضف إضافة Kotlin ووحدتي Pushwoosh إلى ملف build.gradle الخاص بتطبيقك:

apply plugin: 'kotlin-android'

dependencies {
    implementation 'com.pushwoosh:pushwoosh-inbox:6.+'
    implementation 'com.pushwoosh:pushwoosh-inbox-ui:6.+'
}

ثبّت إصدار pushwoosh-inbox و pushwoosh-inbox-ui ليكون مطابقًا لإصدار الاعتمادية الحالية com.pushwoosh:pushwoosh. استبدل + بالإصدار الحالي من Pushwoosh Android SDK.

إذا كان تطبيقك يستخدم ProGuard لتقليص حجم الكود، فاحتفظ بفئة إضافة صندوق الوارد:

-keep public class com.pushwoosh.inbox.PushwooshInboxPlugin {
 *;
}

عرض صندوق الوارد

اعرض صندوق الوارد كشاشة مستقلة، أو قم بتضمينه كـ fragment داخل التخطيط الخاص بك.

كنشاط (activity):

startActivity(Intent(this, InboxActivity::class.java))

كجزء (fragment):

supportFragmentManager.beginTransaction()
    .replace(R.id.inboxContainer, PushwooshInboxUi.createInboxFragment())
    .commitAllowingStateLoss()

أنواع البطاقات

تقوم واجهة مستخدم صندوق الوارد بتحديد نوع البطاقة لكل رسالة. يقرأ المحدد displayType من كائن data لحمولة الإشعار، والذي يقدمه SDK تحت actionParams. إن displayType الذي يسمي نوع بطاقة معروفًا يعرض دائمًا هذا النوع، ويعود إلى classic فقط إذا كانت الحقول المطلوبة للنوع مفقودة. لا يعتمد هذا التحديد على الإعداد الاستدلالي أدناه.

عندما يكون displayType غائبًا، يتم عرض الرسالة كصف عادي ما لم تختر استخدام الاستدلال القائم على الصورة/النص:

PushwooshInboxStyle.richCardsHeuristicEnabled = true

مع تشغيل الاستدلال، فإن الصورة بدون عنوان تعرض بطاقة من نوع banner، والصورة مع عنوان ونص تعرض بطاقة من نوع captioned، وأي شيء آخر يعود إلى النوع classic.

`displayType`	المظهر	حقل الحمولة المطلوب	يتحول إلى
`banner`	صورة تملأ العرض، بدون نص	صورة (أيقونة الرسالة أو `data.attachment`)	`classic` عند عدم وجود صورة
`captioned`	صورة في الأعلى، وعنوان + نص في الأسفل	صورة، `title` و `content` للرسالة	`classic` عند فقدان الصورة أو العنوان أو النص
`classic`	أيقونة + عنوان + نص	— (من المتوقع وجود عنوان ونص وأيقونة)	—
`carousel`	معرض صور متعددة قابل للتمرير	`title` و `content` للرسالة، `data.carousel` (من 1 إلى 5 شرائح)	`classic` عند عدم وجود شرائح أو عدم وجود عنوان/نص
`video`	ملصق مع شارة تشغيل، مشغل بملء الشاشة عند النقر	`data.video` (`url` + `poster` اختياري)	`classic` عند عدم وجود واصف

بطاقة Apple Wallet من iOS InboxKit ليس لها نظير على Android. الرسالة التي تحتوي على displayType: "wallet" يتم عرضها دائمًا كـ classic على Android.

بطاقة العرض الدوار (Carousel)

توجد الشرائح في data.carousel. تحتاج كل شريحة إلى image. أما title (تراكب التسمية التوضيحية) و url (يتم فتحه عند النقر) فهما اختياريان. يتم تجاهل الشريحة التي لا تحتوي على صورة، ويتم عرض 5 شرائح على الأكثر.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "content": "Swipe through this week's drops",
      "inbox_days": 7,
      "data": {
        "displayType": "carousel",
        "carousel": [
          { "image": "https://cdn.example.com/inbox/1.jpg", "title": "New in", "url": "myapp://product/1" },
          { "image": "https://cdn.example.com/inbox/2.jpg", "title": "On sale", "url": "myapp://product/2" }
        ]
      },
      "platforms": [3]
    }]
  }
}

بطاقة الفيديو

يوجد الواصف في data.video: url مطلوب، و poster هو صورة معاينة اختيارية. يؤدي النقر على الملصق إلى فتح مشغل بملء الشاشة.

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "content": "Tap to play",
      "inbox_days": 7,
      "data": {
        "displayType": "video",
        "video": {
          "url": "https://cdn.example.com/inbox/clip.mp4",
          "poster": "https://cdn.example.com/inbox/poster.jpg"
        }
      },
      "platforms": [3]
    }]
  }
}

قراءة البيانات المخصصة من رسالة

لجعل إشعار الدفع يظهر في صندوق الوارد، يجب أن يتضمن طلب createMessage في واجهة برمجة تطبيقات الرسائل (Messages API) أحد الحقول التالية: inbox_image، inbox_date، أو inbox_days. بدون أحد هذه الحقول، يتم تسليم الإشعار كإشعار عادي ولا يصل أبدًا إلى موجز صندوق الوارد. يتم وضع البيانات المخصصة حرة الشكل تحت data، والتي يعرضها SDK كـ actionParams على InboxMessage:

PushwooshInboxUi.onMessageClickListener = OnInboxMessageClickListener { message ->
    val params = message.actionParams?.let { JSONObject(it) }
    val promoId = params?.optString("promo_id")
    if (!promoId.isNullOrEmpty()) {
        navigateToPromo(promoId)
    }
}

إضافة أزرار CTA مضمنة

يمكن أن تحمل الرسالة أزرار دعوة لاتخاذ إجراء (call-to-action) مضمنة داخل data.buttons:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "content": "Tap a button to claim or save",
      "inbox_image": "https://cdn.example.com/inbox/promo.png",
      "inbox_days": 7,
      "data": {
        "displayType": "captioned",
        "promo_id": "SUMMER2026",
        "buttons": [
          { "title": "Claim", "url": "https://example.com/promo/SUMMER2026" },
          { "title": "Read",  "action": "markRead" },
          { "title": "Save",  "action": "custom", "tag": "save_promo" }
        ]
      },
      "platforms": [3]
    }]
  }
}

يحتاج كل زر إلى title. يتبع التحديد هذه الأولوية:

إذا تم تعيين action إلى dismiss أو markRead (غير حساس لحالة الأحرف)، فسيتم تنفيذ هذا الإجراء.
وإلا، فإن url غير فارغ وقابل للتحليل يحل إلى إجراء openURL.
وإلا، فإن النقرة تحل إلى إجراء مخصص، ويتم تمرير كل مفتاح إضافي في كائن الزر إلى المستمع الخاص بك كحمولة له.

اعترض النقرات من PushwooshInboxUi.onButtonClickListener. أرجع true للسماح لـ SDK بتنفيذ الإجراء الافتراضي للزر، أو false لمنعه:

PushwooshInboxUi.onButtonClickListener = OnInboxButtonClickListener { message, button ->
    when (val action = button.action) {
        is InboxCardButton.Action.OpenUrl -> true
        InboxCardButton.Action.Dismiss, InboxCardButton.Action.MarkRead -> true
        is InboxCardButton.Action.Custom -> {
            when (action.payload.optString("tag")) {
                "save_promo" -> saveCurrentPromoLocally(message)
            }
            true
        }
    }
}

تخصيص النمط

قم بتعيين الألوان والخطوط وحالات الفراغ/الخطأ من الكود عبر PushwooshInboxStyle:

PushwooshInboxStyle.accentColor = ContextCompat.getColor(this, R.color.brand_accent)
PushwooshInboxStyle.titleColor = ContextCompat.getColor(this, R.color.brand_title)
PushwooshInboxStyle.listEmptyText = "You have no messages yet"
PushwooshInboxStyle.showToolbar = false

أو قم بتطبيق نفس مجموعة السمات كـ theme، المدرجة في attrs.xml: inboxAccentColor، inboxTitleColor، inboxBackgroundColor، inboxDefaultIcon، وبقية سمات اللون والمظهر. كلا النهجين، بالإضافة إلى تطبيق نموذجي كامل، موجودان في مستودع pushwoosh-inbox-ui-android-sdk InboxSample.

شارة الرسائل غير المقروءة

PushwooshInbox.unreadMessagesCount { result ->
    if (result.isSuccess) {
        val count = result.data
    } else {
        Log.e("App", "Failed to get unread count", result.exception)
    }
}