Configurando o Pushwoosh InboxKit para iOS

Disponível desde o SDK do iOS 7.0.40.

O Pushwoosh InboxKit oferece uma tela de caixa de entrada moderna em UIKit sobre o backend de caixa de entrada existente. Três layouts de célula padrão cobrem os formatos comuns de cartões de conteúdo no estilo Braze, botões de CTA em linha lidam com as interações mais comuns, e toda a superfície está aberta para subclassificação se você precisar de uma aparência personalizada.

Feed do InboxKit mostrando cartões em banner, com legenda e clássicos com botões em linha e indicadores de não lido

Feed padrão do InboxKit com cartões em banner, com legenda e clássicos.

Quando usar o InboxKit

Use o InboxKit para qualquer nova integração com iOS. É o substituto recomendado para o módulo mais antigo em Objective-C PushwooshInboxUI.

O InboxKit oferece a você:

Três tipos de célula integrados — banner, com legenda, clássico — selecionados por mensagem via actionParams["displayType"] do seu payload de push, ou forçados via código com attributes.forceCellKind.
Botões de CTA em linha com um enum tipado PushwooshInboxButtonAction (openURL, dismiss, markRead, custom). O SDK lida com os três primeiros automaticamente; seu delegate direciona custom para sua própria lógica.
Suporte à fixação: mensagens com actionParams["pinned"] == true flutuam para o topo do feed e renderizam um ícone de pino.
Deslizar para excluir, puxar para atualizar, marcação automática como lido ao desaparecer — tudo pode ser ativado/desativado via PushwooshInboxKitAttributes.
Armazenamento persistente: exclusões e estados de leitura sobrevivem a uma reinicialização do processo, mesmo que a chamada de rede ainda não tenha sido confirmada.
Uma classe base aberta PushwooshInboxCell para layouts totalmente personalizados.

O contrato do servidor permanece inalterado — o mesmo backend de caixa de entrada, payloads e ferramentas de painel do Pushwoosh funcionam como antes.

Escolha seu método de integração

Configurar o InboxKit com o Swift Package Manager — recomendado para novos projetos.
Configurar o InboxKit com o CocoaPods — para projetos que já usam o CocoaPods.

Ler dados personalizados de uma mensagem

Para que um push apareça na caixa de entrada, a solicitação createMessage da API de Mensagens deve incluir inbox_image, inbox_date ou inbox_days — sem um desses campos, o push é entregue como uma notificação regular e nunca chega ao feed da caixa de entrada. Dados personalizados de formato livre vão sob a chave data, que o SDK entrega ao cliente como o parâmetro 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]
    }]
  }
}

O SDK expõe esse objeto na mensagem da caixa de entrada através de actionParams. Leia-o a partir do delegate quando o usuário tocar na linha ou em um CTA em linha:

extension MyInboxHost: PushwooshInboxKitDelegate {

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

        // O objeto `data` personalizado chega sob a chave "u" —
        // seja como um dicionário aninhado ou como uma string codificada em JSON,
        // dependendo de como o payload foi construído anteriormente.
        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   // nós lidamos com o toque; o SDK não deve executar a ação padrão
        }
        return true
    }
}

A mesma busca actionParams["u"] funciona dentro de inboxKit(_:didTapButton:onMessage:) para botões de CTA em linha. Para os casos de CTA tipados (openURL, dismiss, markRead), o SDK já executa a ação padrão — retorne true para manter esse comportamento, ou false para suprimi-lo e executar o seu próprio.

Adicionar botões de CTA em linha

Uma mensagem pode conter até três botões de chamada para ação (CTA) em linha. Os botões ficam junto com outros dados personalizados dentro de data como um array buttons. O SDK os renderiza automaticamente dentro das células com legenda e clássicas:

{
  "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]
    }]
  }
}

Cada objeto de botão tem estes campos:

Campo	Tipo	Quando
`title`	string	Obrigatório. Rótulo visível do botão.
`url`	string	Uma URL analisável e não vazia produz uma ação `openURL`. O SDK a abre via `UIApplication.shared.open`, a menos que seu delegate a suprima.
`action`	string	Token de ação explícito: `dismiss` (remove a mensagem do feed), `markRead` (marca a mensagem como lida) ou `custom` (tratado pelo host). Não diferencia maiúsculas de minúsculas.
Qualquer outra coisa	any	Quando `action` é `custom`, toda chave no objeto do botão, exceto `title` e `action`, é encaminhada para o seu delegate como o payload personalizado — combine uma chave com o profissional de marketing (por exemplo, `tag`) e despache com base nela.

Prioridade de resolução: primeiro o token explícito action, depois url se não estiver vazio, caso contrário, o botão se enquadra em custom, carregando o payload completo (menos title e action).

Intercepte os toques a partir do seu delegate. A propriedade button.action é o enum tipado PushwooshInboxButtonAction:

extension MyInboxHost: PushwooshInboxKitDelegate {

    func inboxKit(_ vc: PushwooshInboxKitViewController,
                  didTapButton button: PushwooshInboxButton,
                  onMessage message: PWInboxMessageProtocol) -> Bool {
        switch button.action {
        case .openURL(let url):
            // O comportamento padrão está bom — deixe o SDK abrir a URL.
            return true

        case .dismiss, .markRead:
            // O SDK lida com ambos. Retorne false se quiser substituir.
            return true

        case .custom(let payload):
            // Botão personalizado definido pelo profissional de marketing. Despache com base em uma chave que vocês combinaram.
            if let tag = payload["tag"] as? String {
                switch tag {
                case "save_promo":
                    saveCurrentPromoLocally(message: message)
                default:
                    break
                }
            }
            return true   // ignorado para custom — o SDK nunca executa uma ação padrão aqui
        }
    }
}