Crea una notifica

Le notifiche forniscono informazioni brevi e tempestive sugli eventi nella tua app mentre non è in uso. Questo documento mostra come creare una notifica con varie funzionalità. Per un'introduzione all'aspetto delle notifiche su Android, consulta la panoramica delle notifiche. Per un esempio di codice che utilizza le notifiche, consulta la sezione Persone esempio su GitHub.

Il codice in questa pagina utilizza NotificationCompat API della libreria AndroidX. Queste API ti consentono di aggiungere funzionalità disponibili solo sulle versioni più recenti di Android, garantendo al contempo la compatibilità con Android 9 (livello API 28). Tuttavia, alcune funzionalità, come l'azione di risposta in linea, non hanno alcun effetto nelle versioni precedenti.

Aggiungi la libreria AndroidX Core

Sebbene la maggior parte dei progetti creati con Android Studio includa i per usare NotificationCompat, verifica che la tua configurazione a livello di modulo Il file build.gradle include la seguente dipendenza:

dependencies {
    implementation "androidx.core:core:2.2.0"
}

dependencies {
    implementation("androidx.core:core-ktx:2.2.0")
}

Crea una notifica di base

Una notifica nella sua forma più semplice e compatta, nota anche come compressa form: visualizza un'icona, un titolo e una piccola quantità di contenuti di testo. Questo mostra come creare una notifica che l'utente può toccare per avviare attività nella tua app.

Figura 1. Una notifica con un'icona, un titolo e del testo.

Per ulteriori dettagli su ogni parte di una notifica, leggi l'articolo Informazioni sulle notifiche anatomia.

Dichiara l'autorizzazione di runtime

Android 13 (livello API 33) e versioni successive supportano un'autorizzazione di runtime per la pubblicazione di notifiche non esenti (inclusi i servizi in primo piano (FGS)) da un'app.

Nel file manifest dell'app viene visualizzata l'autorizzazione che devi dichiarare nel seguente snippet di codice:

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>

Per maggiori dettagli sulle autorizzazioni di runtime, consulta Autorizzazione di runtime delle notifiche.

Impostare i contenuti della notifica

Per iniziare, imposta i contenuti e il canale della notifica utilizzando un NotificationCompat.Builder . L'esempio seguente mostra come creare una notifica con il parametro seguenti:

• Una piccola icona, impostata da setSmallIcon() Si tratta degli unici contenuti visibili all'utente richiesti.

• Un titolo impostato da setContentTitle().

• Il corpo del testo, impostato da setContentText()

• La priorità delle notifiche, impostata da setPriority() La priorità determina il livello di invasione della notifica su Android 7.1 e in precedenza. Per Android 8.0 e versioni successive, imposta invece l'importanza del canale come come mostrato nella sezione successiva.

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle(textTitle)
        .setContentText(textContent)
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle(textTitle)
        .setContentText(textContent)
        .setPriority(NotificationCompat.PRIORITY_DEFAULT);

Il costruttore NotificationCompat.Builder richiede che tu fornisca un canale ID. Questa azione è necessaria per la compatibilità con Android 8.0 (livello API 26) e in seguito, ma viene ignorato dalle versioni precedenti.

Per impostazione predefinita, il contenuto testuale della notifica viene troncato per rientrare in una riga. Tu può mostrare informazioni aggiuntive creando una notifica espandibile.

Figura 2. Un modello espandibile in modalità compressa ed espansa.

Se vuoi che la notifica duri più a lungo, puoi attivare una la notifica aggiungendo un modello di stile con setStyle() Ad esempio, il seguente codice crea un'area di testo più grande:

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Much longer text that cannot fit one line...")
        .setStyle(NotificationCompat.BigTextStyle()
                .bigText("Much longer text that cannot fit one line..."))
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Much longer text that cannot fit one line...")
        .setStyle(new NotificationCompat.BigTextStyle()
                .bigText("Much longer text that cannot fit one line..."))
        .setPriority(NotificationCompat.PRIORITY_DEFAULT);

Per ulteriori informazioni su altri stili di notifiche di grandi dimensioni, incluso come aggiungere i controlli di riproduzione di un'immagine e di contenuti multimediali, consulta l'articolo Creare un riquadro di notifica.

Creare un canale e stabilire l'importanza

Per poter inviare la notifica su Android 8.0 e versioni successive, devi registrare il tuo canale di notifica dell'app con il di sistema passando un'istanza Da NotificationChannel a createNotificationChannel(). Il seguente codice è bloccato da una condizione nella versione SDK_INT:

private fun createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is not in the Support Library.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        val name = getString(R.string.channel_name)
        val descriptionText = getString(R.string.channel_description)
        val importance = NotificationManager.IMPORTANCE_DEFAULT
        val channel = NotificationChannel(CHANNEL_ID, name, importance).apply {
            description = descriptionText
        }
        // Register the channel with the system.
        val notificationManager: NotificationManager =
            getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        notificationManager.createNotificationChannel(channel)
    }
}

private void createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is not in the Support Library.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        CharSequence name = getString(R.string.channel_name);
        String description = getString(R.string.channel_description);
        int importance = NotificationManager.IMPORTANCE_DEFAULT;
        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, name, importance);
        channel.setDescription(description);
        // Register the channel with the system; you can't change the importance
        // or other notification behaviors after this.
        NotificationManager notificationManager = getSystemService(NotificationManager.class);
        notificationManager.createNotificationChannel(channel);
    }
}

Perché devi creare il canale di notifica prima di pubblicare qualsiasi su Android 8.0 e versioni successive, esegui questo codice appena viene . Puoi chiamare più volte, dato che la creazione di una canale di notifica non esegue alcuna operazione.

Il costruttore NotificationChannel richiede un importance, utilizzando uno dei costanti dal NotificationManager. Questo determina come interrompere l'utente per qualsiasi notifica appartenente a questo canale. Imposta la priorità con setPriority() per supportare Android 7.1 e versioni precedenti, come mostrato nell'esempio precedente.

Anche se è necessario impostare l'importanza o la priorità delle notifiche, come illustrato nell'esempio seguente, il sistema non garantisce il comportamento degli avvisi che ricevi. Nel in alcuni casi, il sistema può modificare il livello di importanza in base ad altri fattori, e l'utente può sempre ridefinire il livello di importanza canale.

Per ulteriori informazioni sul significato dei diversi livelli, consulta importanza delle notifiche standard.

Impostare l'azione di tocco della notifica

Ogni notifica deve rispondere a un tocco, in genere per aprire un'attività nell'app corrispondente alla notifica. A tale scopo, specifica un intent di contenuti definiti con un PendingIntent e lo passiamo setContentIntent().

Il seguente snippet mostra come creare un intent di base per aprire un'attività quando l'utente tocca la notifica:

// Create an explicit intent for an Activity in your app.
val intent = Intent(this, AlertDetails::class.java).apply {
    flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
}
val pendingIntent: PendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE)

val builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        // Set the intent that fires when the user taps the notification.
        .setContentIntent(pendingIntent)
        .setAutoCancel(true)

// Create an explicit intent for an Activity in your app.
Intent intent = new Intent(this, AlertDetails.class);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        // Set the intent that fires when the user taps the notification.
        .setContentIntent(pendingIntent)
        .setAutoCancel(true);

Questo codice chiama setAutoCancel(), che rimuove automaticamente la notifica quando l'utente la tocca.

Il metodo setFlags() mostrata nell'esempio precedente conserva la navigazione prevista dall'utente dopo l'apertura dell'app tramite la notifica. Potresti voler usarlo a seconda del tipo di attività che stai iniziando, che può essere uno di le seguenti:

• Un'attività esistente esclusivamente per le risposte alla notifica. Non c'è motivo che l'utente passi a questa attività durante il normale utilizzo dell'app, in modo che l'attività avvii una nuova attività anziché essere aggiunta all'elenco attività esistente e viceversa . Questo è il tipo di intent creato nel campione precedente.

• Un'attività esistente nel normale flusso dell'app. In questo caso, l'avvio dell'attività crea un back stack in modo che le aspettative dell'utente per i pulsanti Backup e Su sono vengono conservati.

Per saperne di più sui diversi modi per configurare l'intent delle tue notifiche, consulta Avvia un'attività da una notifica.

Mostra la notifica

Per visualizzare la notifica, chiama NotificationManagerCompat.notify(), passando un ID univoco per la notifica e il risultato NotificationCompat.Builder.build(). Ciò è mostrato nell'esempio seguente:

with(NotificationManagerCompat.from(this)) {
    if (ActivityCompat.checkSelfPermission(
            this@MainActivity,
            Manifest.permission.POST_NOTIFICATIONS
        ) != PackageManager.PERMISSION_GRANTED
    ) {
        // TODO: Consider calling
        // ActivityCompat#requestPermissions
        // here to request the missing permissions, and then overriding
        // public fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>,
        //                                        grantResults: IntArray)
        // to handle the case where the user grants the permission. See the documentation
        // for ActivityCompat#requestPermissions for more details.

        return@with
    }
    // notificationId is a unique int for each notification that you must define.
    notify(NOTIFICATION_ID, builder.build())
}

with(NotificationManagerCompat.from(this)) {
   if (ActivityCompat.checkSelfPermission(
           this@MainActivity,
           Manifest.permission.POST_NOTIFICATIONS
       ) != PackageManager.PERMISSION_GRANTED
   ) {
       // TODO: Consider calling
       // ActivityCompat#requestPermissions
       // here to request the missing permissions, and then overriding
       // public void onRequestPermissionsResult(int requestCode, String[] permissions,
       //                                        int[] grantResults)
       // to handle the case where the user grants the permission. See the documentation
       // for ActivityCompat#requestPermissions for more details.

       return
   }
   // notificationId is a unique int for each notification that you must define.
   notify(NOTIFICATION_ID, builder.build())
}

Salva l'ID notifica che trasmetti su NotificationManagerCompat.notify() perché ne avete bisogno per aggiornare o rimuovere il di notifica.

Inoltre, per testare le notifiche di base sui dispositivi con Android 13 e versioni successive, attiva le notifiche manualmente o crea una finestra di dialogo per notifiche di richiesta.

Aggiungere pulsanti di azione

Una notifica può offrire fino a tre pulsanti di azione che consentono all'utente di rispondere velocemente, ad esempio per posticipare un promemoria o rispondere a un messaggio. Ma questi i pulsanti di azione non devono duplicare l'azione eseguita quando l'utente tocca il di notifica.

Figura 3. Una notifica con un pulsante di azione.

Per aggiungere un pulsante di azione, passa PendingIntent alla addAction() . È come impostare l'azione di tocco predefinita per la notifica, ad eccezione del invece di avviare un'attività, puoi eseguire altre operazioni, ad esempio avviare un BroadcastReceiver che esegue un job in background in modo che l'azione non interrompa l'app che è già aperto.

Ad esempio, il seguente codice mostra come inviare un annuncio a un destinatario:

val ACTION_SNOOZE = "snooze"

val snoozeIntent = Intent(this, MyBroadcastReceiver::class.java).apply {
    action = ACTION_SNOOZE
    putExtra(EXTRA_NOTIFICATION_ID, 0)
}
val snoozePendingIntent: PendingIntent =
    PendingIntent.getBroadcast(this, 0, snoozeIntent, 0)
val builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, getString(R.string.snooze),
                snoozePendingIntent)

String ACTION_SNOOZE = "snooze"

Intent snoozeIntent = new Intent(this, MyBroadcastReceiver.class);
snoozeIntent.setAction(ACTION_SNOOZE);
snoozeIntent.putExtra(EXTRA_NOTIFICATION_ID, 0);
PendingIntent snoozePendingIntent =
        PendingIntent.getBroadcast(this, 0, snoozeIntent, 0);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, getString(R.string.snooze),
                snoozePendingIntent);

Per ulteriori informazioni sulla creazione di un BroadcastReceiver per l'esecuzione in background al lavoro, consulta la Panoramica delle trasmissioni.

Se invece vuoi creare una notifica con pulsanti di riproduzione di contenuti multimediali, ad esempio mettere in pausa e saltare tracce, scopri come creare una notifica con contenuti multimediali Google Cloud.

Aggiungi un'azione di risposta diretta

L'azione di risposta diretta, introdotta in Android 7.0 (livello API 24), consente agli utenti e inserire il testo direttamente nella notifica. Il testo viene quindi consegnato al tuo senza aprire un'attività. Ad esempio, puoi utilizzare un'azione di risposta diretta per consentire agli utenti di rispondere ai messaggi o aggiornare gli elenchi di attività dalla notifica.

Figura 4. Toccare "Rispondi" consente di aprire l'input di testo.

L'azione di risposta diretta viene visualizzata come pulsante aggiuntivo nella notifica che consente di aprire un input di testo. Quando l'utente termina di digitare, il sistema allega il testo all'intent specificato per l'azione di notifica e invia intent alla tua app.

Aggiungere il pulsante Rispondi

Per creare un'azione di notifica che supporti la risposta diretta:

1. Crea un'istanza di RemoteInput.Builder che puoi aggiungere all'azione di notifica. Il costruttore di questa classe accetta una stringa utilizzata dal sistema come chiave per l'input di testo. La tua app più tardi utilizza questa chiave per recuperare il testo dell'input.

   Kotlin

     // Key for the string that's delivered in the action's intent.
     private val KEY_TEXT_REPLY = "key_text_reply"
     var replyLabel: String = resources.getString(R.string.reply_label)
     var remoteInput: RemoteInput = RemoteInput.Builder(KEY_TEXT_REPLY).run {
         setLabel(replyLabel)
         build()
     }
     

   Java

     // Key for the string that's delivered in the action's intent.
     private static final String KEY_TEXT_REPLY = "key_text_reply";
   
     String replyLabel = getResources().getString(R.string.reply_label);
     RemoteInput remoteInput = new RemoteInput.Builder(KEY_TEXT_REPLY)
             .setLabel(replyLabel)
             .build();
     

2. Crea un PendingIntent per l'azione di risposta.

   Kotlin

     // Build a PendingIntent for the reply action to trigger.
     var replyPendingIntent: PendingIntent =
         PendingIntent.getBroadcast(applicationContext,
             conversation.getConversationId(),
             getMessageReplyIntent(conversation.getConversationId()),
             PendingIntent.FLAG_UPDATE_CURRENT)
     

   Java

     // Build a PendingIntent for the reply action to trigger.
     PendingIntent replyPendingIntent =
             PendingIntent.getBroadcast(getApplicationContext(),
                     conversation.getConversationId(),
                     getMessageReplyIntent(conversation.getConversationId()),
                     PendingIntent.FLAG_UPDATE_CURRENT);
     

3. Collega l'oggetto RemoteInput a un'azione utilizzando addRemoteInput().

   Kotlin

     // Create the reply action and add the remote input.
     var action: NotificationCompat.Action =
         NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
             getString(R.string.label), replyPendingIntent)
             .addRemoteInput(remoteInput)
             .build()
     

   Java

     // Create the reply action and add the remote input.
     NotificationCompat.Action action =
             new NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
                     getString(R.string.label), replyPendingIntent)
                     .addRemoteInput(remoteInput)
                     .build();
     

4. Applica l'azione a una notifica ed emetti la notifica.

   Kotlin

     // Build the notification and add the action.
     val newMessageNotification = Notification.Builder(context, CHANNEL_ID)
             .setSmallIcon(R.drawable.ic_message)
             .setContentTitle(getString(R.string.title))
             .setContentText(getString(R.string.content))
             .addAction(action)
             .build()
   
     // Issue the notification.
     with(NotificationManagerCompat.from(this)) {
         notificationManager.notify(notificationId, newMessageNotification)
     }
     

   Java

     // Build the notification and add the action.
     Notification newMessageNotification = new Notification.Builder(context, CHANNEL_ID)
             .setSmallIcon(R.drawable.ic_message)
             .setContentTitle(getString(R.string.title))
             .setContentText(getString(R.string.content))
             .addAction(action)
             .build();
   
     // Issue the notification.
     NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
     notificationManager.notify(notificationId, newMessageNotification);
     

Il sistema chiede all'utente di inserire una risposta quando attiva il pulsante dell'utente, come mostrato nella figura 4.

Recuperare l'input dell'utente dalla risposta

Per ricevere input utente dall'interfaccia utente per la risposta alla notifica, chiama RemoteInput.getResultsFromIntent(), passando il valore Intent ricevuto da BroadcastReceiver:

private fun getMessageText(intent: Intent): CharSequence? {
    return RemoteInput.getResultsFromIntent(intent)?.getCharSequence(KEY_TEXT_REPLY)
}

private CharSequence getMessageText(Intent intent) {
    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
    if (remoteInput != null) {
        return remoteInput.getCharSequence(KEY_TEXT_REPLY);
    }
    return null;
 }

Dopo aver elaborato l'SMS, aggiorna la notifica chiamando NotificationManagerCompat.notify() con lo stesso ID e tag, se utilizzato. Questo è necessario nascondere l'interfaccia utente per la risposta diretta e confermare all'utente che la sua risposta vengono ricevuti ed elaborati correttamente.

// Build a new notification, which informs the user that the system
// handled their interaction with the previous notification.
val repliedNotification = Notification.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_message)
        .setContentText(getString(R.string.replied))
        .build()

// Issue the new notification.
NotificationManagerCompat.from(this).apply {
    notificationManager.notify(notificationId, repliedNotification)
}

// Build a new notification, which informs the user that the system
// handled their interaction with the previous notification.
Notification repliedNotification = new Notification.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_message)
        .setContentText(getString(R.string.replied))
        .build();

// Issue the new notification.
NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
notificationManager.notify(notificationId, repliedNotification);

Quando lavori con questa nuova notifica, utilizza il contesto che viene passato del destinatario onReceive() .

Aggiungi la risposta in fondo alla notifica chiamando setRemoteInputHistory() Tuttavia, se stai creando un'app di messaggistica, devi creare un sistema di messaggistica notifica e aggiungere nuovo messaggio alla conversazione.

Per ulteriori consigli sulle notifiche da un'app di messaggistica, consulta la sezione su best practice per le app di messaggistica.

Aggiungere una barra di avanzamento

Le notifiche possono includere un indicatore di avanzamento animato che mostra agli utenti lo stato di un'operazione in corso.

Figura 5. La barra di avanzamento durante per eseguire un'operazione.

Se puoi stimare in qualsiasi momento la percentuale di completamento dell'operazione, utilizza la forma "determinata" dell'indicatore, come mostrato nella figura 5, chiamando setProgress(max, progress, false). Il primo parametro corrisponde al valore "complete" come 100. Il secondo è quanto è completo. L'ultimo indica che si tratta di un determinato avanzamento .

Man mano che l'operazione procede, chiama continuamente setProgress(max, progress, false) con un valore aggiornato per progress ed emetti di nuovo la notifica, come come mostrato nell'esempio che segue.

val builder = NotificationCompat.Builder(this, CHANNEL_ID).apply {
    setContentTitle("Picture Download")
    setContentText("Download in progress")
    setSmallIcon(R.drawable.ic_notification)
    setPriority(NotificationCompat.PRIORITY_LOW)
}
val PROGRESS_MAX = 100
val PROGRESS_CURRENT = 0
NotificationManagerCompat.from(this).apply {
    // Issue the initial notification with zero progress.
    builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false)
    notify(notificationId, builder.build())

    // Do the job that tracks the progress here.
    // Usually, this is in a worker thread.
    // To show progress, update PROGRESS_CURRENT and update the notification with:
    // builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
    // notificationManager.notify(notificationId, builder.build());

    // When done, update the notification once more to remove the progress bar.
    builder.setContentText("Download complete")
            .setProgress(0, 0, false)
    notify(notificationId, builder.build())
}

...
NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID);
builder.setContentTitle("Picture Download")
        .setContentText("Download in progress")
        .setSmallIcon(R.drawable.ic_notification)
        .setPriority(NotificationCompat.PRIORITY_LOW);

// Issue the initial notification with zero progress.
int PROGRESS_MAX = 100;
int PROGRESS_CURRENT = 0;
builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
notificationManager.notify(notificationId, builder.build());

// Do the job that tracks the progress here.
// Usually, this is in a worker thread.
// To show progress, update PROGRESS_CURRENT and update the notification with:
// builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
// notificationManager.notify(notificationId, builder.build());

// When done, update the notification once more to remove the progress bar.
builder.setContentText("Download complete")
        .setProgress(0,0,false);
notificationManager.notify(notificationId, builder.build());

Al termine dell'operazione, il valore di progress deve corrispondere a max. Puoi uscire dalla barra di avanzamento per mostrare che l'operazione è stata completata o rimuoverla. In entrambi i casi, aggiorna il testo della notifica per indicare che l'operazione è stata completata. Per rimuovere la barra di avanzamento, chiama setProgress(0, 0, false).

Per visualizzare una barra di avanzamento indeterminata (una barra che non indica la percentuale di completamento), chiama setProgress(0, 0, true). Il risultato è un indicatore che ha lo stesso stile della barra di avanzamento precedente, tranne che è uno stile continuo che non indica il completamento. L'animazione di avanzamento viene eseguita fino al chiami setProgress(0, 0, false) e poi aggiorni la notifica per rimuovere l'indicatore di attività.

Ricordati di modificare il testo della notifica per indicare che l'operazione completato.

Imposta una categoria a livello di sistema

Android utilizza categorie predefinite a livello di sistema per stabilire se disturbare l'utente riceve una notifica quando attiva la modalità Non disturbare. .

Se la notifica rientra in una delle categorie definite in NotificationCompat, ad esempio CATEGORY_ALARM, CATEGORY_REMINDER, CATEGORY_EVENT, o CATEGORY_CALL: dichiarazione passando la categoria appropriata al setCategory():

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setCategory(NotificationCompat.CATEGORY_MESSAGE)

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setCategory(NotificationCompat.CATEGORY_MESSAGE);

Il sistema utilizza queste informazioni sulla categoria di notifica per effettuare decisioni relative alla visualizzazione delle notifiche quando il dispositivo è in modalità Non Disturbare. Tuttavia, non è necessario impostare una categoria a livello di sistema. Procedi solo se le notifiche corrispondono a una delle categorie definite in NotificationCompat.

Mostra un messaggio urgente

L'app potrebbe dover mostrare un messaggio urgente e a tempo, ad esempio una chiamata in arrivo o una sveglia che suona. In queste situazioni, puoi associare una intent a schermo intero con la tua notifica.

Quando la notifica viene richiamata, gli utenti vedono una delle seguenti opzioni, a seconda lo stato di blocco del dispositivo:

• Se il dispositivo dell'utente è bloccato, viene visualizzata un'attività a schermo intero che copre schermata di blocco.
• Se il dispositivo dell'utente è sbloccato, la notifica viene visualizzata in una finestra espansa modulo che include opzioni per la gestione o l'eliminazione della notifica.

Il seguente snippet di codice mostra come associare la notifica a per intent a schermo intero:

val fullScreenIntent = Intent(this, ImportantActivity::class.java)
val fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
    fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT)

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setFullScreenIntent(fullScreenPendingIntent, true)

Intent fullScreenIntent = new Intent(this, ImportantActivity.class);
PendingIntent fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
        fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setFullScreenIntent(fullScreenPendingIntent, true);

Impostazione della visibilità della schermata di blocco

Per controllare il livello di dettaglio visibile nella notifica dalla schermata di blocco, chiama setVisibility() e specifica uno dei seguenti valori:

• VISIBILITY_PUBLIC: l'intero contenuto della notifica viene visualizzato nella schermata di blocco.

• VISIBILITY_SECRET: nessuna parte della notifica viene mostrata sulla schermata di blocco.

• VISIBILITY_PRIVATE: solo le informazioni di base, come l'icona e i contenuti della notifica viene mostrato nella schermata di blocco. L'intero contenuto della notifica non .

Quando imposti VISIBILITY_PRIVATE, puoi anche fornire una versione alternativa dei contenuti della notifica che nasconde determinati dettagli. Ad esempio, un'app per SMS potrebbe visualizzare la notifica "Hai 3 nuovi SMS", ma nasconde i contenuti del messaggio e i mittenti. Per offrire questa alternativa di notifica, crea prima la notifica alternativa NotificationCompat.Builder come al solito. Quindi, allega la notifica alternativa alla normale notifica con setPublicVersion()

Ricorda che l'utente ha sempre il massimo controllo sul fatto che la sua sono visibili nella schermata di blocco e puoi controllarle in base alle canali di notifica dell'app.

Aggiornare una notifica

Per aggiornare una notifica dopo averla emessa, chiama il numero NotificationManagerCompat.notify() di nuovo, trasmettendo lo stesso ID usato in precedenza. Se la notifica precedente viene ignorata, ne viene creata una nuova .

Se vuoi, puoi chiamare setOnlyAlertOnce() in modo che la notifica interrompa l'utente con suoni, vibrazioni o immagini indizi: solo la prima volta che viene visualizzata la notifica e non per in seguito aggiornamenti.

Rimuovere una notifica

Le notifiche rimangono visibili fino a quando si verifica una delle seguenti condizioni:

• L'utente ignora la notifica.
• L'utente tocca la notifica se chiami setAutoCancel() quando crei la notifica.
• Chiami cancel() per un ID notifica specifico. Questo metodo elimina anche notifiche.
• Tu chiami cancelAll(), che rimuove tutte le notifiche inviate in precedenza.
• Se imposti un timeout durante la creazione della notifica, utilizzando setTimeoutAfter(), viene trascorsa la durata specificata. Se necessario, puoi annullare una notifica prima del timeout specificato per il tempo necessario.

Best practice per le app di messaggistica

Tieni presente le best practice elencate qui quando crei notifiche per le tue app di messaggistica e chat.

Usa Messaggistica

A partire da Android 7.0 (livello API 24), Android fornisce uno stile di notifica specifico per i contenuti dei messaggi. L'utilizzo del NotificationCompat.MessagingStyle puoi modificare diverse etichette visualizzate nella notifica, tra cui il titolo della conversazione, i messaggi aggiuntivi e la visualizzazione dei contenuti la notifica.

Il seguente snippet di codice mostra come personalizzare lo stile di una notifica utilizzando la classe MessagingStyle.

val user = Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build()

val notification = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("2 new messages with $sender")
    .setContentText(subject)
    .setSmallIcon(R.drawable.new_message)
    .setStyle(NotificationCompat.MessagingStyle(user)
        .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson())
        .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson())
    )
    .build()

Person user = new Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build();

Notification notification = new NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("2 new messages with " + sender)
    .setContentText(subject)
    .setSmallIcon(R.drawable.new_message)
    .setStyle(new NotificationCompat.MessagingStyle(user)
        .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson())
        .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson())
    )
    .build();

A partire da Android 9.0 (livello API 28), è necessario utilizzare anche la classe Person per ottenere un rendering ottimale della notifica e dei relativi avatar.

Quando usi NotificationCompat.MessagingStyle, segui questi passaggi:

• Chiama MessagingStyle.setConversationTitle() per impostare un titolo per le chat di gruppo con più di due persone. Un buon titolo della conversazione potrebbe essere il nome della chat di gruppo o, in caso contrario, avere un nome, un elenco dei partecipanti alla conversazione. Senza questo, il messaggio potrebbe essere scambiato per una conversazione a due il mittente del messaggio più recente nella conversazione.
• Utilizza la MessagingStyle.setData() per includere messaggi multimediali come le immagini. Tipi MIME del pattern image/* sono supportati.

Usa la risposta diretta

Risposta diretta consente a un utente di rispondere in linea a un messaggio.

• Dopo che l'utente risponde con l'azione di risposta in linea, utilizza MessagingStyle.addMessage() aggiornare la notifica MessagingStyle e non ritirare o annullare il notifica. Se la notifica non viene annullata, l'utente può inviare più risposte dalla notifica.
• Per rendere l'azione di risposta integrata compatibile con Wear OS, chiama Action.WearableExtender.setHintDisplayInlineAction(true)
• Utilizza la addHistoricMessage() per fornire il contesto di una conversazione di risposta diretta aggiungendo il metodo messaggi alla notifica.

Attiva Risposta rapida

• Per attivare Risposta rapida, chiama setAllowGeneratedResponses(true) sull'azione di risposta. In questo modo le risposte di Risposta rapida sono disponibili per utenti quando la notifica è collegata a un dispositivo Wear OS. Risposta rapida vengono generate da un modello di machine learning interamente sull'orologio utilizzando il contesto fornito da NotificationCompat.MessagingStyle di notifica e nessun dato viene caricato su internet per generare diverse.

Aggiungi metadati delle notifiche

• Assegna i metadati delle notifiche per indicare al sistema come gestire le notifiche dell'app quando il dispositivo è in modalità Do Not Disturb mode. Ad esempio: utilizza la addPerson() o setCategory(Notification.CATEGORY_MESSAGE) per ignorare la modalità Non disturbare.