> ## 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.

# Notificações ao vivo Android

> Crie e atualize notificações dinâmicas em tempo real em dispositivos Android usando Notificações ao Vivo do OneSignal. Entregue conteúdo continuamente atualizado dentro de uma única notificação, simulando Atividades ao Vivo do iOS para 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](./mobile-sdk-setup).
* 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](/reference/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.

<Info>
  Consulte [Extensão de Serviço de Notificação Android](./service-extensions#android-notification-service-extension) para mais detalhes.
</Info>

```kotlin NotificationServiceExtention.kt theme={null}
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

<CodeGroup>
  ```xml AndroidManifest.xml theme={null}
    <meta-data android:name="com.onesignal.NotificationServiceExtension"
                android:value="com.onesignal.sample.android.NotificationServiceExtension" />
  ```

  ```xml Example AndroidManifest.xml theme={null}
  <?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>
  ```
</CodeGroup>

### 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.

```kotlin NotificationServiceExtention.kt theme={null}
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](./android-notification-categories) 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.

```kotlin NotificationServiceExtention.kt theme={null}
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

<Info>
  Veja [Layout de notificação personalizada Android](https://developer.android.com/develop/ui/views/notifications/custom-notification) para opções de design avançadas.
</Info>

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

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

```kotlin NotificationServiceExtention.kt theme={null}
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. |

```json Example Live Notification Payload theme={null}
  {
      "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                              |

```kotlin NotificationServiceExtention.kt theme={null}
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`](./push#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 theme={null}
  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 theme={null}
  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 theme={null}
  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"
  }'
```

***

<Check>
  Você criou com sucesso uma Notificação ao Vivo!

  Documentos relacionados:

  * [Extensão de Serviço de Notificação Android](./service-extensions#android-notification-service-extension)
  * [Configuração do SDK Android](./mobile-sdk-setup)
  * [API Create Message](/reference/create-message)
</Check>

***