--- title: "Caixa de entrada personalizada no iOS móvel" slug: "ios-custom-inbox" updated: 2026-06-12T10:30:51Z published: 2026-06-12T10:30:51Z canonical: "docs.xtremepush.com/ios-custom-inbox" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt > Use this file to discover all available pages before exploring further. # Caixa de entrada personalizada no iOS móvel Implemente uma caixa de entrada personalizada no seu aplicativo iOS Por padrão, o XtremePush SDK renderiza a caixa de entrada como um WebView embutido. Uma **caixa de entrada personalizada** substitui isso pela sua própria interface nativa, dando controle total sobre o layout e a interação. Quando você implementa uma caixa de entrada personalizada, o SDK continua a lidar: - Buscar e paginar mensagens da caixa de entrada da plataforma - Excluindo mensagens - Contagens de crachás de rastreamento - Enviando eventos analíticos abertos/clicados (quando você chama os métodos de relatório) Seu aplicativo passa a ser responsável por: - Renderização de cada mensagem (título, corpo, imagem, ícone, layout de cartão vs alerta) - Gerenciando ações de tap (navegação por deeplink, abertura de URLs) - Chamando os métodos de reporte no momento certo ## Recuperar mensagens da caixa de entrada O `inboxListWithOffset:limit:callback:` método busca assíncronamente uma lista de itens da caixa de entrada. Use os `offset` parâmetros e `limit` para suportar paginação. **Swift** ```swift XPush.inboxList(withOffset: 0, limit: 20) { (list, badge, error) in    if let list = list {        // render list    } else if let error = error {        // handle error    } } ``` **Objective-C** ```objectivec [XPush inboxListWithOffset:0 limit:20 callback:^(NSArray * _Nullable list, NSUInteger badge, NSError * _Nullable error) {    if (list != nil) {        // render list    } else if (error != nil) {        // handle error    } }]; ``` ## XPInboxItem Cada item no array retornado é um `XPInboxItem` com as seguintes propriedades: | Propriedade | Tipo | Descrição | | --- | --- | --- | | `identifier` | `NSInteger` | ID de mensagem único | | `isOpened` | `BOOL` | Se a mensagem foi marcada como aberta | | `isClicked` | `BOOL` | Se a mensagem foi marcada como clicada | | `isDelivered` | `BOOL` | Se a mensagem foi entregue | | `createTimestamp` | `NSNumber *` | Carimbo de data e hora do Unix de quando a mensagem foi criada | | `expirationTimestamp` | `NSNumber *` | Carimbo de tempo do Unix de expiração, ou nil se a mensagem não expirar | | `style` | `XPInboxItemStyle *` | Valores de cor de fundo e título | | `isCard` | `BOOL` | `YES` para layout de cartões (imagem de banner de largura total), `NO` para layout de alerta (miniatura pequena) | | `response` | `XPMessageResponse *` | Contém o conteúdo da mensagem e a ação de toque — veja abaixo | ## Trabalhando com conteúdo de mensagens Cada `XPInboxItem` um expõe seu conteúdo através de `item.response`, que contém dois objetos: `item.response.message` (`XPMessage`) — o conteúdo da mensagem: | Propriedade | Tipo | Definido por | | --- | --- | --- | | `identifier` | `NSString *` | Plataforma (designada ao sistema) | | `campaignIdentifier` | `NSString *` | Plataforma (designada ao sistema) | | `title` | `NSString *` | Campanha — Campanha pelo título | | `text` | `NSString *` | Campanha — Push texto / campo do corpo | | `icon` | `NSString *` | Campanha — Empurrar o campo do ícone (volta para o ícone do app, depois ícone do projeto, se não estiver definido) | | `data` | `NSDictionary *` | Campanha — Campos personalizados de carga útil (payload_add), com chaves reservadas no SDK removidas | | `payload` | `NSDictionary *` | Dicionário de mensagens raw completo — use quando precisar de acesso direto a campos que não foram mencionados acima | `item.response.action` (`XPAction`) — a ação de toque: | Propriedade | Tipo | Definido por | | --- | --- | --- | | `deeplink` | `NSString *` | Campanha — presente quando o tipo de ação é **Deeplink**; `nil` caso contrário | | `url` | `NSURL *` | Campanha — presente quando o tipo de ação for **URL;** `nil` caso contrário | | `identifier` | `NSString *` | Plataforma — passe para métodos de reporte | `deeplink` e `url` são mutuamente exclusivos — apenas um será definido dependendo do tipo de ação configurado na campanha. Se nenhum dos dois estiver definido, a mensagem não tem ação de toque. **O layout e o estilo** estão no item: | Propriedade | Tipo | Definido por | | --- | --- | --- | | `isCard` | `BOOL` | Campanha — configuração do tipo de caixa de entrada. `YES` = layout de cartões (banner de largura total), `NO` = layout de alerta (miniatura pequena) | | `style.background` | `NSString *` | Campanha — cor de fundo estilo caixa de entrada | | `style.titleBackground` | `NSString *` | Campanha — cor da barra de título estilo caixa de entrada | ### Campos personalizados de carga útil Se a interface da sua caixa de entrada exigir dados além dos campos padrão — por exemplo, um rótulo de CTA, uma URL secundária ou um valor de emblema — adicione campos personalizados na seção **de Carga Personalizada** (payload_add) da campanha. Esses são entregues como `item.response.message.data` um dicionário chave-valor, com todas as chaves reservadas no SDK já removidas. **Swift** ```swift // Reading a custom payload field if let ctaLabel = item.response.message.data?["cta_label"] as? String {    button.setTitle(ctaLabel, for: .normal) } ``` **Objective-C** ```objectivec NSString *ctaLabel = item.response.message.data[@"cta_label"]; if (ctaLabel) {    [button setTitle:ctaLabel forState:UIControlStateNormal]; } ``` > [!NOTE] > Modelos de Campanha > > Como sua interface personalizada da caixa de entrada foi feita para renderizar uma estrutura de conteúdo específica, considere definir um modelo de campanha reutilizável na caixa de entrada na plataforma Xtremepush que preencha consistentemente os campos que sua interface espera. Por exemplo, se o layout do seu cartão sempre mostrar título, corpo, cor de fundo, ação de deeplink e um rótulo personalizado de CTA, defina esses campos como campos obrigatórios para qualquer campanha de entrada que tenha como alvo sua implementação personalizada. ## Lidar com ações de mensagens (deeplink & URL) Quando um usuário digitar uma mensagem, inspecione `item.response.action` para determinar o que fazer. O SDK **não** dispara chamadas de retorno de deeplink automaticamente em uma caixa de entrada personalizada — seu app gerencia a navegação diretamente. Sempre ligue `reportMessageClicked` para que a interação seja registrada na plataforma. **Swift** ```swift func userDidTap(_ item: XPInboxItem) {    // Register the click with the platform    XPush.reportMessageClicked(item.response.message, actionIdentifier: item.response.action.identifier)    if let deeplink = item.response.action.deeplink {        // Route through your app's navigation handler        // MyRouter.shared.navigate(to: deeplink)    } else if let urlString = item.response.action.url,              let url = URL(string: urlString) {        UIApplication.shared.open(url)    } else {        // No tap action configured — message is informational only    } } ``` **Objective-C** ```objectivec - (void)userDidTapInboxItem:(XPInboxItem *)item {    // Register the click with the platform    [XPush reportMessageClicked:item.response.message actionIdentifier:item.response.action.identifier];    if (item.response.action.deeplink) {        // Route through your app's navigation handler        // [[MyRouter shared] navigateTo:item.response.action.deeplink];    } else if (item.response.action.url) {        NSURL *url = [NSURL URLWithString:item.response.action.url];        [[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];    } else {        // No tap action configured — message is informational only    } } ``` ## Mensagem de reporte aberta na caixa de entrada Chame isso quando uma mensagem se torna visível para o usuário (por exemplo, rolada para a visualização de um feed) sem um toque deliberado. **Swift** ```swift XPush.reportMessageOpened(item.response.message, actionIdentifier: item.response.action.identifier) ``` **Objective-C** ```objectivec [XPush reportMessageOpened:item.response.message actionIdentifier:item.response.action.identifier]; ``` ## Mensagem de reportar entrada clicada Chame isso quando um usuário deliberadamente toca uma mensagem. Isso também marca automaticamente a mensagem como aberta. Não ligue `reportMessageOpened` separadamente para mensagens grampeadas. **Swift** ```swift XPush.reportMessageClicked(item.response.message, actionIdentifier: item.response.action.identifier) ``` **Objective-C** ```objectivec [XPush reportMessageClicked:item.response.message actionIdentifier:item.response.action.identifier]; ``` ## Excluir uma mensagem de caixa de entrada **Swift** ```swift XPush.removeInboxMessage(item) { badge in    // reload inbox list    // update badge display } ``` **Objective-C** ```objectivec [XPush removeInboxMessage:item callback:^(NSInteger badge) {    // reload inbox list    // update badge display }]; ``` ## Receba o número do crachá da caixa de entrada Retorna a contagem de não lidos em cache — use isso para exibir um badge sem fazer uma solicitação de rede. **Swift** ```swift let badge: NSInteger = XPush.getInboxBadge() ``` **Objective-C** ```objectivec NSInteger badge = [XPush getInboxBadge]; ```