Développer une application pour gérer l’événement MobileOperatorNotification
Cette rubrique explique comment développer une application haut débit mobile qui gère l’événement MobileOperatorNotification .
Meilleures pratiques
Pour la gestion des événements en arrière-plan, vous devez utiliser les meilleures pratiques suivantes :
Ne vous inscrivez pas aux événements en arrière-plan sur lesquels vous ne pouvez pas agir. Le traitement de ces événements consomme inutilement le quota d’application.
N’effectuez pas de grandes quantités de traitement à la réception d’un événement en arrière-plan.
Envisagez de reporter le traitement au prochain lancement de l’application.
Envisagez d’afficher une notification toast et une vignette de mise à jour en réponse à un événement en arrière-plan. Votre application haut débit mobile peut traiter la charge utile de l’événement en arrière-plan.
Étape 1 : Déclaration de contrat de tâche en arrière-plan
Pour que Windows reconnaisse les expériences de tâche en arrière-plan fournies par une application haut débit mobile, l’application doit déclarer qu’elle fournit une extension aux fonctionnalités système.
Pour effectuer la déclaration dans le fichier package.appxmanifest de votre projet Visual Studio, procédez comme suit :
Pour déclarer un contrat de tâche en arrière-plan
Dans Explorateur de solutions, double-cliquez sur le fichier package.appxmanifest pour votre projet.
Sous l’onglet Déclarations , dans Déclarations disponibles, sélectionnez Tâches en arrière-plan , puis cliquez sur Ajouter.
Sous le titre Propriétés , entrez les informations d’application suivantes :
Dans la zone Page de démarrage sous Paramètres de l’application, pour une application haut débit mobile qui utilise JavaScript et HTML, entrez le nom de fichier qui gère la tâche en arrière-plan dans l’application (par exemple, backgroundtask.js).
Sous l’en-tête Types de tâches pris en charge, cliquez sur la zone case activée événement système.
Si cette opération est effectuée correctement, vous devez disposer d’un élément d’extension similaire à ce qui suit dans le fichier package.appxmanifest.
<Extension Category="windows.backgroundTasks" StartPage="backgroundtask.js">
<BackgroundTasks>
<Task Type="systemEvent" />
</BackgroundTasks>
</Extension>
Étape 2 : Gestionnaire de tâches en arrière-plan
Si votre application fournit une déclaration de notifications d’opérateur mobile, elle doit fournir un gestionnaire pour l’activation de la tâche en arrière-plan. Le gestionnaire obtient l’ID de compte réseau de l’opérateur mobile et les données d’événement à partir de Windows.Networking.NetworkOperators.NetworkOperatorNotificationEventDetails.
Étant donné que la seule interface utilisateur prise en charge par la tâche en arrière-plan est Toast, le gestionnaire de tâches en arrière-plan peut afficher Toast ou enregistrer NetworkOperatorNotificationEventDetails dans le stockage local.
Les exemples de code suivants illustrent une tâche en arrière-plan conçue pour s’exécuter lorsqu’une nouvelle notification SMS administrative est reçue.
C#
using Windows.Networking.NetworkOperators;
namespace MNOMessageBackground
{
public sealed class MNOBackgroundTask : IBackgroundTask
{
public void Run(Windows.ApplicationModel.Background.IBackgroundTaskInstance taskInstance)
{
NetworkOperatorNotificationEventDetails notifyData = (NetworkOperatorNotificationEventDetails)taskInstance.TriggerDetails;
//The network account ID is stored in notifyData.NetworkAccountId
switch (notifyData.NotificationType)
{
case NetworkOperatorEventMessageType.Gsm: // 0
break;
case NetworkOperatorEventMessageType.Cdma: // 1
break;
case NetworkOperatorEventMessageType.Ussd: // 2
break;
case NetworkOperatorEventMessageType.DataPlanThresholdReached: // 3
break;
case NetworkOperatorEventMessageType.DataPlanReset: //4
break;
case NetworkOperatorEventMessageType.DataPlanDeleted: //5
break;
case NetworkOperatorEventMessageType.ProfileConnected: //6
break;
case NetworkOperatorEventMessageType.ProfileDisconnected: //7
break;
case NetworkOperatorEventMessageType.RegisteredRoaming: //8
break;
case NetworkOperatorEventMessageType.RegisteredHome: ///9
break;
case NetworkOperatorEventMessageType.TetheringEntitlementCheck: //10
break;
default:
break;
}
// Add code to save the message to app local storage, and optionally show toast notification and tile updates.
}
}
}
JavaScript
(function () {
"use strict";
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
networkOperatorEventType = Windows.Networking.NetworkOperators.NetworkOperatorEventMessageType,
key = null,
settings = Windows.Storage.ApplicationData.current.localSettings;
try {
var details = backgroundTaskInstance.triggerDetails;
// The network account ID is stored in details.networkAccountId.
switch (details.notificationType) {
case networkOperatorEventType.gsm:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.cdma:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.ussd:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.dataPlanThresholdReached:
showToast("Mobile Broadband message", "Data plan threshold reached");
break;
case networkOperatorEventType.dataPlanReset:
showToast("Mobile Broadband message", "Data plan reset");
break;
case networkOperatorEventType.dataPlanDeleted:
showToast("Mobile Broadband message", "Data plan deleted");
break;
case networkOperatorEventType.profileConnected:
showToast("Mobile Broadband message", "Profile connected");
break;
case networkOperatorEventType.profileDisconnected:
showToast("Mobile Broadband message", "Profile disconnected");
break;
case networkOperatorEventType.registeredRoaming:
showToast("Mobile Broadband message", "Registered roaming");
break;
case networkOperatorEventType.registeredHome:
showToast("Mobile Broadband message", "Registered home");
break;
case networkOperatorEventType.tetheringEntitlementCheck:
showToast("Mobile Broadband message", "Entitlement check completed");
break;
default:
showToast("Mobile Broadband message", "Unknown message");
break;
}
//
// A JavaScript background task must call close when it is done.
//
close();
}
catch (exception) {
// Display error message.
close();
}
Afficher les notifications de vignette et de toast
Nous vous recommandons d’afficher les notifications toast et par vignette dans votre application haut débit mobile, car un utilisateur peut manquer une notification toast en raison de sa nature temporaire. Pour plus d’informations sur la notification toast et les instructions de conception de l’expérience de mise à jour des vignettes, consultez Conception de l’expérience utilisateur d’une application haut débit mobile.
Pour activer les notifications toast
Dans Explorateur de solutions, double-cliquez sur le fichier package.appxmanifest pour votre projet.
Sous l’onglet Interface utilisateur de l’application , sous le titre Notifications , définissez Toast capable sur Oui.
Si cette opération est effectuée correctement, vous devez disposer d’un élément d’extension similaire à ce qui suit dans le fichier package.appxmanifest.
<VisualElements … ToastCapable="true"… />
Le code suivant montre comment afficher une notification toast dans un handle de tâche en arrière-plan :
JavaScript
function showToast(title, body) {
var notifications = Windows.UI.Notifications;
var toastNotificationManager = Windows.UI.Notifications.ToastNotificationManager;
var toastXml = toastNotificationManager.getTemplateContent(notifications.ToastTemplateType.toastText02);
var temp = "the parameter will pass to app when app activated from tap Toast ";
toastXml.selectSingleNode("/toast").setAttribute("launch", temp);
var textNodes = toastXml.getElementsByTagName("text");
textNodes[0].appendChild(toastXml.createTextNode(title));
textNodes[1].appendChild(toastXml.createTextNode(body));
var toast = new notifications.ToastNotification(toastXml);
toastNotificationManager.createToastNotifier().show(toast);
}
Obtenir un SMS
Si la tâche en arrière-plan a été déclenchée par un message SMS entrant, les détails de la tâche en arrière-plan portent l’objet SMS dans sa charge utile.
JavaScript
(function () {
"use strict";
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
try {
var details = backgroundTaskInstance.triggerDetails;
if (details.notificationType === networkOperatorEventType.gsm
|| details.notificationType === networkOperatorEventType.cdma)
{
var textMessage = new Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(details.smsMessage);
// textMessage can be used to get other SmsMessage properties
// like sender number, timestamp, message part count etc.
showToast("From: " + textMessage.from + "; TimeStamp: " + textMessage.timestamp, details.message);
}
Utiliser le stockage local
La tâche en arrière-plan peut utiliser le stockage local pour enregistrer le message que vous obtenez à partir de l’événement d’arrière-plan, afin que l’application puisse utiliser ces informations ultérieurement.
JavaScript
//
// Save the message
//
var settings = Windows.Storage.ApplicationData.current.localSettings;
var keyMessage = "BA5857FA-DE2C-4A4A-BEF2-49D8B4130A39";
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;
var details = backgroundTaskInstance.triggerDetails;
settings.values[keyMessage] = details.message;
Le code suivant montre comment récupérer le message stocké par le gestionnaire de tâches en arrière-plan dans l’application :
JavaScript
var settings = Windows.Storage.ApplicationData.current.localSettings;
var keyMessage = "BA5857FA-DE2C-4A4A-BEF2-49D8B4130A39";
var operatorMessage = settings.values[keyMessage];
Étape 3 : Gérer l’événement Activation
Si le toast définit un paramètre, il est passé à l’application via detail.arguments.
Dans JavaScript ou C#, vous gérez l’événement WinJS.Application.onactivated , puis examinez les arguments d’événement passés au gestionnaire d’événements. L’activation à partir de toast transmet l’argument d’événement de type Windows.UI.WebUI.WebUILaunchActivatedEventArgs. Si la propriété detail.kind de l’argument d’événement est Windows.ApplicationModel.Activation.ctivationKind. l’application fournit l’expérience de démarrage ou l’expérience de notification, selon que la propriété detail.argument de l’argument d’événement a la valeur null.
JavaScript
WinJS.Application.addEventListener("activated", activated; false);
function activated(eventArgs)
{
if (eventArgs.detail.kind == Windows.ApplicationModel.Activation.ActivationKind.launch)
{
if (!eventArgs.detail.arguments)
{
// Initialize logic for the Start experience here.
}
else
{
// Initialize logic for the Notification experience here.
}
}
}
Étape 4 : Gérer les gestionnaires d’achèvement de tâches en arrière-plan
L’application de premier plan peut également inscrire un gestionnaire de saisie semi-automatique à notifier une fois la tâche en arrière-plan terminée. L’status d’achèvement ou toute exception qui se produit dans la méthode Run de la tâche en arrière-plan est passée au gestionnaire d’achèvement dans l’application de premier plan. Si l’application a été suspendue à la fin de la tâche, elle reçoit la notification d’achèvement la prochaine fois que l’application est reprise. Si l’application était à l’état Terminé , elle ne reçoit pas la notification d’achèvement. Si la tâche en arrière-plan doit conserver les informations qu’elle a exécutées avec succès, elle doit conserver les informations à l’aide du Gestionnaire d’états ou d’un autre moyen, tel qu’un fichier que l’application peut lire lorsqu’elle retourne à l’état En cours d’exécution .
Important Bien que l’événement d’arrière-plan de l’opérateur mobile soit inscrit automatiquement par le système dans l’application, l’application doit toujours s’exécuter au moins une fois pour s’inscrire aux gestionnaires d’achèvement ou de progression en arrière-plan.
C#
foreach (var cur in BackgroundTaskRegistration.AllTasks)
{
if(cur.Value.Name == “MobileOperatorNotificationHandler”)
{
cur.Value.Progress += new BackgroundTaskProgressEventHandler(OnProgress);
cur.Value.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);
}
}
//
// Handle background task completion.
private void OnCompleted(IBackgroundTaskRegistration sender, BackgroundTaskCompletedEventArgs e)
{
var taskCompletion = task as IBackgroundTaskRegistration;
var completionArgs = args.Context as BackgroundTaskCompletedEventArgs;
//
// If the background task threw an exception, display the exception in the error text box.
if (completionArgs.Status != null)
{
throw completionArgs.Status;
}
}
// Handle background task progress.
private void OnProgress(IBackgroundTaskRegistration sender, BackgroundTaskProgressEventArgs e)
{
var taskRegistration = task as IBackgroundTaskRegistration;
var progressArgs = args.Context as BackgroundTaskProgressEventArgs;
// progressArgs.Progress has the progress percentage
}
JavaScript
var iter = Windows.ApplicationModel.Background.BackgroundTaskRegistration.allTasks.first();
var hascur = iter.hasCurrent;
while (hascur) {
var cur = iter.current.value;
if (cur.name === “MobileOperatorNotificationHandler”) {
cur.addEventListener("progress", new ProgressHandler(cur).onProgress);
cur.addEventListener("completed", new CompleteHandler(cur).onCompleted);
}
hascur = iter.moveNext();
}
//
// Handle background task progress.
//
function ProgressHandler(task) {
this.onProgress = function (args) {
try {
var progress = "Progress: " + args.progress + "%";
} catch (ex) {
displayError(ex);
}
};
}
//
// Handle background task completion.
//
function CompleteHandler(task) {
this.onCompleted = function (args) {
try {
var key = task.taskId;
} catch (ex) {
displayError(ex);
}
};
}
Dépannage
Utilisez ces sections pour résoudre les problèmes qui peuvent survenir.
Déclencher l’analyse des métadonnées pour inscrire des tâches en arrière-plan
Pour les utilisateurs, lorsque l’appareil haut débit mobile est connecté, Windows 8, Windows 8.1 et Windows 10 installe automatiquement l’application haut débit mobile et les métadonnées de service associées et enregistre les tâches en arrière-plan définies dans les métadonnées du service. Toutefois, dans Windows 8.1, l’application n’est pas automatiquement épinglée à l’écran d’accueil.
Les développeurs peuvent déclencher manuellement des Windows 8, des Windows 8.1 et des Windows 10 pour analyser les métadonnées du service et inscrire des tâches en arrière-plan en appuyant sur la touche F5 (ou en cliquant avec le bouton droit et sélectionner Actualiser) dans la fenêtre Appareils et imprimantes sur le bureau. L’inscription des tâches en arrière-plan via l’analyse des métadonnées de service réussit uniquement lorsque l’application est déployée.
Vérifier que les tâches en arrière-plan sont correctement inscrites
Les développeurs peuvent vérifier que le Gestionnaire d’installation des appareils (DSM) a correctement analysé les métadonnées du service en affichant les journaux des événements sous Journaux d’application et de services\Microsoft\Windows\DeviceSetupManager.
Ouvrez l'observateur d'événements.
Sous l’onglet Menu , sélectionnez Affichage, puis cliquez sur Afficher les journaux analytiques et de débogage.
Accédez à Journaux des applications et des services\Microsoft\Windows\DeviceSetupManager.
Les événements d’intérêt incluent l’ID d’événement 220 qui indique que DSM a correctement inscrit la tâche en arrière-plan pour l’événement MobileOperatorNotification et l’ID d’événement 7900, qui indique les erreurs détectées dans le package de métadonnées.
Vérifier que les métadonnées d’approvisionnement sont correctement appliquées
Lorsque vous appliquez des métadonnées d’approvisionnement, vérifiez que ProvisionFromXmlDocumentResults.AllElementsProvisioned a la valeur true. Si ce n’est pas le cas, case activée ProvisionResultsXml pour plus d’informations sur l’erreur. Les erreurs courantes de haut débit mobile sont les suivantes :
Incompatibilité entre la carte SIM dans le PC et le fichier d’approvisionnement (le profil échoue avec ERROR_NOT_FOUND).
Incompatibilité entre le CarrierId dans le fichier d’approvisionnement et le numéro de service dans les métadonnées d’expérience.
Vérifier que les tâches en arrière-plan sont exécutées par le Répartiteur d’événements système
Vous pouvez vérifier que Windows génère l’événement MobileOperatorNotification et que la tâche en arrière-plan de l’application est exécutée par le répartiteur d’événements en vérifiant les observateur d'événements. La journalisation de ces événements est désactivée par défaut et peut être activée en effectuant les étapes suivantes :
Ouvrez l'observateur d'événements.
Sous l’onglet Menu , sélectionnez Affichage, puis cliquez sur Afficher les journaux analytiques et de débogage.
Accédez à Journaux des applications et des services\Microsoft\Windows\BackgroundTaskInfrastructure.
Cliquez avec le bouton droit sur Journal de diagnostic , puis sélectionnez Activer le journal.
Une fois que vous avez activé les journaux, une exécution réussie de la tâche en arrière-plan entraîne un événement ID d’événement = 1 qui a la description suivante : « Une instance d’une tâche en arrière-plan avec un point <d’entrée background_task_namespace_name>.<> background_task_class_name et le nom MobileOperatorNotificationHandler ont été créés dans la session 1 et ont reçu un ID de {11111111-1111-1111-1111-111111111111}».
Si la tâche en arrière-plan n’est pas exécutée, vérifiez d’abord que les noms de vos tâches en arrière-plan qui sont spécifiées dans les métadonnées du service correspondent aux noms du fichier AppXManifest.xml de votre package. Vérifiez qu’après le déploiement de l’application, l’analyse des métadonnées du service est déclenchée et insère l’appareil haut débit mobile.
Vérifier que Windows reçoit des notifications SMS et USSD
Vous pouvez vérifier que Windows reçoit des notifications SMS et USSD en vérifiant les événements SmsRouter dans observateur d'événements.
Dans observateur d'événements, sous Journaux d’application et de services\Microsoft\Windows \Mobile-Broadband-Experience-SmsRouter\Microsoft-Windows-SMSRouter, figurent des entrées telles que « Le SMSRouter a reçu un message de notification de l’opérateur SMS » et « SmsRouter a reçu un message texte ». Sous Journaux d’application et services\Microsoft\Windows \Mobile-Broadband-Experience-SmsApi\SMSApi se trouvent des entrées telles que « Application : Microsoft.SDKSamples.SmsSendReceive envoyé sms sms sur un appareil haut débit mobile : {11111111-1111-1111-1111-111111111111}».
Les sms reçus ne sont pas détectés comme des notifications d’opérateur
Si les SMS reçus ne sont pas détectés en tant que notifications d’opérateur, vérifiez les règles de filtrage personnalisées pour les notifications SMS administratives dans les métadonnées d’approvisionnement de compte. Pour plus d’informations sur l’approvisionnement des métadonnées, consultez Provisionnement de comptes.
En particulier, si les métadonnées d’approvisionnement de compte spécifient le numéro de téléphone de l’expéditeur, vérifiez que la mise en forme de nombre spécifiée correspond à celle du message reçu à l’aide des API SMS. Pour vérifier que cette correspondance est correcte, remplacez temporairement le modèle par [^]\* pour qu’il corresponde à tous les messages de cet expéditeur.
Exemple de fichier backgroundtask.js
//
// A JavaScript background task runs a specified JavaScript file.
//
(function () {
"use strict";
//
// The background task instance's activation parameters are available via Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
networkOperatorEventType = Windows.Networking.NetworkOperators.NetworkOperatorEventMessageType,
key = null,
settings = Windows.Storage.ApplicationData.current.localSettings;
try {
var details = backgroundTaskInstance.triggerDetails;
switch (details.notificationType) {
case networkOperatorEventType.gsm:
var textMessage = new Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(details.smsMessage);
showToast("Gsm Msg From: " + textMessage.from + "; TimeStamp: " + textMessage.timestamp, details.message);
break;
case networkOperatorEventType.cdma:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.ussd:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.dataPlanThresholdReached:
showToast("Mobile Broadband message", "Data plan threshold reached");
break;
case networkOperatorEventType.dataPlanReset:
showToast("Mobile Broadband message", "Data plan reset");
break;
case networkOperatorEventType.dataPlanDeleted:
showToast("Mobile Broadband message", "Data plan deleted");
break;
case networkOperatorEventType.profileConnected:
showToast("Mobile Broadband message", "Profile connected");
break;
case networkOperatorEventType.profileDisconnected:
showToast("Mobile Broadband message", "Profile disconnected");
break;
case networkOperatorEventType.registeredRoaming:
showToast("Mobile Broadband message", "Registered roaming");
break;
case networkOperatorEventType.registeredHome:
showToast("Mobile Broadband message", "Registered home");
break;
case networkOperatorEventType.tetheringEntitlementCheck:
showToast("Mobile Broadband message", "Entitlement check completed");
break;
default:
showToast("Mobile Broadband message", "Unknown message");
break;
}
taskSucceeded();
}
catch (exception) {
taskFailed();
}
function showToast(title, body) {
var notifications = Windows.UI.Notifications;
var toastNotificationManager = Windows.UI.Notifications.ToastNotificationManager;
var toastXml = toastNotificationManager.getTemplateContent(notifications.ToastTemplateType.toastText02);
//
// Pass to app through eventArguments.arguments.
//
var temp = "\"Title\"" + ":" + "\"" + title + "\"" + "," + "\"Message\"" + ":" + "\"" + body + "\"";
if (temp.length > 251) {
temp = temp.substring(0, 251);
}
toastXml.selectSingleNode("/toast").setAttribute("launch", "'{" + temp + "}'");
var textNodes = toastXml.getElementsByTagName("text");
textNodes[0].appendChild(toastXml.createTextNode(title));
textNodes[1].appendChild(toastXml.createTextNode(body));
var toast = new notifications.ToastNotification(toastXml);
toastNotificationManager.createToastNotifier().show(toast);
}
//
// This function is called when the background task is completed successfully.
//
function taskSucceeded() {
//
// Use the succeeded property to indicate that this background task completed successfully.
//
backgroundTaskInstance.succeeded = true;
backgroundTask.taskInstance.progress = 100;
console.log("Background " + backgroundTask.taskInstance.task.name + " Completed");
//
// Write to localSettings to indicate that this background task completed.
//
key = backgroundTaskInstance.task.taskId.toString();
settings.values[key] = "Completed";
//
// A JavaScript background task must call close when it is done.
//
close();
}
//
// If the task was canceled or failed, stop the background task.
//
function taskFailed() {
console.log("Background " + backgroundTask.taskInstance.task.name + " Failed");
backgroundTaskInstance.succeeded = false;
key = backgroundTaskInstance.task.taskId.toString();
settings.values[key] = "Failed";
close();
}
})();
Rubriques connexes
Activation des notifications de l’opérateur mobile et des événements système