Utilisation de notifications

Remonter à Utilisation de la RTL dans les applications multi-périphériques

Les notifications sont des messages que les applications envoient pour communiquer des informations ou des alertes.

Remarque: Cette rubrique traite des notifications locales qui sont des notifications envoyées par les applications du périphérique. Pour les notifications distantes, voir Notifications push.

RAD Studio fournit le composant TNotificationCenter pour gérer les notifications multi-périphériques. Le Centre de notifications vous permet d'envoyer des messages depuis les applications en cours d'exécution. Les applications peuvent utiliser les notifications pour informer l'utilisateur.

Le composant TNotification est le message que l'application envoie au Centre de notifications pour l'afficher sur la zone de notification désignée, selon la plate-forme.

Vous pouvez créer des notifications pour Windows en utilisant la VCL, ou pour vos applications multi-périphériques en utilisant FireMonkey.

Prise en charge des notifications selon la plate-forme

Elément	Windows	macOS	iOS	Android
Plates-formes prises en charge	Windows 10 et Windows 8	10.8+
Nom de la zone de notification	Centre de notifications ou Action Center (EN)	Centre de notifications ou Notification Center (EN)	Centre de notifications ou Notification Center (EN)	Tiroir de notifications ou Notification Drawer (EN)
TNotification
TNotification.Name
TNotification.AlertBody			Obligatoire
TNotification.Title		En absence de titre, le nom de l'app est utilisé comme titre.	Non pris en charge. Nom d'app utilisé comme titre.	En absence de titre, le nom de l'app est utilisé comme titre.
TNotification.FireDate	Non pris en charge.
TNotification.Number	Non pris en charge.	Non pris en charge.	Définit le numéro de badge.
TNotification.EnableSound
TNotification.AlertAction	Non pris en charge.			Non pris en charge.
TNotification.HasAction	Non pris en charge.			Non pris en charge.
TNotification.RepeatInterval	Non pris en charge.
TCustomNotificationCenter
TCustomNotificationCenter.ApplicationIconBadgeNumber	Non pris en charge.	Non pris en charge. Voir l'exemple OS X Badge.		Non pris en charge.
TCustomNotificationCenter.ScheduleNotification	Non pris en charge.
TCustomNotificationCenter.PresentNotification

Notifications Windows

Les notifications toast sont compatibles avec les versions suivantes de Windows :

• Windows 8 : Windows 8 affiche les notifications pendant un bref laps de temps. Elles ne sont ensuite plus accessibles à l'utilisateur.
• Windows 10 : Windows 10 affiche les notifications pendant un bref laps de temps. Elles sont ensuite accessibles depuis le Centre de notifications.

Pour accéder au Centre de notifications, cliquez sur l'icône Centre de notifications sur la barre des tâches. L'icône change selon que des notifications sont en attente ou non :

Notifications en attente	Aucune notification en attente

Notifications macOS

Depuis la version 10.8, macOS prend en charge les notifications. Pour de plus amples informations sur macOS, voir Utilisation du Centre de notifications macOS.

Notifications iOS

Permissions d'utilisation

Pour utiliser des notifications sur iOS, ajoutez des permissions de notifications à votre application :

1. Sélectionnez Projet > Options > Informations de version.
2. Sélectionnez la plate-forme cible iOS appropriée.
3. Dans la zone de liste clé-valeur, définissez la valeur de FMLocalNotificationPermission sur True.

Alerte de notification

iOS permet à l'utilisateur de définir si les notifications d'une app sont affichées sous forme de bannière ou d'alerte. Les bannières sont affichées à l'écran pendant une courte durée, alors que les alertes restent affichées à l'écran jusqu'à ce que l'utilisateur interagisse.

Pour afficher les notifications sous forme d'alertes, l'utilisateur final doit accéder aux paramètres de notifications de l'application sur le périphérique iOS, et définir le paramètre Style d'alerte si déverrouillé sur Alertes.

Création de notifications

La classe TNotification est utilisée pour créer des messages de notification. Vous devez utiliser le composant TNotificationCenter pour gérer une ou plusieurs instances de TNotification.

Une fois le composant TNotificationCenter installé sur votre fiche, vous pouvez déclarer une variable TNotification et appeler la méthode CreateNotification pour créer la notification.

Delphi :

MyNotification:= NotificationCenter1.CreateNotification;

C++ :

TNotification *MyNotification = NotificationCenter1->CreateNotification();

Une fois la notification créée, nous vous recommandons de définir au moins les champs suivants :

• Name : le nom unique permettant d'identifier la notification.
• AlertBody : le texte de la notification. Sous iOS, il est obligatoire de spécifier AlertBody.

Les paramètres suivants peuvent être également spécifiés pour vos notifications :

• Title : le titre de la notification. iOS n'est pas compatible avec le champ Title et affiche toujours le nom de l'app comme titre.

• Number : utilisez ce champ pour mettre à jour le numéro de notification sous Android ou le numéro de badge d'application sous iOS.

• ApplicationIconBadgeNumber : utilisez cette propriété pour mettre à jour le numéro de badge de l'application sous iOS.

Numéro de badge iOS	Numéro de notification Android

Déclenchement des notifications

FireDate est utilisé pour définir la date et l'heure de déclenchement de la notification.

Concernant l'heure de déclenchement de la notification, il est possible de créer deux types de notifications.

• Les notifications immédiates
• Les notifications planifiées

Notifications immédiates

Par défaut, FireDate est défini sur Now. Ainsi, si vous ne changez pas la valeur de FireDate, la notification est déclenchée immédiatement.

Notifications planifiées

Les notifications peuvent être planifiées de façon à se déclencher à tout moment. Définissez FireDate sur la date et l'heure auxquelles vous voulez déclencher la notification.

Déclenchement de notifications à une date et une heure particulières

Vous pouvez définir qu'une notification sera déclenchée à une date et une heure précises. Par exemple, pour spécifier qu'une notification sera déclenchée le 16 décembre 2015 à 17:30, vous devez définir FireDate comme suit :

Delphi :

MyNotification.FireDate := EncodeDateTime(2015, 12, 16, 17, 30, 00, 00);

C++ :

MyNotification->FireDate = System::Dateutils::EncodeDateTime(2015, 12, 16, 17, 30, 00, 00);

Lorsque vous planifiez des notifications pour une date et une heure spécifiques, vous devez garder à l'esprit que si la date et l'heure de FireDate sont passées, la notification est déclenchée immédiatement.

Déclenchement de notifications après un laps de temps

Vous pouvez définir qu'une notification sera déclenchée après un laps de temps. Par exemple, pour déclencher la notification dans une minute et trente secondes, vous pouvez procéder comme suit :

Delphi :

MyNotification.FireDate := Now + EncodeTime(0, 1, 30, 0);

C++ :

MyNotification->FireDate = Now() + EncodeTime(0, 1, 30, 0);

Si une notification est planifiée et que vous avez créé une notification portant le même nom (qu'elle soit planifiée ou non), toute notification précédente ayant été planifiée sous ce nom est écrasée.

Répétition des notifications

Vous pouvez utiliser RepeatInterval pour planifier des notifications afin qu'elles se répètent après une certaine période de temps. Vous pouvez utiliser l'un des types d'intervalles définis par TRepeatInterval : None, Second, Minute, Hour, Day, Week, Weekday, Month, Quarter, Year ou Era.

Avertissement: Lorsque vous planifiez une notification de façon à ce qu'elle se répète après une certaine période de temps (RepeatInterval), la notification continue de se répéter jusqu'à la fermeture de l'application. Assurez-vous de bien utiliser l'annulation des notifications.

Par exemple, pour définir une notification de façon à ce qu'elle se répète chaque heure, vous pouvez procéder comme suit :

Delphi :

MyNotification.RepeatInterval := TRepeatInterval.Hour;

C++ :

MyNotification->RepeatInterval = TRepeatInterval::Hour;

Son des notifications

Activation du son des notifications

Vous pouvez activer ou désactiver le son des notifications en utilisant EnableSound. Par défaut, EnableSound est définie sur True.

• Sur macOS et iOS, le son de la notification n'est pas exécuté même en cas d'activation du son si l'application est au premier plan. macOS et iOS exécutent le son de la notification lorsque l'application est fermée ou à l'arrière-plan.
• Sur Windows, lorsque EnableSound est défini sur True, le son de la notification est exécuté. Vous pouvez désactiver le son en définissant cette propriété sur False.

Personnalisation des sons de notifications

Vous pouvez personnaliser le son de vos notifications en définissant SoundName sur le son de votre notification.

Pour ajouter un son de notification personnalisé, procédez comme suit :

1. Effectuez un glisser-déposer du fichier son sur le nom de votre projet dans la fenêtre Projets et confirmez l'ajout du fichier.
2. Accédez à Projet > Déploiement et définissez correctement les chemins distants du fichier pour les différentes plates-formes.
   • iOS : .\
3. Indiquez le nom du fichier personnalisé, définissez SoundName selon la plate-forme.

Delphi :

{$IFDEF IOS}
MyNotification.SoundName := 'nameOfSound.caf';
{$ENDIF}

C++ :

#if defined(_PLAT_IOS)
myNotification->SoundName = "nameOfSound.caf";
#endif

Remarque: Selon la documentation iOS, le fichier son doit avoir l'extension de fichier aiff, wav ou caf.

Assurez-vous d'ajouter l'unité appropriée à votre projet :

Delphi : Ajoutez System.IOUtils dans la clause uses.

System.IOUtils;

C++ : Ajoutez System.IOUtils.hpp dans le fichier d'en-tête .h de votre projet.

#include <System.IOUtils.hpp>

Si le périphérique n'est pas capable de trouver le fichier son personnalisé que vous avez défini dans votre projet, iOS exécute le son par défaut. Android quant à lui n'exécute aucun son.

Actions des notifications

Cliquer sur les notifications sous macOS, iOS ou Android provoque l'affichage au premier plan de l'application ayant envoyé la notification, même si cette application est fermée ou exécutée en arrière-plan.

Aucun comportement particulier n'est attendu lorsque l'utilisateur clique sur la notification sous Windows.

Ajout des actions des notifications

Lorsque l'utilisateur clique sur une notification, des actions peuvent être exécutées. L'événement OnReceiveLocalNotification est déclenché lorsque l'utilisateur clique sur une notification. Ecrivez un gestionnaire d'événement pour définir une action.

Le gestionnaire d'événement de OnReceiveLocalNotification reçoit le TNotitication sur lequel l'utilisateur a cliqué dans le paramètre ANotification. Utilisez le paramètre ANotification pour obtenir des informations supplémentaires sur la notification sur laquelle l'utilisateur a cliqué.

Pour afficher un message selon la notification sur laquelle l'utilisateur a cliqué :

Delphi :

if ANotification.Name='ProcessCompleted' then
	ShowMessage('The process is completed.');

C++ :

if (ANotification->Name == "ProcessCompleted") {
	ShowMessage("The process is completed.");
}

Actions des notifications (macOS et iOS)

Vous pouvez ajouter un bouton d'action à une alerte afin que l'utilisateur puisse ouvrir l'application en cliquant sur le bouton. Pour obtenir le fonctionnement espéré, l'utilisateur doit définir le style des notifications du projet sur "Alertes". Pour de plus amples informations, découvrez comment définir les alertes de notifications sous macOS et Alertes de notifications sous iOS.

Pour ajouter un bouton d'action, définissez le champ HasAction sur True. Utilisez le champ AlertAction pour indiquer le texte du bouton.

Delphi :

MyNotification.HasAction := True;
MyNotification.AlertAction := 'Open App';

C++ :

MyNotification->HasAction = True;
MyNotification->AlertAction = "Open App";

Envoi de notifications au Centre de notifications

Lorsque vous avez terminé de configurer les paramètres de votre notification, vous devez l'envoyer au Centre de notifications afin qu'il puisse la traiter.

Pour envoyer des notifications au Centre de notifications, vous pouvez utiliser l'une des méthodes suivantes :

• ScheduleNotification
• PresentNotification

ScheduleNotification

ScheduleNotification envoie une notification planifiée au Centre de notifications. Si FireDate est défini sur Now ou si FireDate a un TDateTime passé, la notification apparaît immédiatement. Elle est sinon planifiée comme indiqué.

Delphi :

NotificationCenter1.ScheduleNotification(MyNotification);

C++ :

NotificationCenter1->ScheduleNotification(MyNotification);

PresentNotification

PresentNotification présente immédiatement la notification quelle que soit la valeur de FireDate.

Delphi :

NotificationCenter1.PresentNotification(MyNotification);

C++ :

NotificationCenter1->PresentNotification(MyNotification);

Annulation des notifications

Vous pouvez annuler des notifications planifiées, des notifications répétées et vous pouvez également retirer des notifications déjà affichées dans le Centre de notifications ou le Tiroir de notifications.

CancelNotification

CancelNotification est utilisée pour annuler une notification planifiée ou une notification répétée. Pour annuler la notification, vous devez connaître son nom.

Delphi :

NotificationCenter1.CancelNotification('MyNotificationName');

C++ :

NotificationCenter1->CancelNotification("MyNotificationName");

CancelAll

CancelAll annule l'ensemble des notifications :

• Les notifications planifiées ne seront pas déclenchées.
• Les notifications ayant des intervalles de répétition sont annulées.
• Les notifications disponibles dans le Centre de notifications ou le Tiroir de notifications de cette application sont supprimées.

Delphi :

NotificationCenter1.CancelAll;

C++ :

NotificationCenter1->CancelAll();

Mise à jour des notifications

Vous pouvez mettre à jour les notifications en attente de déclenchement en utilisant leur nom (Name), qui est l'identificateur unique de la notification. Pour mettre à jour une notification, suivez ces étapes :

1. Créez une instance de TNotification ayant le même nom que celle que vous souhaitez mettre à jour.
2. Configurez la nouvelle instance avec les paramètres voulus.
3. Envoyez la notification au Centre de notifications.

La mise à jour des notifications futures, qu'elles soient planifiées ou qu'elles soient répétitives, supprime les notifications déjà présentes dans le Centre de notifications ou le Tiroir de notifications et écrase les futures notifications.

Voir aussi

• Utilisation du Centre de notifications macOS
• Tutoriel mobile : Utilisation des notifications (iOS et Android)
• Notifications push
• System.Notification.TNotification
• System.Notification.TNotificationCenter

Exemples de code

• Exemple FireMonkey Send Cancel Notification
• Exemple FireMonkey Android Notification Service
• Exemple FireMonkey Set Reset Badge Number
• OSX Dock Badges (Delphi)
• FireMonkey Notification Mac (Delphi)
• FireMonkey Notification Mac (C++)