Créer une notification

Les notifications fournissent des informations courtes et opportunes sur les événements de votre application lorsqu'elle n'est pas utilisée. Ce document explique comment créer une notification avec diverses fonctionnalités. Pour découvrir comment les notifications s'affichent sur Android, consultez la présentation des notifications. Pour obtenir un exemple de code utilisant des notifications, consultez l'exemple People sur GitHub.

Le code de cette page utilise les API NotificationCompat de la bibliothèque AndroidX. Ces API vous permettent d'ajouter des fonctionnalités disponibles uniquement sur les versions plus récentes d'Android, tout en conservant la rétrocompatibilité avec Android 9 (niveau d'API 28). Toutefois, certaines fonctionnalités, comme l'action de réponse intégrée, ne sont pas exécutées dans les versions antérieures.

Ajouter la bibliothèque principale AndroidX

Bien que la plupart des projets créés avec Android Studio incluent les dépendances nécessaires pour utiliser NotificationCompat, vérifiez que votre fichier build.gradle au niveau du module inclut la dépendance suivante:

Groovy

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

Kotlin

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

Remarque :Les autres bibliothèques du groupe androidx incluent également core en tant que dépendance transitive. Si vous utilisez déjà d'autres API Jetpack, vous pouvez avoir accès à NotificationCompat sans avoir besoin de cette dépendance exacte.

Créer une notification de base

Une notification dans sa forme la plus basique et compacte (également appelée forme réduite) affiche une icône, un titre et une petite quantité de texte. Cette section explique comment créer une notification que l'utilisateur peut appuyer pour lancer une activité dans votre application.

Figure 1 : Notification avec une icône, un titre et du texte.

Pour en savoir plus sur chaque partie d'une notification, consultez la section Anatomie d'une notification.

Déclarer l'autorisation d'exécution

Android 13 (niveau d'API 33) ou version ultérieure est compatible avec une autorisation d'exécution pour l'affichage de notifications non exemptées (y compris les services de premier plan) à partir d'une application.

L'autorisation que vous devez déclarer dans le fichier manifeste de votre application apparaît dans l'extrait de code suivant:

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

Pour en savoir plus sur les autorisations d'exécution, consultez la section Autorisation d'exécution des notifications.

Définir le contenu de la notification

Pour commencer, définissez le contenu et le canal de la notification à l'aide d'un objet NotificationCompat.Builder. L'exemple suivant montre comment créer une notification avec les éléments suivants:

• Petite icône, définie par setSmallIcon(). Il s'agit du seul contenu visible par l'utilisateur qui est obligatoire.

• Titre défini par setContentTitle().

• Corps du texte, défini par setContentText().

• Priorité de la notification, définie par setPriority(). La priorité détermine le niveau d'intrusion de la notification sur Android 7.1 et versions antérieures. Pour Android 8.0 et versions ultérieures, définissez plutôt l'importance du canal comme indiqué dans la section suivante.

Kotlin

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

Java

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

Le constructeur NotificationCompat.Builder nécessite que vous fournissiez un ID de chaîne. Cette valeur est requise pour la compatibilité avec Android 8.0 (niveau d'API 26) et les versions ultérieures, mais elle est ignorée par les versions antérieures.

Par défaut, le contenu textuel de la notification est tronqué pour tenir sur une seule ligne. Vous pouvez afficher des informations supplémentaires en créant une notification extensible.

Figure 2. Notification à développer dans ses formes réduite et développée.

Si vous souhaitez que votre notification soit plus longue, vous pouvez activer une notification extensible en ajoutant un modèle de style avec setStyle(). Par exemple, le code suivant crée une zone de texte plus grande:

Kotlin

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)

Java

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);

Pour en savoir plus sur les autres styles de notifications de grande taille, y compris comment ajouter une image et des commandes de lecture multimédia, consultez Créer une notification à développer.

Créer un canal et définir son importance

Avant de pouvoir envoyer la notification sur Android 8.0 et versions ultérieures, enregistrez le canal de notification de votre application auprès du système en transmettant une instance de NotificationChannel à createNotificationChannel(). Le code suivant est bloqué par une condition sur la version SDK_INT:

Kotlin

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)
    }
}

Java

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);
    }
}

Étant donné que vous devez créer le canal de notification avant de publier des notifications sur Android 8.0 et versions ultérieures, exécutez ce code dès le démarrage de votre application. Vous pouvez appeler cette méthode plusieurs fois, car la création d'un canal de notification existant n'effectue aucune opération.

Le constructeur NotificationChannel nécessite un importance, à l'aide de l'une des constantes de la classe NotificationManager. Ce paramètre détermine comment interrompre l'utilisateur pour toute notification appartenant à ce canal. Définissez la priorité avec setPriority() pour prendre en charge Android 7.1 et versions antérieures, comme indiqué dans l'exemple précédent.

Bien que vous deviez définir l'importance ou la priorité de la notification comme indiqué dans l'exemple suivant, le système ne garantit pas le comportement de l'alerte. Dans certains cas, le système peut modifier le niveau d'importance en fonction d'autres facteurs. L'utilisateur peut toujours redéfinir le niveau d'importance d'un canal donné.

Pour en savoir plus sur la signification des différents niveaux, consultez la page sur les niveaux d'importance des notifications.

Définir l'action à effectuer en appuyant sur la notification

Chaque notification doit répondre à un appui, généralement pour ouvrir une activité dans votre application qui correspond à la notification. Pour ce faire, spécifiez un intent de contenu défini avec un objet PendingIntent et transmettez-le à setContentIntent().

L'extrait de code suivant montre comment créer un intent de base pour ouvrir une activité lorsque l'utilisateur appuie sur la notification:

Kotlin

// 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)

Java

// 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);

Ce code appelle setAutoCancel(), qui supprime automatiquement la notification lorsque l'utilisateur appuie dessus.

La méthode setFlags() illustrée dans l'exemple précédent préserve l'expérience de navigation attendue par l'utilisateur après l'ouverture de votre application à l'aide de la notification. Vous pouvez l'utiliser en fonction du type d'activité que vous lancez, qui peut être l'un des suivants:

• Activité qui existe exclusivement pour les réponses à la notification. Il n'y a aucune raison pour que l'utilisateur accède à cette activité lors d'une utilisation normale de l'application. L'activité lance donc une nouvelle tâche au lieu d'être ajoutée à la pile de tâches et de retour existante de votre application. Il s'agit du type d'intent créé dans l'exemple précédent.

• Activité qui existe dans le flux d'application normal de votre application. Dans ce cas, le démarrage de l'activité crée une pile "Retour" afin que les attentes de l'utilisateur concernant les boutons "Retour" et "Haut" soient préservées.

Pour en savoir plus sur les différentes façons de configurer l'intent de votre notification, consultez la section Démarrer une activité à partir d'une notification.

Afficher la notification

Pour afficher la notification, appelez NotificationManagerCompat.notify() en lui transmettant un ID unique pour la notification et le résultat de NotificationCompat.Builder.build(). Ce processus est illustré dans l'exemple suivant :

Kotlin

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())
}

Java

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())
}

Enregistrez l'ID de notification que vous transmettez à NotificationManagerCompat.notify(), car vous en avez besoin lorsque vous souhaitez mettre à jour ou supprimer la notification.

De plus, pour tester les notifications de base sur les appareils équipés d'Android 13 ou version ultérieure, activez les notifications manuellement ou créez une boîte de dialogue pour demander des notifications.

Remarque :Depuis Android 8.1 (niveau d'API 27), les applications ne peuvent pas émettre une notification sonore plus d'une fois par seconde. Si votre application publie plusieurs notifications en une seconde, elles s'affichent toutes comme prévu, mais seule la première notification par seconde est annoncée au moyen d'un son.

Ajouter des boutons d'action

Une notification peut proposer jusqu'à trois boutons d'action permettant à l'utilisateur de répondre rapidement, par exemple pour mettre en veille un rappel ou répondre à un message texte. Toutefois, ces boutons d'action ne doivent pas dupliquer l'action effectuée lorsque l'utilisateur appuie sur la notification.

Figure 3. Notification avec un bouton d'action

Pour ajouter un bouton d'action, transmettez un PendingIntent à la méthode addAction(). Cela revient à configurer l'action par défaut de la notification, sauf qu'au lieu de lancer une activité, vous pouvez effectuer d'autres actions, comme démarrer un BroadcastReceiver qui effectue une tâche en arrière-plan afin que l'action n'interrompe pas l'application déjà ouverte.

Par exemple, le code suivant montre comment envoyer une diffusion à un récepteur spécifique:

Kotlin

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)

Java

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);

Pour en savoir plus sur la création d'un BroadcastReceiver pour exécuter des tâches en arrière-plan, consultez la présentation des diffusions.

Si vous essayez plutôt de créer une notification avec des boutons de lecture multimédia, par exemple pour mettre en pause et sauter des titres, découvrez comment créer une notification avec des commandes multimédias.

Remarque :Sous Android 10 (niveau d'API 29) et versions ultérieures, la plate-forme génère automatiquement des boutons d'action de notification si une application ne fournit pas les siens. Si vous ne souhaitez pas que les notifications de votre application affichent des suggestions de réponses ou d'actions, vous pouvez désactiver les réponses et les actions générées par le système à l'aide de setAllowGeneratedReplies() et de setAllowSystemGeneratedContextualActions().

Ajouter une action de réponse directe

L'action de réponse directe, introduite dans Android 7.0 (niveau d'API 24), permet aux utilisateurs de saisir du texte directement dans la notification. Le texte est ensuite envoyé à votre application sans ouvrir d'activité. Par exemple, vous pouvez utiliser une action de réponse directe pour permettre aux utilisateurs de répondre aux SMS ou de mettre à jour des listes de tâches depuis la notification.

Figure 4. Appuyer sur le bouton "Répondre" ouvre la saisie de texte.

L'action de réponse directe s'affiche sous la forme d'un bouton supplémentaire dans la notification qui ouvre une zone de saisie de texte. Lorsque l'utilisateur a terminé de saisir du texte, le système associe la réponse textuelle à l'intent que vous spécifiez pour l'action de notification et envoie l'intent à votre application.

Ajouter le bouton de réponse

Pour créer une action de notification compatible avec la réponse directe, procédez comme suit:

1. Créez une instance de RemoteInput.Builder que vous pouvez ajouter à votre action de notification. Le constructeur de cette classe accepte une chaîne que le système utilise comme clé pour la saisie de texte. Votre application utilise ensuite cette clé pour récupérer le texte de la saisie.

   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. Créez un PendingIntent pour l'action de réponse.

   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);
     

   Attention:Si vous réutilisez un PendingIntent, un utilisateur peut répondre à une conversation différente de celle qu'il avait l'intention de mener. Vous devez fournir un code de requête différent pour chaque conversation ou un intent qui ne renvoie pas true lorsque vous appelez equals() sur l'intent de réponse d'une autre conversation. L'ID de conversation est souvent transmis dans le bundle d'extras de l'intent, mais il est ignoré lorsque vous appelez equals().
3. Associez l'objet RemoteInput à une action à l'aide de 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. Appliquez l'action à une notification et envoyez-la.

   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);
     

Le système invite l'utilisateur à saisir une réponse lorsqu'il déclenche l'action de notification, comme illustré dans la figure 4.

Récupérer l'entrée utilisateur à partir de la réponse

Pour recevoir l'entrée utilisateur à partir de l'UI de réponse de la notification, appelez RemoteInput.getResultsFromIntent() en lui transmettant le Intent reçu par votre BroadcastReceiver:

Kotlin

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

Java

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

Après avoir traité le texte, mettez à jour la notification en appelant NotificationManagerCompat.notify() avec le même ID et la même balise, le cas échéant. Cela est nécessaire pour masquer l'interface utilisateur de la réponse directe et confirmer à l'utilisateur que sa réponse est reçue et traitée correctement.

Kotlin

// 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)
}

Java

// 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);

Lorsque vous utilisez cette nouvelle notification, utilisez le contexte transmis à la méthode onReceive() du destinataire.

Ajoutez la réponse au bas de la notification en appelant setRemoteInputHistory(). Toutefois, si vous créez une application de chat, créez une notification de style chat et ajoutez le nouveau message à la conversation.

Pour obtenir des conseils sur les notifications d'applications de messagerie, consultez la section sur les bonnes pratiques pour les applications de messagerie.

Ajouter une barre de progression

Les notifications peuvent inclure un indicateur de progression animé qui indique aux utilisateurs l'état d'une opération en cours.

Figure 5. Barre de progression pendant une opération.

Si vous pouvez estimer la part de l'opération terminée à tout moment, utilisez la forme "déterminée" de l'indicateur (comme illustré dans la figure 5) en appelant setProgress(max, progress, false). Le premier paramètre correspond à la valeur "complete", par exemple 100. Le second est le niveau d'avancement. Le dernier indique qu'il s'agit d'une barre de progression déterminée.

Au fur et à mesure de votre opération, appelez continuellement setProgress(max, progress, false) avec une valeur mise à jour pour progress et rééditez la notification, comme illustré dans l'exemple suivant.

Remarque :Étant donné que la barre de progression nécessite que votre application mette à jour la notification en continu, exécutez ce code dans un service en arrière-plan.

Kotlin

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())
}

Java

...
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());

À la fin de l'opération, progress doit être égal à max. Vous pouvez laisser la barre de progression pour indiquer que l'opération est terminée ou la supprimer. Dans les deux cas, mettez à jour le texte de la notification pour indiquer que l'opération est terminée. Pour supprimer la barre de progression, appelez setProgress(0, 0, false).

Pour afficher une barre de progression indéterminée (une barre qui n'indique pas le pourcentage d'avancement), appelez setProgress(0, 0, true). Le résultat est un indicateur qui a le même style que la barre de progression précédente, à l'exception qu'il s'agit d'une animation continue qui n'indique pas la fin. L'animation de progression s'exécute jusqu'à ce que vous appeliez setProgress(0, 0, false), puis mettez à jour la notification pour supprimer l'indicateur d'activité.

N'oubliez pas de modifier le texte de la notification pour indiquer que l'opération est terminée.

Remarque :Si vous devez télécharger un fichier, envisagez d'utiliser DownloadManager, qui fournit sa propre notification pour suivre la progression du téléchargement.

Définir une catégorie au niveau du système

Android utilise des catégories prédéfinies à l'échelle du système pour déterminer s'il faut déranger l'utilisateur en lui présentant une notification spécifique lorsque celui-ci active le mode Ne pas déranger.

Si votre notification fait partie de l'une des catégories de notifications définies dans NotificationCompat (par exemple, CATEGORY_ALARM, CATEGORY_REMINDER, CATEGORY_EVENT ou CATEGORY_CALL), déclarez-la en transmettant la catégorie appropriée à setCategory():

Kotlin

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)

Java

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);

Le système utilise ces informations sur votre catégorie de notification pour décider de l'affichage de votre notification lorsque l'appareil est en mode Ne pas déranger. Toutefois, vous n'êtes pas obligé de définir une catégorie à l'échelle du système. Ne le faites que si vos notifications correspondent à l'une des catégories définies dans NotificationCompat.

Afficher un message urgent

Votre application peut être amenée à afficher un message urgent et urgent, comme un appel téléphonique entrant ou une alarme qui sonne. Dans ces situations, vous pouvez associer un intent plein écran à votre notification.

Attention :Les notifications contenant des intents plein écran sont très intrusives. Il est donc important de n'utiliser ce type de notification que pour les messages les plus urgents et les plus sensibles au temps.

Lorsque la notification est appelée, les utilisateurs voient l'un des éléments suivants, en fonction de l'état de verrouillage de l'appareil:

• Si l'appareil de l'utilisateur est verrouillé, une activité en plein écran s'affiche, recouvrant l'écran de verrouillage.
• Si l'appareil de l'utilisateur est déverrouillé, la notification s'affiche sous une forme agrandie qui inclut des options permettant de la gérer ou de l'ignorer.

Remarque :Si votre application cible Android 10 (niveau d'API 29) ou une version ultérieure, vous devez demander l'autorisation USE_FULL_SCREEN_INTENT dans le fichier manifeste de votre application pour que le système lance l'activité en plein écran associée à la notification urgente.

L'extrait de code suivant montre comment associer votre notification à un intent plein écran:

Kotlin

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)

Java

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);

Définir la visibilité de l'écran de verrouillage

Pour contrôler le niveau de détail visible dans la notification depuis l'écran de verrouillage, appelez setVisibility() et spécifiez l'une des valeurs suivantes:

• VISIBILITY_PUBLIC : le contenu complet de la notification s'affiche sur l'écran de verrouillage.

• VISIBILITY_SECRET : aucune partie de la notification ne s'affiche sur l'écran de verrouillage.

• VISIBILITY_PRIVATE : seules les informations de base, telles que l'icône de la notification et le titre du contenu, s'affichent sur l'écran de verrouillage. Le contenu complet de la notification ne s'affiche pas.

Lorsque vous définissez VISIBILITY_PRIVATE, vous pouvez également fournir une autre version du contenu de la notification qui masque certains détails. Par exemple, une application de SMS peut afficher une notification indiquant "Vous avez trois nouveaux messages", mais masquer le contenu et les expéditeurs des messages. Pour fournir cette notification alternative, créez d'abord la notification alternative avec NotificationCompat.Builder comme d'habitude. Ensuite, joignez la notification de remplacement à la notification normale avec setPublicVersion().

N'oubliez pas que l'utilisateur a toujours le contrôle final sur la visibilité de ses notifications sur l'écran de verrouillage et peut les contrôler en fonction des canaux de notification de votre application.

Mettre à jour une notification

Pour mettre à jour une notification après l'avoir envoyée, appelez à nouveau NotificationManagerCompat.notify() en lui transmettant le même ID que celui que vous avez utilisé précédemment. Si la notification précédente est ignorée, une nouvelle notification est créée à la place.

Vous pouvez appeler setOnlyAlertOnce() si vous souhaitez que votre notification interrompe l'utilisateur (avec un son, une vibration ou des indices visuels) uniquement la première fois qu'elle s'affiche et non pour les mises à jour ultérieures.

Attention :Android applique une limite de débit lors de la mise à jour d'une notification. Si vous publiez trop fréquemment des mises à jour dans une notification (plusieurs en moins d'une seconde), le système peut abandonner certaines mises à jour.

Supprimer une notification

Les notifications restent visibles jusqu'à ce que l'un des événements suivants se produise:

• L'utilisateur ignore la notification.
• L'utilisateur appuie sur la notification si vous appelez setAutoCancel() lorsque vous créez la notification.
• Vous appelez cancel() pour un ID de notification spécifique. Cette méthode supprime également les notifications en cours.
• Vous appelez cancelAll(), ce qui supprime toutes les notifications que vous avez précédemment émises.
• La durée spécifiée expire si vous définissez un délai avant expiration lors de la création de la notification à l'aide de setTimeoutAfter(). Si nécessaire, vous pouvez annuler une notification avant l'expiration du délai avant expiration spécifié.

Bonnes pratiques pour les applications de messagerie

Tenez compte des bonnes pratiques listées ici lorsque vous créez des notifications pour vos applications de chat et de messagerie.

Utiliser MessagingStyle

À partir d'Android 7.0 (niveau d'API 24), Android fournit un modèle de style de notification spécifiquement pour le contenu des messages. À l'aide de la classe NotificationCompat.MessagingStyle, vous pouvez modifier plusieurs des libellés affichés dans la notification, y compris le titre de la conversation, les messages supplémentaires et la vue du contenu de la notification.

L'extrait de code suivant montre comment personnaliser le style d'une notification à l'aide de la classe MessagingStyle.

Kotlin

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()

Java

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();

À partir d'Android 9.0 (niveau d'API 28), vous devez également utiliser la classe Person pour obtenir un rendu optimal de la notification et de ses avatars.

Lorsque vous utilisez NotificationCompat.MessagingStyle, procédez comme suit:

• Appuyez sur MessagingStyle.setConversationTitle() pour ajouter un titre aux chats de groupe avec plus de deux personnes. Un bon titre de conversation peut être le nom du chat de groupe ou, s'il n'a pas de nom, une liste des participants à la conversation. Sans cela, le message pourrait être confondu avec une conversation individuelle avec l'expéditeur du message le plus récent de la conversation.
• Utilisez la méthode MessagingStyle.setData() pour inclure des messages multimédias tels que des images. Les types MIME du modèle image/* sont acceptés.

Utiliser la réponse directe

La réponse directe permet à un utilisateur de répondre directement à un message.

• Une fois qu'un utilisateur a répondu à l'action de réponse intégrée, utilisez MessagingStyle.addMessage() pour mettre à jour la notification MessagingStyle, et ne rétractez ni n'annulez la notification. Si vous ne l'annulez pas, l'utilisateur peut envoyer plusieurs réponses à partir de la notification.
• Pour rendre l'action de réponse intégrée compatible avec Wear OS, appelez Action.WearableExtender.setHintDisplayInlineAction(true).
• Utilisez la méthode addHistoricMessage() pour fournir du contexte à une conversation de réponse directe en ajoutant l'historique des messages à la notification.

Activer les réponses suggérées

• Pour activer la fonctionnalité Réponse suggérée, appelez setAllowGeneratedResponses(true) sur l'action de réponse. Les réponses suggérées sont ainsi disponibles pour les utilisateurs lorsque la notification est associée à un appareil Wear OS. Les réponses suggérées sont générées par un modèle de machine learning entièrement sur la montre à l'aide du contexte fourni par la notification NotificationCompat.MessagingStyle. Aucune donnée n'est importée sur Internet pour générer les réponses.

Ajouter des métadonnées de notification

• Attribuez des métadonnées de notification pour indiquer au système comment gérer les notifications de votre application lorsque l'appareil est en mode Do Not Disturb mode. Par exemple, utilisez la méthode addPerson() ou setCategory(Notification.CATEGORY_MESSAGE) pour remplacer le mode Ne pas déranger.