انتقل إلى المحتوى
أدلة المستخدمالدعم طلب عرض توضيحي تسجيل الدخول
Pushwoosh.com

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

متاح منذ iOS SDK 7.0.40.

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

موجز InboxKit يعرض بطاقات البانر، والتعليقات، والكلاسيكية، والدائرية، والفيديو، وApple Wallet

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

متى تستخدم InboxKit

Anchor link to

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

يمنحك InboxKit:

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

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

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

Anchor link to

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

Anchor link to

يختار InboxKit تخطيط خلية لكل رسالة. يقرأ المحلل الافتراضي displayType من حمولة الدفع — ضعه داخل كائن data، الذي يقدمه SDK تحت actionParams. عندما يكون displayType مفقودًا، يلجأ المحلل إلى طريقة استدلالية: صورة + بدون عنوان ← بانر، صورة + عنوان ← مع تعليق، وإلا كلاسيكي. لفرض تخطيط واحد للموجز بأكمله من الكود، قم بتعيين attributes.forceCellKind.

كل تخطيط غني يتدهور برشاقة: إذا كانت الحمولة المطلوبة غائبة أو مشوهة، تعود البطاقة إلى classic بدلاً من عرض عنصر نائب فارغ (ويتم تسجيل WARN).

displayTypeالتخطيطحقل الحمولة المطلوبيتدهور إلى
bannerصورة بملء الشاشة، بدون نصصورة (inbox_image أو data.image)classic عند عدم وجود صورة
captionedصورة في الأعلى، عنوان + نص أدناهصورة (inbox_image أو data.image)classic عند عدم وجود صورة
classicصورة رمزية أولية ملونة + عنوان + نص——
carouselمعرض صور متعددة قابل للسحبdata.carousel (مصفوفة من الشرائح)classic عند عدم وجود شرائح
videoملصق مع شارة تشغيل، مشغل بملء الشاشة عند النقرdata.video (url + poster اختياري)classic عند عدم وجود واصف
walletزر “إضافة إلى Apple Wallet” (iOS فقط)data.wallet (عنوان URL لـ .pkpass)classic عند عدم وجود عنوان URL للبطاقة
بطاقة بانر InboxKit
بطاقة بانر
بطاقة مع تعليق من InboxKit
بطاقة مع تعليق
بطاقة كلاسيكية من InboxKit
بطاقة كلاسيكية
بطاقة دائرية من InboxKit
بطاقة دائرية
بطاقة فيديو من InboxKit
بطاقة فيديو
بطاقة Apple Wallet من InboxKit
بطاقة Apple Wallet

تعتمد بطاقات البانر، والتعليقات، والكلاسيكية على حقول الرسائل القياسية (الصورة، العنوان، النص) بالإضافة إلى مصفوفة buttons الاختيارية — انظر إضافة أزرار CTA مضمنة. تحمل بطاقات الدوارة والفيديو و Apple Wallet بيانات منظمة إضافية داخل data، موثقة أدناه.

بطاقة دائرية

Anchor link to

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

POST https://api.pushwoosh.com/json/1.3/createMessage
{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "New arrivals",
      "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" },
          { "image": "https://cdn.example.com/inbox/3.jpg" }
        ]
      },
      "platforms": [1]
    }]
  }
}

بطاقة فيديو

Anchor link to

تعرض بطاقة الفيديو صورة ملصق مع شارة تشغيل؛ يؤدي النقر عليها إلى فتح مشغل بملء الشاشة (مع تشغيل الصوت، حتى مع تفعيل مفتاح الصامت). يوجد الواصف في data.video: url مطلوب ويجب أن يكون بثًا أو ملفًا http/https؛ poster هي صورة معاينة اختيارية.

POST https://api.pushwoosh.com/json/1.3/createMessage
{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "Watch the reveal",
      "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": [1]
    }]
  }
}

بطاقة Apple Wallet

Anchor link to

تعرض بطاقة Apple Wallet صورة رئيسية اختيارية وعنوانًا ونصًا فوق زر إضافة إلى Apple Wallet الرسمي. يؤدي النقر على الزر إلى تنزيل .pkpass وتقديم ورقة إضافة البطاقات النظامية. استخدمها لتقديم القسائم أو بطاقات الولاء أو التذاكر أو بطاقات الصعود إلى الطائرة مباشرة من صندوق الوارد. البطاقة مخصصة لنظام iOS / Mac Catalyst فقط — على المنصات الأخرى، يتم عرض الرسالة كبطاقة كلاسيكية.

يوجد عنوان URL للبطاقة في data.wallet، إما كسلسلة نصية مجردة أو ككائن يحتوي على حقل pass. تضيف data.image الاختيارية الصورة الرئيسية. يخفي الزر نفسه تلقائيًا عندما لا يكون هناك عنوان URL للبطاقة أو عندما لا يتمكن الجهاز من إضافة بطاقات.

POST https://api.pushwoosh.com/json/1.3/createMessage
{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "API_TOKEN",
    "notifications": [{
      "send_date": "now",
      "ios_title": "Your loyalty card is ready",
      "content": "Add it to Apple Wallet in one tap",
      "inbox_days": 7,
      "data": {
        "displayType": "wallet",
        "image": "https://cdn.example.com/inbox/loyalty.png",
        "wallet": "https://passes.example.com/v1/passes/pass.com.example.loyalty/abc123?token=…"
      },
      "platforms": [1]
    }]
  }
}

يتم إبلاغ النتيجة إلى المفوّض الخاص بك:

extension MyInboxHost: PushwooshInboxKitDelegate {


    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didAddWalletPassFor message: PWInboxMessageProtocol) {
        // The pass is now in the user's Wallet — show a confirmation if you like.
    }


    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didFailToAddWalletPassFor message: PWInboxMessageProtocol,
                  error: Error?) {
        // Download failed — surface a retry, log, etc.
    }
}

كلا الاستدعاءين اختياريان (يحملان تطبيقات فارغة افتراضية). إلغاء المستخدم لورقة النظام ليس نجاحًا ولا فشلًا، لذلك لا يتم تشغيل أي استدعاء في هذه الحالة.

إمكانية الوصول

Anchor link to

خلايا InboxKit جاهزة لـ VoiceOver بشكل افتراضي. تعرض بطاقات البانر والتعليقات والكلاسيكية عنوانها ونصها وتاريخها من خلال التسميات الأساسية، وتقرأ أزرار CTA المضمنة عناوينها الخاصة. تضيف البطاقات الغنية دلالات صريحة:

  • فيديو — يتم عرض الملصق كعنصر زر واحد يسمى “تشغيل الفيديو” (السمات .button + .startsMediaSession)، لذلك يعلن VoiceOver عنه كعنصر تحكم في الوسائط بدلاً من صورة عادية.
  • دوارة — كل شريحة هي عنصر زر يكون تسمية إمكانية الوصول الخاصة به هي تعليق الشريحة، أو “شريحة” عندما لا يكون لها تعليق. يعلن مؤشر الصفحة عن الموضع الحالي كـ “n من الإجمالي”.
  • Apple Wallet — زر إضافة إلى Apple Wallet هو زر PKAddPassButton القياسي من Apple، والذي يحمل تسمية VoiceOver مترجمة خاصة به.

لاختبار واجهة المستخدم والأتمتة، يتم تعيين معرفي accessibilityIdentifier ثابتين: inboxkit.video.play على ملصق الفيديو و inboxkit.wallet.add على زر Wallet.

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

Anchor link to

لجعل إشعار الدفع يظهر في صندوق الوارد، يجب أن يتضمن طلب 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": {
        "displayType": "captioned",
        "promo_id": "SUMMER2026",
        "screen": "promo_details"
      },
      "platforms": [1]
    }]
  }
}

يعرض SDK هذا الكائن على رسالة صندوق الوارد من خلال actionParams. اقرأه من المفوّض عندما ينقر المستخدم على الصف أو على زر 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 مضمنة

Anchor link to

يمكن أن تحمل الرسالة ما يصل إلى ثلاثة أزرار دعوة إلى اتخاذ إجراء (CTA) مضمنة. توجد الأزرار جنبًا إلى جنب مع البيانات المخصصة الأخرى داخل 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": {
        "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": [1]
    }]
  }
}

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

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

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

اعترض النقرات من المفوّض الخاص بك. خاصية 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
        }
    }
}