Partager via

Envoyer une notification locale app à partir d’applications UWP C++

Une app notification est un message que votre app peut construire et livrer à votre utilisateur lorsqu'il n'est pas présent dans votre app.

Capture d’écran d’une app notification

Ce guide de démarrage rapide vous guide tout au long des étapes de création, de remise et d’affichage d’une notification Windows 10 ou Windows 11 app à l’aide de contenu enrichi et d’actions interactives. Ce guide de démarrage rapide utilise les notifications locales, qui sont la notification la plus simple à implémenter. Tous les types d’applications (WPF, UWP, WinForms, console) peuvent envoyer des notifications !

Note

Le terme «toast notification » est remplacé par «app notification ». Ces termes font tous deux référence à la même fonctionnalité de Windows, mais au fil du temps, nous allons abandonner progressivement l'utilisation de «toast notification » dans la documentation.

Important

Si vous écrivez une version C++ non UWP app, consultez la documentation WRL C++ . Si vous écrivez un C# app, consultez la documentation C#.

Étape 1 : Installer le package NuGet

Vous pouvez créer des app notifications avec la syntaxe du générateur de Windows Community Toolkit (WCT) OU avec XML. Si vous préférez la seconde option, passez à étape 2 et reportez-vous aux exemples de code sans syntaxe de générateur .

Dans votre solution Visual Studio, cliquez avec le bouton droit sur votre projet, cliquez sur « Gérer les packages NuGet... » et recherchez et installez le package NuGet Microsoft.Toolkit.Uwp.Notifications version 7.0 ou ultérieure.

Nos exemples de code de syntaxe Builder utilisent ce package. Ce package vous permet de créer app des notifications sans utiliser XML.

Étape 2 : Ajouter des déclarations d’espace de noms

using namespace Microsoft::Toolkit::Uwp::Notifications;

Étape 3 : Envoyer une app notification

Dans Windows 10 et Windows 11, votre app contenu de notification est décrit à l’aide d’un langage adaptatif qui permet une grande flexibilité avec l’apparence de votre notification. Pour plus d’informations, consultez la documentation sur le contenu de App la notification .

Nous allons commencer par une simple notification textuelle. Construisez le contenu de notification (à l’aide de la bibliothèque Notifications) et affichez la notification ! Notez que le namespace est Microsoft.Toolkit.Uwp.Notifications.

notification texte simple

Si vous n’utilisez pas la syntaxe du générateur de bibliothèque de notifications WCT, vous allez plutôt construire le modèle de notification XML app , le remplir avec du texte et des valeurs, construire la notification et l’afficher.

// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)
    ->AddText("Andrew sent you a picture")
    ->AddText("Check this out, The Enchantments in Washington!")
    ->Show();

Étape 4 : Gérer l’activation

Lorsque l’utilisateur clique sur votre notification (ou un bouton sur la notification avec activation au premier plan), votre app.xaml.cppAppOnActivated est appelé.

App.xaml.cpp

void App::OnActivated(IActivatedEventArgs^ e)
{
    // Handle notification activation
    if (e->Kind == ActivationKind::ToastNotification)
    {
        ToastNotificationActivatedEventArgs^ toastActivationArgs = (ToastNotificationActivatedEventArgs^)e;

        // Obtain the arguments from the notification
        ToastArguments^ args = ToastArguments::Parse(toastActivationArgs->Argument);

        // Obtain any user input (text boxes, menu selections) from the notification
        auto userInput = toastActivationArgs->UserInput;

        // TODO: Show the corresponding content
    }
}

Important

Vous devez initialiser votre cadre et activer votre fenêtre comme votre code OnLaunched. OnLaunched n’est pas appelé si l’utilisateur clique sur votre app notification, même si votre app était fermé et se lance pour la première fois. Nous vous recommandons souvent de combiner OnLaunched et OnActivated dans votre propre méthode OnLaunchedOrActivated, car le même processus d'initialisation doit être effectué dans les deux.

Activation en profondeur

La première étape de la création de vos notifications exploitables consiste à ajouter des arguments de lancement à votre notification, afin que vous app puissiez savoir ce qu’il faut lancer lorsque l’utilisateur clique sur la notification (dans ce cas, nous incluons quelques informations qui nous indiquent ultérieurement que nous devrions ouvrir une conversation, et nous savons quelle conversation spécifique ouvrir).

// Construct the content and show the toast!
(ref new ToastContentBuilder())

    // Arguments returned when user taps body of notification
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)

    ->AddText("Andrew sent you a picture")
    ->Show();

Ajouter des images

Vous pouvez ajouter du contenu enrichi aux notifications. Nous allons ajouter une image intégrée et une image de profil (app substitution de logo).

Note

Les images peuvent être utilisées depuis le package du app, du stockage local du app, ou depuis le web. À compter de Fall Creators Update, les images web peuvent être jusqu’à 3 Mo sur les connexions normales et 1 Mo sur les connexions limitées. Sur les appareils qui n’exécutent pas encore Fall Creators Update, les images web ne doivent pas dépasser 200 Ko.

Toast avec des images 
// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ...

    // Inline image
    ->AddInlineImage(ref new Uri("https://picsum.photos/360/202?image=883"))

    // Profile (app logo override) image
    ->AddAppLogoOverride(ref new Uri("ms-appdata:///local/Andrew.jpg"), ToastGenericAppLogoCrop::Circle)

    ->Show();

Ajouter des boutons et des entrées

Vous pouvez ajouter des boutons et des entrées pour rendre vos notifications interactives. Les boutons peuvent lancer votre premier plan app, un protocole ou votre tâche en arrière-plan. Nous allons ajouter une zone de texte de réponse, un bouton « Like » et un bouton « Afficher » qui ouvre l’image.

Capture d’écran d’une toast notification avec des entrées et des boutons 
// Construct the content
(ref new ToastContentBuilder())
    ->AddArgument("conversationId", 9813)
    ...

    // Text box for replying
    ->AddInputTextBox("tbReply", "Type a response")

    // Buttons
    ->AddButton((ref new ToastButton())
        ->SetContent("Reply")
        ->AddArgument("action", "reply")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("Like")
        ->AddArgument("action", "like")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("View")
        ->AddArgument("action", "view"))

    ->Show();

L’activation des boutons de premier plan est gérée de la même façon que le corps de notification principal (votre App.xaml.cpp OnActivated sera appelé).

Gérer l’activation en arrière-plan

Lorsque vous spécifiez l’activation en arrière-plan sur votre app notification (ou sur un bouton à l’intérieur de la notification), votre tâche en arrière-plan est exécutée au lieu d’activer votre premier plan app.

Pour plus d’informations sur les tâches en arrière-plan, consultez Prendre en charge vos app tâches en arrière-plan.

Si vous ciblez la build 14393 ou une version ultérieure, vous pouvez utiliser des tâches en arrière-plan in-process, ce qui simplifie considérablement les choses. Notez que les tâches en arrière-plan en cours ne s’exécutent pas sur les versions antérieures de Windows. Nous allons utiliser une tâche d'arrière-plan en cours dans cet exemple de code.

const string taskName = "ToastBackgroundTask";

// If background task is already registered, do nothing
if (BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals(taskName)))
    return;

// Otherwise request access
BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();

// Create the background task
BackgroundTaskBuilder builder = new BackgroundTaskBuilder()
{
    Name = taskName
};

// Assign the toast action trigger
builder.SetTrigger(new ToastNotificationActionTrigger());

// And register the task
BackgroundTaskRegistration registration = builder.Register();

Ensuite, dans votre App.xaml.cs, remplacez la méthode OnBackgroundActivated. Vous pouvez ensuite récupérer les arguments prédéfinis et les entrées utilisateur, similaires à l’activation au premier plan.

App.xaml.cs

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();

    switch (args.TaskInstance.Task.Name)
    {
        case "ToastBackgroundTask":
            var details = args.TaskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
            if (details != null)
            {
                string arguments = details.Argument;
                var userInput = details.UserInput;

                // Perform tasks
            }
            break;
    }

    deferral.Complete();
}

Définir un délai d’expiration

Dans Windows 10 et 11, toutes les app notifications sont envoyées dans le Centre de notifications une fois qu’elles sont ignorées ou rejetées par l’utilisateur, afin que les utilisateurs puissent consulter votre notification une fois le popup supprimé.

Toutefois, si le message de votre notification ne concerne que pendant une période donnée, vous devez définir une heure d’expiration sur la app notification afin que les utilisateurs ne voient pas les informations obsolètes de votre app. Par exemple, si une promotion est valide uniquement pendant 12 heures, définissez l’heure d’expiration sur 12 heures. Dans le code ci-dessous, nous définissons la durée d’expiration sur 2 jours.

Note

La durée d’expiration par défaut et maximale des notifications locales app est de 3 jours.

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("Expires in 2 days...")
    ->Show(toast =>
    {
        toast->ExpirationTime = DateTime::Now->AddDays(2);
    });

Fournir une clé primaire pour votre app notification

Si vous souhaitez supprimer ou remplacer par programmation la notification que vous envoyez, vous devez utiliser la propriété Tag (et éventuellement la propriété Group) pour fournir une clé primaire pour votre notification. Ensuite, vous pouvez utiliser cette clé primaire à l’avenir pour supprimer ou remplacer la notification.

Pour plus d’informations sur le remplacement/la suppression des notifications déjà remisesapp, consultez démarrage rapide : Gestion des toast notifications dans le centre de notifications (XAML)

L’étiquette et le groupe combinés agissent comme une clé primaire composite. Le groupe est l’identificateur plus générique, où vous pouvez affecter des groupes tels que « wallPosts », « messages », « friendRequests », etc. Ensuite, l’étiquette doit identifier de manière unique la notification elle-même à partir du groupe. En utilisant un groupe générique, vous pouvez ensuite supprimer toutes les notifications de ce groupe à l’aide de l’API RemoveGroup .

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("New post on your wall!")
    ->Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

Effacer vos notifications

Les applications sont responsables de la suppression et de l’effacement de leurs propres notifications. Lorsque votre app est lancé, nous n'effaçons pas automatiquement vos notifications.

Windows supprime automatiquement une notification si l’utilisateur clique explicitement sur la notification.

Voici un exemple de ce qu’une messagerie app doit faire...

  1. L’utilisateur reçoit plusieurs notifications sur les app nouveaux messages d’une conversation
  2. L’utilisateur appuie sur l’une de ces notifications pour ouvrir la conversation
  3. app ouvre la conversation, puis efface toutes les notifications pour cette conversation (en utilisant RemoveGroup sur le groupe fourni par app pour cette conversation)
  4. Le Centre de notifications de l’utilisateur reflète désormais correctement l’état de notification, car il n’existe aucune notification obsolète pour cette conversation laissée dans le Centre de notifications.

Pour en savoir plus sur l’effacement de toutes les notifications ou la suppression de notifications spécifiques, consultez Démarrage rapide : Gestion des toast notifications dans le centre de notifications (XAML).

ToastNotificationManagerCompat::History->Clear();

Resources

  • Last updated on