Notificações ao vivo Android

As Notificações ao Vivo Android do OneSignal permitem que você envie atualizações em tempo real para uma única notificação, reduzindo desordem e melhorando o engajamento. Essas notificações permanecem persistentes e atualizam seu conteúdo dinamicamente—ideais para placares esportivos, progresso de download ou rastreamento de eventos. Para receber Notificações ao Vivo, usuários Android devem ter notificações push habilitadas.

Requisitos

Seu aplicativo deve usar a versão mais recente do SDK OneSignal.
Usuários Android devem ter permissões de notificação push habilitadas.

Notificações ao vivo vs. push padrão

Diferente das notificações push regulares, que enviam uma nova notificação cada vez, as Notificações ao Vivo usam uma única notificação atualizada ao longo do tempo. As atualizações são enviadas via API Create Message usando o mesmo collapse_id.

Configuração

1. Implementar uma Extensão de Serviço de Notificação

Crie uma classe NotificationServiceExtension que implementa INotificationServiceExtension. Esta classe intercepta notificações recebidas e pode modificá-las ou substituí-las.

Consulte Extensão de Serviço de Notificação Android para mais detalhes.

NotificationServiceExtention.kt

package com.onesignal.sample.android

import android.app.NotificationChannel
import android.app.NotificationManager
import android.content.Context
import android.os.Build
import com.onesignal.notifications.INotificationReceivedEvent
import com.onesignal.notifications.INotificationServiceExtension
import org.json.JSONObject
import java.util.logging.Logger

class NotificationServiceExtension : INotificationServiceExtension {
  override fun onNotificationReceived(event: INotificationReceivedEvent) {
        val context = event.context
        val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
            ?: run {
                logger.warning("NotificationManager not available.")
                return
            }

        notificationManager.let {
            if (!notificationChannelsCreated) {
                createNotificationChannels(notificationManager)
            }
        }

        // Use `additional_data` para enviar o payload da Notificação ao Vivo.
    		val additionalData = event.notification.additionalData
        val liveNotificationPayload = additionalData?.optJSONObject("live_notification")
        if (liveNotificationPayload == null) {
            logger.info("Nenhum payload de notificação ao vivo encontrado. Mostrando notificação original.")
            return
        }

        event.preventDefault()
        handleLiveNotification(event, liveNotificationPayload, notificationManager, context)
    }
}

2. Adicionar a extensão ao Android Manifest

  <meta-data android:name="com.onesignal.NotificationServiceExtension"
              android:value="com.onesignal.sample.android.NotificationServiceExtension" />

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:name=".MainApplication"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.OneSignalAndroidSample"
        tools:targetApi="31">
        <meta-data android:name="com.onesignal.NotificationServiceExtension"
            android:value="com.onesignal.sample.android.NotificationServiceExtension" />
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

3. Criar tipos de Notificação ao Vivo

Um Tipo de Notificação ao Vivo indica qual Notificação ao Vivo iniciar.

Definir chaves

As Notificações ao Vivo são referenciadas por uma key, que determina como as atualizações são roteadas.

NotificationServiceExtention.kt

private const val PROGRESS_LIVE_NOTIFICATION = "progress"

Criar canais de notificação

Os canais definem como as notificações se comportam (som, vibração, aparência). Você deve criar canais para seus tipos de Notificação ao Vivo. Recomendamos:

Baixa Importância para notificações de progresso
Desabilitar badges
Manter som e vibração ao mínimo

Veja Categorias de Canal de Notificação Android para mais informações.

Projetar a Notificação ao Vivo

Ao projetar uma Notificação ao Vivo, você tem a flexibilidade de criar um design de notificação para cada tipo de atualização. Cada design que você criar deve ser atribuído a um tipo específico, permitindo apresentações variadas de uma Notificação ao Vivo.

NotificationServiceExtention.kt

private fun updateProgressNotification(
        liveNotificationUpdates: JSONObject,
        context: Context,
        notificationManager: NotificationManager
    ) {
        val currentProgress = liveNotificationUpdates.optInt("current_progress", 0)

        val builder = NotificationCompat.Builder(context, PROGRESS_CHANNEL_ID)
            .setContentTitle("Progress Live Notifications")
            .setContentText("It's working...")
            .setSmallIcon(android.R.drawable.ic_media_play)
            .setLargeIcon(BitmapFactory.decodeResource(context.resources, android.R.drawable.ic_dialog_info))
            .setOngoing(true)
            .setOnlyAlertOnce(true)
            .setProgress(100, currentProgress, false)
            .setAutoCancel(false) // Prevenir descarte automático da notificação até que você defina o evento de término

        notificationManager.notify(keyMap[PROGRESS_LIVE_NOTIFICATION]!!, builder.build())
        logger.info("Atualizado notificação de progresso com progresso: $currentProgress")
    }

Considerações de design:

Ícone pequeno e cor de destaque
Ícone grande
Imagem grande
Botões de ação

Veja Layout de notificação personalizada Android para opções de design avançadas.

4. Extrair o payload da Notificação ao Vivo

As Notificações ao Vivo usam o campo additional_data para passar conteúdo estruturado.

NotificationServiceExtention.kt

val additionalData = event.notification.additionalData
val liveNotificationPayload = additionalData?.optJSONObject("live_notification")

Schema da Notificação ao Vivo

Propriedade	Obrigatória	Descrição
`key`	Sim	Usado para carregar a IU de notificação correta.
`event`	Sim	A ação a executar na Notificação ao Vivo.
`event_attributes`	Não	Dados estáticos usados para inicializar a Notificação ao Vivo; um schema autodefinido que define os dados que sua notificação precisa.
`event_updates`	Não	Conteúdo dinâmico da Notificação ao Vivo. Deve estar em conformidade com a interface ContentState definida dentro da Notificação ao Vivo do seu aplicativo.

Example Live Notification Payload

  {
      "key": "celtics-vs-lakers",
      "event": "start",
      "event_attributes": {
          "homeTeam": "Celtics",
          "awayTeam": "Lakers",
          "game": "Finals Game 1"
      },
      "event_updates": {
          "quarter": 1,
          "homeScore": 0,
          "awayScore": 0,
      }
  }

5. Tratar eventos de Notificação ao Vivo

Cada Notificação ao Vivo deve responder aos seguintes eventos:

Evento	Descrição	Campos obrigatórios
`start`	Inicia uma Notificação ao Vivo com dados estáticos e dinâmicos.	`event_attributes`, `event_updates`
`update`	Atualiza a Notificação ao Vivo com novos dados dinâmicos.	`event_updates`
`end`	Termina e remove a Notificação ao Vivo.	Nenhum

NotificationServiceExtention.kt

val liveNotificationEvent = liveNotificationPayload.optString("event", "")

Iniciar uma Notificação ao Vivo

Quando estiver pronto para iniciar uma Notificação ao Vivo:

Defina event_attributes para inicializar os dados estáticos para a Notificação ao Vivo. Esses dados não mudarão durante o tempo de vida da Notificação ao Vivo.
Defina dados event_updates para inicializar os dados dinâmicos para a Notificação ao Vivo. Estes são os dados que podem e irão mudar durante o tempo de vida da Notificação ao Vivo.
Um collapse_id para garantir que cada atualização substitua a anterior. Este ID deve ser único para a Notificação ao Vivo para garantir que atualizações subsequentes sejam refletidas na mesma notificação.

curl

  curl -X "POST" "https://api.onesignal.com/notifications" \
       -H 'Authorization: key YOUR_REST_API_KEY' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "THE_UNIQUE_ID_FOR_THIS_LIVE_NOTIFICATION",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "start",
        "event_attributes": {},
        "event_updates": {
          "current_progress": 0
        }
      }
    },
    "headings": {
      "en": "Start"
    },
    "contents": {
      "en": "Starting Live Notification"
    },
    "include_aliases": {
      "external_id": ["EID1", "EID2"]
    },
    "target_channel": "push"
  }'

Atualizar Notificação ao Vivo

Você pode atualizar a Notificação ao Vivo quantas vezes quiser, desde que seja iniciada primeiro.

Defina dados event_updates para inicializar os dados dinâmicos para a Notificação ao Vivo. Estes são os dados que podem e irão mudar durante o tempo de vida da Notificação ao Vivo e informam com o que atualizar o conteúdo da sua Notificação ao Vivo.

Exemplo de solicitação cURL

curl

  curl -X "POST" "https://api.onesignal.com/notifications" \
       -H 'Authorization: key YOUR_REST_API_KEY' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "THE_UNIQUE_ID_FOR_THIS_LIVE_NOTIFICATION",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "update",
  			"event_attributes": {},
        "event_updates": {
          "current_progress": 80
        }
      }
    },
    "headings": {
      "en": "Update"
    },
    "contents": {
      "en": "Updating Live Notification"
    },
    "include_aliases": {
      "external_id": ["EID1", "EID2"]
    },
    "target_channel": "push"
  }'

Encerrar Notificação ao Vivo

Exemplo de solicitação cURL

curl

  curl -X "POST" "https://api.onesignal.com/notifications" \
       -H 'Authorization: key YOUR_REST_API_KEY' \
       -H 'Content-Type: application/json; charset=utf-8' \
       -d $'{
    "app_id": "YOUR_APP_ID",
    "isAndroid": true,
    "collapse_id": "THE_UNIQUE_ID_FOR_THIS_LIVE_NOTIFICATION",
    "data": {
      "live_notification": {
        "key": "progress",
        "event": "dismiss"
      }
    },
    "headings": {
      "en": "Dismissing"
    },
    "contents": {
      "en": "Dismissing Live Notification"
    },
    "include_aliases": {
      "external_id": ["EID1", "EID2"]
    },
    "target_channel": "push"
  }'

Você criou com sucesso uma Notificação ao Vivo!Documentos relacionados:

Documentação de desenvolvedor

SDKs móveis

SDKs web

Atividades ao Vivo

Configuração de Desktop & Watch

Notificações ao vivo Android

Requisitos

Notificações ao vivo vs. push padrão

Configuração

1. Implementar uma Extensão de Serviço de Notificação

2. Adicionar a extensão ao Android Manifest

3. Criar tipos de Notificação ao Vivo

Definir chaves

Criar canais de notificação

Projetar a Notificação ao Vivo

4. Extrair o payload da Notificação ao Vivo

Schema da Notificação ao Vivo

5. Tratar eventos de Notificação ao Vivo

Iniciar uma Notificação ao Vivo

Atualizar Notificação ao Vivo

Encerrar Notificação ao Vivo

​Requisitos

​Notificações ao vivo vs. push padrão

​Configuração

​1. Implementar uma Extensão de Serviço de Notificação

​2. Adicionar a extensão ao Android Manifest

​3. Criar tipos de Notificação ao Vivo

​Definir chaves

​Criar canais de notificação

​Projetar a Notificação ao Vivo

​4. Extrair o payload da Notificação ao Vivo

​Schema da Notificação ao Vivo

​5. Tratar eventos de Notificação ao Vivo

​Iniciar uma Notificação ao Vivo

​Atualizar Notificação ao Vivo

​Encerrar Notificação ao Vivo

Requisitos

Notificações ao vivo vs. push padrão

Configuração

1. Implementar uma Extensão de Serviço de Notificação

2. Adicionar a extensão ao Android Manifest

3. Criar tipos de Notificação ao Vivo

Definir chaves

Criar canais de notificação

Projetar a Notificação ao Vivo

4. Extrair o payload da Notificação ao Vivo

Schema da Notificação ao Vivo

5. Tratar eventos de Notificação ao Vivo

Iniciar uma Notificação ao Vivo

Atualizar Notificação ao Vivo

Encerrar Notificação ao Vivo