Pushwoosh InboxKit iOS 설정하기

iOS SDK 7.0.40부터 사용 가능합니다.

Pushwoosh InboxKit은 기존 인박스 백엔드 위에 최신 UIKit 인박스 화면을 제공합니다. 세 가지 기본 셀 레이아웃은 일반적인 Braze 스타일의 콘텐츠 카드 형태를 다루며, 인라인 CTA 버튼은 가장 일반적인 상호작용을 처리합니다. 또한 맞춤형 디자인이 필요한 경우 전체 영역을 서브클래싱할 수 있도록 열려 있습니다.

인라인 버튼과 읽지 않음 표시기가 있는 배너, 캡션, 클래식 카드를 보여주는 InboxKit 피드

배너, 캡션, 클래식 카드가 있는 기본 InboxKit 피드.

InboxKit 사용 시점

새로운 iOS 통합에는 InboxKit을 사용하세요. 기존 Objective-C PushwooshInboxUI 모듈을 대체하는 권장 방법입니다.

InboxKit은 다음을 제공합니다:

푸시 페이로드의 actionParams["displayType"]를 통해 메시지별로 선택하거나 코드에서 attributes.forceCellKind를 통해 강제할 수 있는 세 가지 내장 셀 유형(배너, 캡션, 클래식)을 제공합니다.
타입이 지정된 PushwooshInboxButtonAction 열거형(openURL, dismiss, markRead, custom)을 사용하는 인라인 CTA 버튼. SDK는 처음 세 가지를 자동으로 처리하며, 델리게이트는 custom을 자체 로직으로 라우팅합니다.
고정 지원: actionParams["pinned"] == true인 메시지는 피드 상단에 표시되며 핀 글리프를 렌더링합니다.
스와이프로 삭제, 당겨서 새로고침, 사라질 때 자동으로 읽음으로 표시 — 모두 PushwooshInboxKitAttributes를 통해 토글할 수 있습니다.
영구 저장소: 삭제 및 읽음 상태는 네트워크 호출이 아직 확인되지 않은 경우에도 프로세스 재시작 후에도 유지됩니다.
완전한 맞춤형 레이아웃을 위한 공개 PushwooshInboxCell 기본 클래스.

서버 계약은 변경되지 않았습니다. 동일한 Pushwoosh 인박스 백엔드, 페이로드, 대시보드 도구가 이전과 같이 작동합니다.

통합 방법 선택

Swift Package Manager로 InboxKit 설정하기 — 새 프로젝트에 권장됩니다.
CocoaPods로 InboxKit 설정하기 — 이미 CocoaPods를 사용하는 프로젝트용입니다.

메시지에서 커스텀 데이터 읽기

푸시를 인박스에 표시하려면 Messages API의 createMessage 요청에 inbox_image, inbox_date 또는 inbox_days가 포함되어야 합니다. 이 필드 중 하나가 없으면 푸시는 일반 알림으로 전달되며 인박스 피드에 도달하지 않습니다. 자유 형식의 커스텀 데이터는 data 키 아래에 위치하며, SDK는 이를 클라이언트에 u 매개변수로 전달합니다:

{
  "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를 통해 노출합니다. 사용자가 행이나 인라인 CTA를 탭할 때 델리게이트에서 이를 읽어오세요:

extension MyInboxHost: PushwooshInboxKitDelegate {

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

        // 커스텀 `data` 객체는 "u" 키 아래에 도착합니다 —
        // 중첩된 딕셔너리 또는 JSON으로 인코딩된 문자열 형태로,
        // 페이로드가 업스트림에서 어떻게 빌드되었는지에 따라 다릅니다.
        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   // 탭을 처리했으므로 SDK는 기본 작업을 실행해서는 안 됩니다
        }
        return true
    }
}

동일한 actionParams["u"] 조회는 인라인 CTA 버튼에 대해 inboxKit(_:didTapButton:onMessage:) 내부에서도 작동합니다. 타입이 지정된 CTA 케이스(openURL, dismiss, markRead)의 경우 SDK는 이미 기본 작업을 수행합니다. 해당 동작을 유지하려면 true를 반환하고, 이를 억제하고 자체 로직을 실행하려면 false를 반환하세요.

인라인 CTA 버튼 추가하기

메시지는 최대 세 개의 인라인 콜투액션(call-to-action) 버튼을 가질 수 있습니다. 버튼은 data 내의 다른 커스텀 데이터와 함께 buttons 배열로 존재합니다. SDK는 캡션 및 클래식 셀 내부에 이를 자동으로 렌더링합니다:

{
  "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`을 통해 엽니다.
`action`	string	명시적 작업 토큰: `dismiss`(피드에서 메시지 제거), `markRead`(메시지를 읽음으로 표시), 또는 `custom`(호스트에서 처리). 대소문자를 구분하지 않습니다.
그 외 모든 것	any	`action`이 `custom`일 때, 버튼 객체의 `title`과 `action`을 제외한 모든 키는 커스텀 페이로드로 델리게이트에 전달됩니다. 마케터와 키(예: `tag`)에 대해 합의하고 이를 기반으로 디스패치하세요.

해결 우선순위: 명시적 action 토큰이 먼저, 그 다음 비어 있지 않은 경우 url, 그렇지 않으면 버튼은 전체 페이로드(title과 action 제외)를 포함하는 custom으로 처리됩니다.

델리게이트에서 탭을 가로챕니다. button.action 속성은 타입이 지정된 PushwooshInboxButtonAction 열거형입니다:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didTapButton button: PushwooshInboxButton,
                  onMessage message: PWInboxMessageProtocol) -> Bool {
        switch button.action {
        case .openURL(let url):
            // 기본 동작으로 충분합니다 — SDK가 URL을 열도록 합니다.
            return true

        case .dismiss, .markRead:
            // SDK가 둘 다 처리합니다. 재정의하려면 false를 반환하세요.
            return true

        case .custom(let payload):
            // 마케터가 정의한 커스텀 버튼. 합의된 키를 기반으로 디스패치하세요.
            if let tag = payload["tag"] as? String {
                switch tag {
                case "save_promo":
                    saveCurrentPromoLocally(message: message)
                default:
                    break
                }
            }
            return true   // custom의 경우 무시됩니다 — SDK는 여기서 기본 작업을 실행하지 않습니다
        }
    }
}