Pular para o conteúdo principal
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" />

​
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

PropriedadeObrigatóriaDescrição
keySimUsado para carregar a IU de notificação correta.
eventSimA ação a executar na Notificação ao Vivo.
event_attributesNãoDados estáticos usados para inicializar a Notificação ao Vivo; um schema autodefinido que define os dados que sua notificação precisa.
event_updatesNãoConteú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:
EventoDescriçãoCampos obrigatórios
startInicia uma Notificação ao Vivo com dados estáticos e dinâmicos.event_attributes, event_updates
updateAtualiza a Notificação ao Vivo com novos dados dinâmicos.event_updates
endTermina 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: