> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Badges

> Gerencie contagens de badges de ícone de aplicativo para notificações push no iOS, Android e Huawei, incluindo limpeza automática, controle de API e lógica nativa de badge.

Badges são os pequenos pontos numerados que aparecem no ícone do seu aplicativo móvel. Eles ajudam a capturar a atenção do usuário e podem influenciar o comportamento de engajamento. No iOS em particular, badges requerem configuração adicional e oferecem controle flexível, conforme descrito abaixo.

<Note>
  Para notificações Android Web Push, o badge se refere ao pequeno ícone mostrado nas notificações—não no ícone do aplicativo—e pode ser personalizado. Veja [Web Push Badges](./push#badges).
</Note>

***

## Badges do Android

O comportamento de badge do ícone de aplicativo Android pode ser gerenciado através de [categorias de notificação do Android](./android-notification-categories). Você pode controlar se uma categoria (canal) exibe um badge e definir o comportamento do badge por categoria.

***

## Badges Huawei

Em dispositivos Huawei, um badge pode ser exibido como um número ou um ponto no ícone do aplicativo, dependendo das configurações do dispositivo do usuário. Badges ajudam a indicar mensagens não lidas ou ações pendentes, encorajando os usuários a abrir o aplicativo. O OneSignal permite que você controle as contagens de badges Huawei diretamente através do painel ou API.

### Como os badges Huawei funcionam

O badge é exibido no ícone do aplicativo como uma **contagem numérica** ou um **ponto**, dependendo das configurações do dispositivo do usuário (**Configurações > Notificações > Badges de ícone de aplicativo**). Sua chamada de API controla a contagem subjacente; o dispositivo decide o estilo visual.

#### Parâmetros

| Parâmetro              | Tipo    | Intervalo | Descrição                                                                                                                                                                                                          |
| ---------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `huawei_badge_class`   | string  | —         | **(Obrigatório)** Nome de classe totalmente qualificado da Activity de lançamento do seu aplicativo (ex.: `com.example.myapp.MainActivity`). Informa ao sistema Huawei em qual ícone de aplicativo exibir o badge. |
| `huawei_badge_set_num` | integer | 0–99      | Define o badge para um número exato. `0` limpa o badge.                                                                                                                                                            |
| `huawei_badge_add_num` | integer | 1–99      | Incrementa a contagem de badge existente por esta quantidade.                                                                                                                                                      |

#### Regras de comportamento

* `huawei_badge_class` é obrigatório para qualquer operação de badge.
* Se `huawei_badge_set_num` e `huawei_badge_add_num` forem fornecidos, `huawei_badge_set_num` tem prioridade.
* Se nenhum for fornecido (mas `huawei_badge_class` estiver definido), a contagem de badge incrementa em 1 por padrão.

### Enviar push Huawei com badges

<Tabs>
  <Tab title="Dashboard">
    1. Vá para **Messages > Push** ou **Templates**
    2. Em **Platform Settings > Send to Huawei Android > Badge**
    3. Escolha uma das seguintes opções:
       * **Não definir** — o badge não é afetado por esta notificação
       * **Definir para** — define o badge para um número específico (0-99)
       * **Aumentar em** — incrementa a contagem de badge existente (1-99)
  </Tab>

  <Tab title="API">
    Use os seguintes parâmetros na API [Create message](/reference/create-message):

    * `huawei_badge_class` — *(string, obrigatório para badge)* O nome de classe totalmente qualificado da activity de lançamento do aplicativo (por exemplo, `"com.example.myapp.MainActivity"`)
    * `huawei_badge_set_num` — *(inteiro, 0-99)* Define a contagem de badge para este número exato. Defina como `0` para limpar o badge.
    * `huawei_badge_add_num` — *(inteiro, 1-99)* Incrementa a contagem de badge existente por este número. Se omitido junto com `huawei_badge_set_num`, o padrão é incrementar em 1.

    **Definir badge para um número específico:**

    ```json theme={null}
    {
      "huawei_badge_class": "com.example.myapp.MainActivity",
      "huawei_badge_set_num": 5
    }
    ```

    **Incrementar badge por uma quantidade específica:**

    ```json theme={null}
    {
      "huawei_badge_class": "com.example.myapp.MainActivity",
      "huawei_badge_add_num": 1
    }
    ```

    **Limpar o badge:**

    ```json theme={null}
    {
      "huawei_badge_class": "com.example.myapp.MainActivity",
      "huawei_badge_set_num": 0
    }
    ```
  </Tab>
</Tabs>

### Limpando badges

A Huawei **não** limpa automaticamente o badge quando um usuário abre o aplicativo ou toca em uma notificação. Para limpar o badge, você tem duas opções:

* **Via API ou painel**: Envie uma notificação com `huawei_badge_set_num` definido como `0` (ou use **Definir para > 0** no painel). Pode ser uma [notificação de dados/em segundo plano](./data-notifications) se você não quiser que uma notificação visível apareça.
* **Via código do lado do cliente**: Seu aplicativo pode limpar o badge localmente usando a API de badge da Huawei. Isso requer a permissão `com.huawei.android.launcher.permission.CHANGE_BADGE` em seu `AndroidManifest.xml`. Consulte o [guia de desenvolvimento de badges da Huawei](https://developer.huawei.com/consumer/en/doc/hmscore-guides/android-badging-0000001050042083) para detalhes de implementação.

<Note>
  O parâmetro `huawei_badge_set_num` requer EMUI 10.0.0 ou posterior e Push SDK 10.1.0 ou posterior. Em dispositivos mais antigos, apenas `huawei_badge_add_num` é suportado.
</Note>

***

## Badges do iOS

Para garantir que as contagens de badge incrementem corretamente no iOS, você deve configurar:

* O `OneSignalNotificationServiceExtension`
* App Groups

Veja [Configuração do SDK móvel](./mobile-sdk-setup) para instruções completas.

Por padrão, o SDK do OneSignal irá:

1. Limpar o badge do ícone do aplicativo quando o aplicativo é aberto.
2. Remover notificações da Central de Notificações.

Se você quiser manter as notificações e gerenciar a lógica de badge manualmente (por exemplo, usando seu próprio contador ou sincronizando o estado entre dispositivos), você pode desabilitar esse comportamento automático.

**Casos de uso comuns para controle manual de badge**

* Redefinir badge quando o aplicativo é iniciado ou retomado
* Incrementar badge quando uma notificação é recebida em primeiro plano
* Decrementar quando uma mensagem é lida ou descartada
* Sincronizar estado de badge entre dispositivos ou extensões de aplicativo via App Groups ou seu backend

### Desabilitar notificação automática e limpeza de badge

No `info.plist` do seu aplicativo, adicione a chave: `OneSignal_disable_badge_clearing` com tipo Boolean para o valor `YES`

<Frame caption="Info.plist com OneSignal_disable_badge_clearing definido como YES.">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/ea4fbad85bfcb4909ce88668e3882fc8749624c781a66d7c78c440b7e267999c-Screenshot_2025-04-01_at_4.37.05_PM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=e2aafae9e93e16b63e263f34770f262a" alt="Xcode Info.plist editor showing OneSignal_disable_badge_clearing set to YES" width="2284" height="1484" data-path="images/docs/ea4fbad85bfcb4909ce88668e3882fc8749624c781a66d7c78c440b7e267999c-Screenshot_2025-04-01_at_4.37.05_PM.png" />
</Frame>

```xml theme={null}
<key>OneSignal_disable_badge_clearing</key>
<true/>
```

Isso impede que o SDK remova automaticamente notificações ou redefina o badge quando o aplicativo abre.

#### Gerenciamento nativo de badge do iOS

Se você desabilitar a limpeza automática de badge do OneSignal, você pode usar as APIs nativas da Apple para controlar o comportamento do badge.

<Warning>
  A Apple descontinuou `UIApplication.shared.applicationIconBadgeNumber` no iOS 17. Você deve agora usar os seguintes métodos do [framework UserNotifications](https://developer.apple.com/documentation/UserNotifications/UNUserNotificationCenter/setBadgeCount\(_:withCompletionHandler:\)):
</Warning>

**Definir contagem de badge**

Para definir o badge no ícone do aplicativo para um valor específico:

```swift theme={null}
import UserNotifications
import UIKit

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(5) { error in
    if let error = error {
      print("Failed to set badge count: \(error.localizedDescription)")
    } else {
      print("Badge count updated successfully.")
    }
  }
} else {
  UIApplication.shared.applicationIconBadgeNumber = 5
}
```

**Obter contagem atual de badge**

O iOS não fornece um método para recuperar a contagem atual de badge do sistema. Você deve rastrear a contagem de badge no estado do seu aplicativo (por exemplo, usando `UserDefaults`, o modelo de dados do seu aplicativo ou sincronizando com seu backend).

```swift theme={null}
// Example: Store and retrieve badge count using UserDefaults
let badgeCount = UserDefaults.standard.integer(forKey: "badgeCount")
// Update badge count as needed
UserDefaults.standard.set(badgeCount, forKey: "badgeCount")
```

**Incrementar ou decrementar badge**

Você deve gerenciar a lógica de badge manualmente, pois mudanças relativas (como +1 ou -1) não são suportadas em payloads. Atualize sua contagem de badge armazenada e então defina-a:

```swift theme={null}
// Example: Increment badge count and update system badge
let currentCount = UserDefaults.standard.integer(forKey: "badgeCount")
let updatedCount = max(0, currentCount + 1)
UserDefaults.standard.set(updatedCount, forKey: "badgeCount")

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(updatedCount)
} else {
  UIApplication.shared.applicationIconBadgeNumber = updatedCount
}
```

**Limpar badge**

Para remover o badge completamente:

```swift theme={null}
if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(0)
} else {
  UIApplication.shared.applicationIconBadgeNumber = 0
}
```

### Enviar push do iOS com badges

Você pode definir a contagem de badge no painel do OneSignal ou usando a API.

<Tabs>
  <Tab title="Dashboard">
    1. Vá para **Messages > Push** ou **Templates**.
    2. Em **Platform Settings > Send to Apple iOS > Badges**.
    3. Escolha:
       * Definir para um número específico.
       * Aumentar por uma quantidade relativa.

    <Frame caption="Definir badges no formulário de mensagem do painel do OneSignal.">
      <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a6f4a4c0d5869fd9ba5c83ded26752f83c1350c4f6f5213a985cf522fa4d0387-Screenshot_2025-04-01_at_4.42.50_PM.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=8b428dfec1995ea5ec296d717bad9524" alt="OneSignal dashboard push message form showing iOS badge count options" width="1528" height="558" data-path="images/docs/a6f4a4c0d5869fd9ba5c83ded26752f83c1350c4f6f5213a985cf522fa4d0387-Screenshot_2025-04-01_at_4.42.50_PM.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    Use os seguintes parâmetros na API [Create message](/reference/create-message):

    * `ios_badgeType` — Defina como `SetTo` ou `Increase`.
    * `ios_badgeCount` — O número para definir ou aumentar.

    ```json theme={null}
    {
      "ios_badgeType": "Increase",
      "ios_badgeCount": 1
    }
    ```
  </Tab>
</Tabs>

Ao enviar notificações push do iOS, a contagem de badge muda com base nessas opções.

Se o aplicativo estiver aberto, a contagem de badge será redefinida a menos que você [desabilite a limpeza automática de badge](#desabilitar-notificação-automática-e-limpeza-de-badge).

***

## FAQ

### Por que a contagem de badge não está incrementando no iOS?

Certifique-se de ter configurado o `OneSignalNotificationServiceExtension` e os App Groups. Sem esses, as contagens de badge não podem incrementar corretamente. Veja [Configuração do SDK móvel](./mobile-sdk-setup) para instruções completas.

### Como limpar badges no Huawei?

Envie uma notificação com `huawei_badge_set_num` definido como `0`, ou use **Definir para > 0** no painel. Você também pode usar uma [notificação de dados/em segundo plano](./data-notifications) para limpar badges sem mostrar uma notificação visível. Alternativamente, limpe o badge do lado do cliente usando a API de badge da Huawei.

### Posso definir badges para web push?

Não. Badges de ícone de aplicativo são suportados apenas no iOS, Android e Huawei. Para Android web push, o "badge" se refere ao pequeno ícone exibido na própria notificação — veja [Web Push Badges](./push#badges).

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Categorias de notificação do Android" icon="android" href="./android-notification-categories">
    Controle a exibição e o comportamento de badges por canal de notificação no Android.
  </Card>

  <Card title="Autorização Huawei" icon="mobile" href="./authorize-onesignal-to-send-huawei-push">
    Configure o envio de mensagens push Huawei com o OneSignal.
  </Card>

  <Card title="Visão geral de push" icon="bell" href="./push">
    Referência completa para recursos de notificação push, incluindo badges de web push.
  </Card>

  <Card title="Configuração do SDK móvel" icon="code" href="./mobile-sdk-setup">
    Configure o SDK do OneSignal incluindo pré-requisitos de badge para iOS.
  </Card>
</Columns>