Insignias

Gestione los contadores de insignias de ícono de aplicación para notificaciones push en iOS, Android y Huawei, incluyendo borrado automático, control de API y lógica nativa de insignias.

Las insignias son los pequeños puntos numerados que aparecen en el ícono de su aplicación móvil. Ayudan a captar la atención del usuario y pueden influir en el comportamiento de participación. En iOS en particular, las insignias requieren configuración adicional y ofrecen control flexible, como se describe a continuación.

Para las notificaciones de Web Push de Android, la insignia se refiere al pequeño ícono mostrado en las notificaciones, no al ícono de la aplicación, y puede personalizarse. Consulte Insignias de Web Push.

---

​

Insignias de Android

El comportamiento de las insignias del ícono de la aplicación Android puede gestionarse a través de categorías de notificación de Android. Puede controlar si una categoría (canal) muestra una insignia y establecer el comportamiento de la insignia por categoría.

---

​

Insignias de Huawei

En dispositivos Huawei, una insignia puede mostrarse como un número o un punto en el ícono de la aplicación, dependiendo de la configuración del dispositivo del usuario. Las insignias ayudan a indicar mensajes no leídos o acciones pendientes, animando a los usuarios a abrir la aplicación. OneSignal le permite controlar los conteos de insignias de Huawei directamente a través del panel de control o la API.

​

Cómo funcionan las insignias de Huawei

La insignia se muestra en el ícono de la aplicación como un conteo numérico o un punto, dependiendo de la configuración del dispositivo del usuario (Configuración > Notificaciones > Insignias de íconos de aplicación). Su llamada a la API controla el conteo subyacente; el dispositivo decide el estilo visual.

​

Parámetros

Parámetro	Tipo	Rango	Descripción
huawei_badge_class	string	—	(Obligatorio) Nombre de clase completamente cualificado de la Activity de lanzamiento de su aplicación (p. ej., com.example.myapp.MainActivity). Indica al sistema Huawei a qué ícono de aplicación colocar la insignia.
huawei_badge_set_num	integer	0–99	Establece la insignia en un número exacto. 0 borra la insignia.
huawei_badge_add_num	integer	1–99	Incrementa el conteo de insignias existente en esta cantidad.

​

Reglas de comportamiento

• huawei_badge_class es obligatorio para cualquier operación de insignia.
• Si se proporcionan tanto huawei_badge_set_num como huawei_badge_add_num, huawei_badge_set_num tiene prioridad.
• Si ninguno se proporciona (pero huawei_badge_class está configurado), el conteo de insignias se incrementa en 1 por defecto.

​

Enviar push de Huawei con insignias

Panel

1. Vaya a Messages > Push o Templates
2. Bajo Platform Settings > Send to Huawei Android > Badge
3. Elija cualquiera de las siguientes opciones:
   • No establecer — la insignia no se ve afectada por esta notificación
   • Establecer en — establece la insignia en un número específico (0-99)
   • Aumentar en — incrementa el conteo de insignias existente (1-99)

API

Use los siguientes parámetros en la API Create message:

• huawei_badge_class — (cadena, requerido para insignia) El nombre de clase completamente cualificado de la activity de lanzamiento de la aplicación (por ejemplo, "com.example.myapp.MainActivity")
• huawei_badge_set_num — (entero, 0-99) Establece el conteo de insignias a este número exacto. Establecer en 0 para borrar la insignia.
• huawei_badge_add_num — (entero, 1-99) Incrementa el conteo de insignias existente en este número. Si se omite junto con huawei_badge_set_num, por defecto incrementa en 1.

Establecer insignia en un número específico:

{
  "huawei_badge_class": "com.example.myapp.MainActivity",
  "huawei_badge_set_num": 5
}

Incrementar insignia en una cantidad específica:

{
  "huawei_badge_class": "com.example.myapp.MainActivity",
  "huawei_badge_add_num": 1
}

Borrar la insignia:

{
  "huawei_badge_class": "com.example.myapp.MainActivity",
  "huawei_badge_set_num": 0
}

​

Borrar insignias

Huawei no borra automáticamente la insignia cuando un usuario abre la aplicación o toca una notificación. Para borrar la insignia, tiene dos opciones:

• A través de la API o el panel: Envíe una notificación con huawei_badge_set_num establecido en 0 (o use Establecer en > 0 en el panel). Puede ser una notificación de datos/en segundo plano si no desea que aparezca una notificación visible.
• A través de código del lado del cliente: Su aplicación puede borrar la insignia localmente usando la API de insignias de Huawei. Esto requiere el permiso com.huawei.android.launcher.permission.CHANGE_BADGE en su AndroidManifest.xml. Consulte la guía de desarrollo de insignias de Huawei para detalles de implementación.

El parámetro huawei_badge_set_num requiere EMUI 10.0.0 o posterior y Push SDK 10.1.0 o posterior. En dispositivos más antiguos, solo se admite huawei_badge_add_num.

---

​

Insignias de iOS

Para asegurar que los contadores de insignias se incrementen correctamente en iOS, debe configurar:

• La OneSignalNotificationServiceExtension
• App Groups

Consulte Configuración del SDK móvil para instrucciones completas.

De forma predeterminada, el SDK de OneSignal:

1. Borrará la insignia del ícono de la aplicación cuando se abra la aplicación.
2. Eliminará las notificaciones del Centro de Notificaciones.

Si desea retener las notificaciones y gestionar la lógica de insignias manualmente (por ejemplo, usando su propio contador o sincronizando el estado entre dispositivos), puede deshabilitar este comportamiento automático.

Casos de uso comunes para el control manual de insignias

• Restablecer la insignia cuando la aplicación se inicia o reanuda
• Incrementar la insignia cuando se recibe una notificación en primer plano
• Decrementar cuando se lee o descarta un mensaje
• Sincronizar el estado de la insignia entre dispositivos o extensiones de aplicación a través de App Groups o su backend

​

Deshabilitar la eliminación automática de notificaciones e insignias

En el info.plist de su aplicación, agregue la Key: OneSignal_disable_badge_clearing con tipo Boolean al Value YES

<key>OneSignal_disable_badge_clearing</key>
<true/>

Esto evita que el SDK elimine automáticamente las notificaciones o restablezca la insignia cuando se abre la aplicación.

​

Gestión nativa de insignias de iOS

Si deshabilita el borrado automático de insignias de OneSignal, puede usar las API nativas de Apple para controlar el comportamiento de las insignias.

Apple deprecó UIApplication.shared.applicationIconBadgeNumber en iOS 17. Ahora debe usar los siguientes métodos del framework UserNotifications:

Establecer contador de insignias

Para establecer la insignia en el ícono de la aplicación a un valor específico:

import UserNotifications
import UIKit

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(5) { error in
    if let error = error {
      print("Fallo al establecer el contador de insignias: \(error.localizedDescription)")
    } else {
      print("Contador de insignias actualizado con éxito.")
    }
  }
} else {
  UIApplication.shared.applicationIconBadgeNumber = 5
}

Obtener contador de insignias actual

iOS no proporciona un método para recuperar el contador de insignias actual del sistema. Debe realizar un seguimiento del contador de insignias en el estado de su aplicación (por ejemplo, usando UserDefaults, el modelo de datos de su aplicación, o sincronizando con su backend).

// Ejemplo: Almacenar y recuperar el contador de insignias usando UserDefaults
let badgeCount = UserDefaults.standard.integer(forKey: "badgeCount")
// Actualizar el contador de insignias según sea necesario
UserDefaults.standard.set(badgeCount, forKey: "badgeCount")

Incrementar o decrementar la insignia

Debe gestionar la lógica de insignias manualmente, ya que los cambios relativos (como +1 o -1) no son compatibles con los payloads. Actualice su contador de insignias almacenado y luego establézcalo:

// Ejemplo: Incrementar el contador de insignias y actualizar la insignia del sistema
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
}

Borrar insignia

Para eliminar la insignia por completo:

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

​

Enviar push de iOS con insignias

Puede establecer el contador de insignias en el panel de OneSignal o usando la API.

Panel

1. Vaya a Messages > Push o Templates.
2. Bajo Platform Settings > Send to Apple iOS > Badges.
3. Elija cualquiera de las siguientes opciones:
   • Establecer a un número específico.
   • Aumentar por una cantidad relativa.

API

Use los siguientes parámetros en la API de Create message:

• ios_badgeType — Establecer a SetTo o Increase.
• ios_badgeCount — El número a establecer o incrementar.

{
  "ios_badgeType": "Increase",
  "ios_badgeCount": 1
}

Al enviar notificaciones push de iOS, el contador de insignias cambia según estas opciones.

Si la aplicación está abierta, el contador de insignias se restablece a menos que deshabilite el borrado automático de insignias.

---

​

Preguntas frecuentes

​

¿Por qué no se incrementa el contador de insignias en iOS?

Asegúrese de haber configurado la OneSignalNotificationServiceExtension y los App Groups. Sin estos, los contadores de insignias no pueden incrementarse correctamente. Consulte Configuración del SDK móvil para obtener instrucciones completas.

​

¿Cómo borro las insignias en Huawei?

Envíe una notificación con huawei_badge_set_num establecido en 0, o use Establecer en > 0 en el panel. También puede usar una notificación de datos/en segundo plano para borrar insignias sin mostrar una notificación visible. Alternativamente, borre la insignia del lado del cliente usando la API de insignias de Huawei.

​

¿Puedo configurar insignias para web push?

No. Las insignias de íconos de aplicación solo son compatibles con iOS, Android y Huawei. Para Android web push, la “insignia” se refiere al pequeño ícono que se muestra en la propia notificación — consulte Insignias de Web Push.

---

​

Páginas relacionadas

Categorías de notificación de Android

Controle la visualización y el comportamiento de las insignias por canal de notificación en Android.

Autorización de Huawei

Configure la mensajería push de Huawei con OneSignal.

Descripción general de Push

Referencia completa de las funciones de notificaciones push, incluidas las insignias de web push.

Configuración del SDK móvil

Configure el SDK de OneSignal, incluidos los requisitos previos de insignias para iOS.