การตั้งค่า Pushwoosh InboxKit iOS

พร้อมใช้งานตั้งแต่ iOS SDK 7.0.40

Pushwoosh InboxKit นำเสนอหน้าจอกล่องข้อความ UIKit ที่ทันสมัยซึ่งทำงานบนแบ็กเอนด์ของกล่องข้อความที่มีอยู่ เลย์เอาต์เซลล์เริ่มต้นสามแบบครอบคลุมรูปทรงการ์ดเนื้อหาทั่วไปสไตล์ Braze, ปุ่ม CTA ในตัวจัดการการโต้ตอบที่พบบ่อยที่สุด และพื้นผิวทั้งหมดเปิดให้ทำการ subclassing หากคุณต้องการรูปลักษณ์ที่กำหนดเอง

ฟีด InboxKit เริ่มต้นพร้อมการ์ดแบบแบนเนอร์, มีคำบรรยาย และคลาสสิก

เมื่อใดที่ควรใช้ InboxKit

ใช้ InboxKit สำหรับการผสานรวม iOS ใหม่ทั้งหมด เป็นโมดูลที่แนะนำให้ใช้แทนที่โมดูล Objective-C PushwooshInboxUI รุ่นเก่า

InboxKit ให้คุณ:

• ประเภทเซลล์ในตัวสามแบบ — แบนเนอร์, มีคำบรรยาย, คลาสสิก — ซึ่งเลือกต่อข้อความผ่าน actionParams["displayType"] จาก payload ของ push ของคุณ หรือบังคับจากโค้ดผ่าน attributes.forceCellKind
• ปุ่ม CTA ในตัวพร้อม enum PushwooshInboxButtonAction ที่ระบุประเภท (openURL, dismiss, markRead, custom) SDK จะจัดการสามอย่างแรกโดยอัตโนมัติ delegate ของคุณจะส่ง custom ไปยังตรรกะของคุณเอง
• รองรับการปักหมุด: ข้อความที่มี actionParams["pinned"] == true จะลอยไปอยู่ด้านบนสุดของฟีดและแสดงสัญลักษณ์หมุด
• ปัดเพื่อลบ, ดึงเพื่อรีเฟรช, ทำเครื่องหมายว่าอ่านแล้วโดยอัตโนมัติเมื่อหายไป — ทั้งหมดนี้สามารถสลับเปิด/ปิดได้ผ่าน PushwooshInboxKitAttributes
• ที่เก็บข้อมูลถาวร: สถานะการลบและการอ่านจะยังคงอยู่แม้จะรีสตาร์ทกระบวนการ แม้ว่าการเรียกเครือข่ายจะยังไม่ได้รับการยืนยันก็ตาม
• คลาสพื้นฐาน PushwooshInboxCell แบบเปิดสำหรับเลย์เอาต์ที่กำหนดเองได้อย่างเต็มที่

สัญญาของเซิร์ฟเวอร์ไม่เปลี่ยนแปลง — แบ็กเอนด์กล่องข้อความ, payloads และเครื่องมือแดชบอร์ดของ Pushwoosh ยังคงทำงานเหมือนเดิม

เลือกวิธีการผสานรวมของคุณ

• ตั้งค่า InboxKit ด้วย Swift Package Manager — แนะนำสำหรับโปรเจกต์ใหม่
• ตั้งค่า InboxKit ด้วย CocoaPods — สำหรับโปรเจกต์ที่ใช้ CocoaPods อยู่แล้ว

อ่านข้อมูลที่กำหนดเองจากข้อความ

เพื่อให้ push ปรากฏในกล่องข้อความ คำขอ createMessage ของ Messages API จะต้องมี inbox_image, inbox_date หรือ inbox_days — หากไม่มีฟิลด์ใดฟิลด์หนึ่งเหล่านี้ push จะถูกส่งเป็นการแจ้งเตือนปกติและจะไม่ไปถึงฟีดกล่องข้อความ ข้อมูลที่กำหนดเองแบบอิสระจะอยู่ภายใต้คีย์ 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 ของคุณเป็น payload ที่กำหนดเอง — ตกลงคีย์กับนักการตลาด (เช่น tag) และจัดการตามนั้น

ลำดับความสำคัญในการตัดสินใจ: โทเค็น action ที่ชัดเจนก่อน จากนั้นเป็น url หากไม่ว่างเปล่า มิฉะนั้นปุ่มจะตกไปอยู่ใน custom พร้อมกับ payload ทั้งหมด (ลบ title และ action)

ดักจับการแตะจาก delegate ของคุณ คุณสมบัติ button.action คือ enum 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
        }
    }
}