Comment gérer l’activation à partir d’une notification toast (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Remarque Vous n’utilisez pas JavaScript ? Voir Comment gérer l’activation à partir d’une notification toast (XAML).

Cette rubrique décrit les actions que vous devez entreprendre en réponse au clic d’un utilisateur sur une notification toast envoyée à partir de votre application. Votre application doit répondre en affichant une interface utilisateur spécifique à la notification toast. L’application doit généralement démarrer dans un contexte ou une vue associés au contenu de la notification toast. Vous parvenez à cela par le biais d’une chaîne d’activation que vous incluez dans la charge utile de la notification toast, qui est ensuite transmise à votre application sous la forme d’un argument dans l’événement d’activation. Le flux de données de base est le suivant :

L’application ou le service web crée et envoie la charge utile de la notification toast, y compris la chaîne de lancement
La notification toast est déclenchée et/ou envoyée au Centre de maintenance
L’utilisateur sélectionne la notification toast (par clic ou appui)
L’événement activé se déclenche
Le gestionnaire d’événements activé de l’application lit la chaîne de lancement
L’application est lancée à l’aide des paramètres fournis dans la chaîne de lancement

Remarque Lors des tests de la fonctionnalité de code de notification toast à l’aide de Microsoft Visual Studio, vous devez utiliser le paramètre de débogage Ordinateur local ou Ordinateur distant sur un ordinateur Windows x86, x64 ou Windows Runtime. Vous ne pouvez pas utiliser l’option de fonction de débogage Simulateur Visual Studio (votre code serait compilé et exécuté dans le Simulateur, mais le toast n’apparaîtrait pas).

Ce que vous devez savoir

Technologies

Windows Runtime

Prérequis

Conditions préalables à la compréhension de cette rubrique :

Bonnes connaissances des termes et des concepts liés aux notifications toast. Pour plus d’informations, voir Vue d’ensemble des notifications toast.
L’option Compatible toast doit avoir la valeur « true » dans le manifeste de votre application (« Oui » dans l’éditeur de manifeste de Visual Studio) pour permettre l’envoi ou la réception de notifications toast. Pour plus d’informations, voir Démarrage rapide : création d’une vignette par défaut à l’aide de l’éditeur de manifeste de Visual Studio et Comment s’abonner aux notifications toast.
Bonne connaissance du langage XML et de sa manipulation via les API DOM (Document Object Model).
Bonne connaissance du schéma XML des notifications toast. Pour plus d’informations, voir Schéma des notifications toast.
Aptitude à créer une application élémentaire Windows Store en JavaScript à l’aide des API Windows Runtime. Pour plus d’informations, voir Créer votre première application du Windows Store en JavaScript.

Instructions

Étape 1: Inclure des données d’activation dans votre charge utile de notification toast

Lorsque votre application est activée par le biais d’une notification toast, elle doit obtenir des informations associées au contenu de la notification toast. Elle peut alors refléter ce contenu en démarrant dans une vue associée à la place de sa vue par défaut. Lorsque votre application ou service Web crée la notification toast, elle utilise l’attribut launch pour spécifier ces informations d’activation. Vous pouvez considérer la chaîne comme analogue aux arguments de ligne de commande. La chaîne peut contenir toutes les informations susceptibles d’être comprises par l’application, si elles n’ont pas pour conséquence de rendre non valide la charge utile XML. Notez que la taille totale de la charge utile XML de la notification toast, y compris la chaîne de lancement, ne peut pas dépasser 5 Ko.

Si vous n’incluez pas une chaîne d’attribut de lancement, votre application sera lancée normalement, comme si l’utilisateur l’avait lancée à partir de l’écran d’accueil.

Dans cette étape, nous supposons l’existence d’un objet XmlDocument créé auparavant, nommé toastXml. Cet exemple crée l’attribut launch, attribue sa valeur de chaîne, puis l’ajoute à la charge utile XML de la notification toast. Pour obtenir des instructions sur la création de la notification toast complète, voir Démarrage rapide : envoi d’une notification toast.


var launchAttribute = toastXml.createAttribute("launch");
launchAttribute.value = "{\"myContext\":\"12345\"}";
var toastNode = toastXml.selectSingleNode("/toast");
toastNode.attributes.setNamedItem(launchAttribute);

Le code ci-dessus génère le code XML suivant, en fonction du contenu de l’élément visual, qui est défini dans Démarrage rapide : envoi d’une notification toast.


<toast launch="{&quot;myContext&quot;:&quot;12345&quot;}">
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png" alt="red graphic"/>
            <text id="1">Hello World!</text>
        </binding>
    </visual>
</toast>

Étape 2: Enregistrer l’événement activé

Lorsque l’utilisateur clique sur votre notification toast ou la sélectionne en appuyant dessus, l’événement activated est déclenché. Votre application doit s’inscrire via la fonction addEventListener pour être informée de l’événement.

Remarque Si vous n’incluez pas une chaîne d’attribut de lancement dans votre notification toast et que votre application est déjà en cours d’exécution lorsque la notification toast est sélectionnée, l’événement activated n’est pas déclenché.

WinJS.Application.addEventListener("activated", onActivatedHandler, false);

Étape 3: Implémenter un gestionnaire pour l’événement « activé » de votre notification toast

Votre gestionnaire d’événements inscrit reçoit tous les événements d’activation, quel que soit le type d’activation. La propriété kind, incluse dans la notification d’événement, indique le type d’événement d’activation. Lorsque l’utilisateur clique sur une notification toast qui possède un attribut launch spécifié dans sa charge utile XML, un événement d’activation de type launch est déclenché. Il s’agit du même événement qui est déclenché lorsqu’un utilisateur appuie sur la vignette principale ou secondaire d’une application.

La chaîne d’activation que vous avez fournie via l’attribut launch à l’étape 1 est incluse dans la propriété arguments de la notification d’événement.

Cet exemple dresse l’esquisse du gestionnaire d’événements activé inscrit à l’étape 2.


function onActivatedHandler(args) {
    if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
        var launchString = args.detail.arguments;

        // Handle activation as required for your app, using the launch string.
    }
}