إعداد Pushwoosh InboxKit لنظام iOS

متوفر منذ iOS SDK 7.0.40.

يقدم Pushwoosh InboxKit شاشة صندوق وارد حديثة بتقنية UIKit فوق الواجهة الخلفية الحالية لصندوق الوارد. تغطي ثلاثة تخطيطات افتراضية للخلايا أشكال بطاقات المحتوى الشائعة بأسلوب Braze، وتتعامل أزرار CTA المضمنة مع التفاعلات الأكثر شيوعًا، والسطح بأكمله مفتوح للتصنيف الفرعي إذا كنت بحاجة إلى مظهر مخصص.

موجز InboxKit الافتراضي مع بطاقات بانر، ومع تسميات توضيحية، وكلاسيكية.

متى تستخدم InboxKit

استخدم InboxKit لأي تكامل جديد لنظام iOS. إنه البديل الموصى به لوحدة Objective-C الأقدم PushwooshInboxUI.

يمنحك InboxKit:

• ثلاثة أنواع خلايا مدمجة — بانر، مع تسمية توضيحية، وكلاسيكي — يتم تحديدها لكل رسالة عبر actionParams["displayType"] من حمولة الإشعار الخاصة بك، أو يتم فرضها من الكود عبر attributes.forceCellKind.
• أزرار CTA مضمنة مع تعداد PushwooshInboxButtonAction محدد النوع (openURL، dismiss، markRead، custom). يتعامل SDK مع الثلاثة الأولى تلقائيًا؛ ويوجه المفوّض (delegate) الخاص بك custom إلى منطقك الخاص.
• دعم التثبيت: الرسائل التي تحتوي على actionParams["pinned"] == true تطفو إلى أعلى الموجز وتعرض رمز دبوس.
• السحب للحذف، السحب للتحديث، التحديد التلقائي كمقروء عند الاختفاء — كلها قابلة للتبديل عبر PushwooshInboxKitAttributes.
• تخزين دائم: تبقى حالات الحذف والقراءة بعد إعادة تشغيل العملية حتى لو لم يتم تأكيد استدعاء الشبكة بعد.
• فئة أساسية مفتوحة PushwooshInboxCell للتخطيطات المخصصة بالكامل.

عقد الخادم لم يتغير — تعمل نفس الواجهة الخلفية لصندوق الوارد في Pushwoosh، والحمولات، وأدوات لوحة التحكم كما كانت من قبل.

اختر طريقة التكامل الخاصة بك

• إعداد InboxKit باستخدام Swift Package Manager — موصى به للمشاريع الجديدة.
• إعداد InboxKit باستخدام CocoaPods — للمشاريع التي تستخدم CocoaPods بالفعل.

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

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

POST https://api.pushwoosh.com/json/1.3/createMessage

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "Summer sale",
      "content": "30% off everything — limited time only",
      "inbox_image": "https://cdn.example.com/inbox/summer.png",
      "inbox_days": 7,
      "data": {
        "promo_id": "SUMMER2026",
        "screen": "promo_details"
      },
      "ios_root_params": {
        "displayType": "captioned"
      },
      "platforms": [1]
    }]
  }
}

يعرض SDK هذا الكائن على رسالة صندوق الوارد من خلال actionParams. اقرأه من المفوّض (delegate) عندما ينقر المستخدم على الصف أو على زر CTA مضمن:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didSelect message: PWInboxMessageProtocol) -> Bool {
        guard let params = message.actionParams as? [String: Any] else { return true }

        // The custom `data` object arrives under the "u" key —
        // either as a nested dictionary or as a JSON-encoded string,
        // depending on how the payload was built upstream.
        let custom: [String: Any]? = {
            if let dict = params["u"] as? [String: Any] { return dict }
            if let raw = params["u"] as? String,
               let bytes = raw.data(using: .utf8),
               let parsed = try? JSONSerialization.jsonObject(with: bytes) as? [String: Any] {
                return parsed
            }
            return nil
        }()

        if let promoId = custom?["promo_id"] as? String {
            navigateToPromo(promoId)
            return false   // we handled the tap; SDK should not run the default action
        }
        return true
    }
}

يعمل نفس البحث actionParams["u"] داخل inboxKit(_:didTapButton:onMessage:) لأزرار CTA المضمنة. بالنسبة لحالات CTA المحددة النوع (openURL، dismiss، markRead)، يقوم SDK بالفعل بتنفيذ الإجراء الافتراضي — أرجع true للحفاظ على هذا السلوك، أو false لقمعه وتشغيل منطقك الخاص.

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

يمكن أن تحمل الرسالة ما يصل إلى ثلاثة أزرار دعوة لاتخاذ إجراء (call-to-action) مضمنة. توجد الأزرار جنبًا إلى جنب مع البيانات المخصصة الأخرى داخل data كمصفوفة buttons. يقوم SDK بعرضها تلقائيًا داخل الخلايا ذات التسميات التوضيحية والكلاسيكية:

POST https://api.pushwoosh.com/json/1.3/createMessage

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

يحتوي كل كائن زر على هذه الحقول:

الحقل	النوع	متى
title	string	مطلوب. تسمية الزر المرئية.
url	string	ينتج عن عنوان URL غير فارغ وقابل للتحليل إجراء openURL. يفتحه SDK عبر UIApplication.shared.open ما لم يقم المفوّض (delegate) الخاص بك بقمعه.
action	string	رمز إجراء صريح: dismiss (يزيل الرسالة من الموجز)، markRead (يحدد الرسالة كمقروءة)، أو custom (يتعامل معه المضيف). غير حساس لحالة الأحرف.
أي شيء آخر	any	عندما يكون action هو custom، يتم تمرير كل مفتاح في كائن الزر باستثناء title و action إلى المفوّض (delegate) الخاص بك كحمولة مخصصة — اتفق على مفتاح مع المسوق (على سبيل المثال tag) وقم بالتوزيع بناءً عليه.

أولوية الحل: رمز action الصريح أولاً، ثم url إذا لم يكن فارغًا، وإلا فإن الزر يقع ضمن custom حاملاً الحمولة الكاملة (ناقص title و action).

اعترض النقرات من المفوّض (delegate) الخاص بك. خاصية button.action هي التعداد المحدد النوع PushwooshInboxButtonAction:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didTapButton button: PushwooshInboxButton,
                  onMessage message: PWInboxMessageProtocol) -> Bool {
        switch button.action {
        case .openURL(let url):
            // Default behavior is fine — let SDK open the URL.
            return true

        case .dismiss, .markRead:
            // SDK handles both. Return false if you want to override.
            return true

        case .custom(let payload):
            // Marketer-defined custom button. Dispatch on a key you agreed on.
            if let tag = payload["tag"] as? String {
                switch tag {
                case "save_promo":
                    saveCurrentPromoLocally(message: message)
                default:
                    break
                }
            }
            return true   // ignored for custom — SDK never runs a default action here
        }
    }
}