Partilhar via


Desenvolver um aplicativo para lidar com o evento MobileOperatorNotification

Este tópico explica como desenvolver um aplicativo de banda larga móvel que manipula o evento MobileOperatorNotification .

Melhores práticas

Para tratamento de eventos em segundo plano, você deve usar as seguintes práticas recomendadas:

  • Não registre-se para eventos em segundo plano nos quais você não pode executar uma ação. O processamento desses eventos consumirá desnecessariamente a cota do aplicativo.

  • Não execute grandes quantidades de processamento no recebimento de um evento em segundo plano.

  • Considere adiar o processamento para a próxima vez que o aplicativo for iniciado.

  • Considere mostrar uma notificação do sistema e atualizar o bloco em resposta a um evento em segundo plano. Seu aplicativo de banda larga móvel pode processar o conteúdo do evento em segundo plano.

Etapa 1: Declaração de contrato de tarefa em segundo plano

Para que o Windows reconheça as experiências de tarefa em segundo plano fornecidas por um aplicativo de banda larga móvel, o aplicativo deve declarar que está fornecendo uma extensão para a funcionalidade do sistema.

Para fazer a declaração no arquivo package.appxmanifest para seu projeto do Visual Studio, execute as seguintes etapas:

Para declarar um contrato de tarefa em segundo plano

  1. Em Gerenciador de Soluções, clique duas vezes no arquivo package.appxmanifest do projeto.

  2. Na guia Declarações , em Declarações Disponíveis, selecione Tarefas em Segundo Plano e clique em Adicionar.

  3. No título Propriedades , insira as seguintes informações do aplicativo:

    • Na caixa Página inicial em Configurações do aplicativo, para um aplicativo de banda larga móvel que usa JavaScript e HTML, insira o nome do arquivo que manipula a tarefa em segundo plano no aplicativo (por exemplo, backgroundtask.js).

    • No título Tipos de tarefa com suporte, clique na caixa marcar de eventos do sistema.

Se isso for feito corretamente, você deverá ter um elemento de extensão semelhante ao seguinte no arquivo package.appxmanifest.

<Extension Category="windows.backgroundTasks" StartPage="backgroundtask.js">
  <BackgroundTasks>
    <Task Type="systemEvent" />
  </BackgroundTasks>
</Extension>

Etapa 2: manipulador de tarefas em segundo plano

Se o aplicativo fornecer uma declaração de notificações da operadora móvel, ele deverá fornecer um manipulador para a ativação da tarefa em segundo plano. O manipulador obterá a ID da conta de rede da operadora móvel e os dados de evento de Windows.Networking.NetworkOperators.NetworkOperatorNotificationEventDetails.

Como a única interface do usuário compatível com a tarefa em segundo plano é Toast, o manipulador de tarefas em segundo plano pode mostrar Toast ou salvar NetworkOperatorNotificationEventDetails no armazenamento local.

Os exemplos de código a seguir demonstram uma tarefa em segundo plano projetada para ser executada quando uma nova notificação de SMS administrativa é recebida.

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

Mostrar notificações do bloco e do sistema

Recomendamos que você mostre notificações do sistema e do bloco em seu aplicativo de banda larga móvel porque um usuário pode perder uma notificação do sistema devido à sua natureza transitória. Para obter diretrizes de design de experiência de notificação do sistema e atualização de bloco, consulte Projetando a experiência do usuário de um aplicativo de banda larga móvel.

Para habilitar notificações do sistema

  1. Em Gerenciador de Soluções, clique duas vezes no arquivo package.appxmanifest do projeto.

  2. Na guia Interface do usuário do aplicativo , no título Notificações , defina Sistema compatível comSim.

Se isso for feito corretamente, você deverá ter um elemento de extensão semelhante ao seguinte no arquivo package.appxmanifest.

<VisualElements … ToastCapable="true"… />

O código a seguir mostra como exibir uma notificação do sistema em um identificador de tarefa em segundo plano:

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

Obter mensagem de texto SMS

Se a tarefa em segundo plano tiver sido disparada por uma mensagem SMS de entrada, os detalhes da tarefa em segundo plano carregarão o objeto SMS em seu conteúdo.

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

Usar o armazenamento local

A tarefa em segundo plano pode usar o armazenamento local para salvar a mensagem que você obtém do evento em segundo plano, para que o aplicativo possa usar essas informações mais tarde.

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;

O código a seguir demonstra como recuperar a mensagem armazenada pelo manipulador de tarefas em segundo plano no aplicativo:

JavaScript

var settings = Windows.Storage.ApplicationData.current.localSettings;
    var keyMessage = "BA5857FA-DE2C-4A4A-BEF2-49D8B4130A39";
    var operatorMessage = settings.values[keyMessage];

Etapa 3: Manipular o evento de ativação

Se o sistema definir um parâmetro, ele será passado para o aplicativo por meio de detail.arguments.

Em JavaScript ou C#, você manipula o evento WinJS.Application.onactivated e examina os argumentos de evento que são passados para o manipulador de eventos. A ativação do sistema passa o argumento de evento do tipo Windows.UI.WebUI.WebUILaunchActivatedEventArgs. Se a propriedade detail.kind do argumento de evento for Windows.ApplicationModel.Activation.ctivationKind. launch, o aplicativo fornece a experiência Iniciar ou a experiência de Notificação, dependendo se a propriedade detail.argument do argumento de evento está definida como nula.

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

Etapa 4: Manipular manipuladores de conclusão de tarefas em segundo plano

O aplicativo em primeiro plano também pode registrar um manipulador de conclusão a ser notificado quando a tarefa em segundo plano for concluída. A conclusão status ou qualquer exceção que ocorra no método Run da tarefa em segundo plano é passada para o manipulador de conclusão no aplicativo em primeiro plano. Se o aplicativo tiver sido suspenso quando a tarefa for concluída, ele receberá a notificação de conclusão na próxima vez que o aplicativo for retomado. Se o aplicativo estiver no estado Encerrado , ele não receberá a notificação de conclusão. Se a tarefa em segundo plano precisar preservar as informações que ela executou com êxito, ela deverá persistir as informações usando o Gerenciador de Estado ou outro meio, como um arquivo que o aplicativo pode ler quando retornar ao estado Em execução .

Importante Embora o evento em segundo plano da operadora móvel seja registrado automaticamente pelo sistema para o aplicativo, o aplicativo ainda precisa executar pelo menos uma vez para se registrar nos manipuladores de conclusão ou progresso em segundo plano.

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

Solução de problemas

Use estas seções para ajudar a solucionar problemas que podem surgir.

Disparar análise de metadados para registrar tarefas em segundo plano

Para os usuários, quando o dispositivo de banda larga móvel está conectado, Windows 8, Windows 8.1 e Windows 10 instala automaticamente o aplicativo de banda larga móvel e os metadados de serviço associados e registra tarefas em segundo plano definidas nos metadados do serviço. No entanto, em Windows 8.1, o aplicativo não é fixado automaticamente na tela Inicial.

Os desenvolvedores podem disparar manualmente Windows 8, Windows 8.1 e Windows 10 para analisar metadados de serviço e registrar tarefas em segundo plano pressionando a tecla F5 (ou clique com o botão direito do mouse e selecione Atualizar) na janela Dispositivos e Impressoras na área de trabalho. O registro de tarefas em segundo plano por meio da análise de metadados de serviço só é bem-sucedido quando o aplicativo é implantado.

Verifique se as tarefas em segundo plano estão registradas corretamente

Os desenvolvedores podem verificar se o Gerenciador de Instalação de Dispositivos (DSM) analisou corretamente os metadados de serviço exibindo os logs de eventos em Logs de Aplicativos e Serviços\Microsoft\Windows\DeviceSetupManager.

  1. Visualizador de EventosAberto.

  2. Na guia Menu , selecione Exibir e, em seguida, clique em Mostrar Logs de Análise e Depuração.

  3. Navegue até Logs de Aplicativos e Serviços\Microsoft\Windows\DeviceSetupManager.

Os eventos de interesse incluem a ID de Evento 220 que indica que o DSM registrou com êxito a tarefa em segundo plano para o evento MobileOperatorNotification e a ID de Evento 7900, que indica todos os erros encontrados no pacote de metadados.

Verifique se os metadados de provisionamento foram aplicados com êxito

Ao aplicar metadados de provisionamento, verifique se ProvisionFromXmlDocumentResults.AllElementsProvisioned é verdadeiro. Caso contrário, marcar ProvisionResultsXml para obter mais detalhes sobre o erro. Os erros comuns de banda larga móvel incluem o seguinte:

  • Uma incompatibilidade entre o SIM no computador e o arquivo de provisionamento (o perfil falha com ERROR_NOT_FOUND).

  • Uma incompatibilidade entre CarrierId no arquivo de provisionamento e o número de serviço nos metadados da experiência.

Verifique se as tarefas em segundo plano estão sendo executadas pelo Agente de Eventos do Sistema

Você pode verificar se o Windows está gerando o evento MobileOperatorNotification e se a tarefa em segundo plano do aplicativo está sendo executada pelo agente de eventos verificando o Visualizador de Eventos. O registro em log desses eventos está desativado por padrão e pode ser habilitado executando as seguintes etapas:

  1. Visualizador de EventosAberto.

  2. Na guia Menu , selecione Exibir e, em seguida, clique em Mostrar Logs de Análise e Depuração.

  3. Navegue até Logs de Aplicativos e Serviços\Microsoft\Windows\BackgroundTaskInfrastructure.

  4. Clique com o botão direito do mouse em Log de diagnóstico e selecione Habilitar Log.

Depois de habilitar os logs, uma execução bem-sucedida da tarefa em segundo plano resulta em um evento de ID de Evento = 1 que tem a seguinte descrição: "Uma instância de uma tarefa em segundo plano com ponto <de entrada background_task_namespace_name>.<> background_task_class_name e nome MobileOperatorNotificationHandler foi criado na sessão 1 e recebeu uma ID de {11111111-1111-1111-1111-111111111111}."

Se a tarefa em segundo plano não estiver sendo executada, primeiro verifique se os nomes das tarefas em segundo plano especificados nos metadados do serviço correspondem aos nomes no arquivo AppXManifest.xml do pacote. Verifique se, depois de implantar o aplicativo, a análise dos metadados do serviço é disparada e insere o dispositivo de banda larga móvel.

Verifique se o Windows recebe notificações por SMS e USSD

Você pode verificar se o Windows está recebendo notificações sms e USSD verificando se há eventos smsRouter em Visualizador de Eventos.

Em Visualizador de Eventos, em Logs de Aplicativos e Serviços\Microsoft\Windows \Mobile-Broadband-Experience-SmsRouter\Microsoft-Windows-SMSRouter, estão entradas como "O SMSRouter recebeu uma mensagem de notificação do operador SMS" e "O SMSRouter recebeu uma mensagem de texto". Em Logs de Aplicativos e Serviços\Microsoft\Windows \Mobile-Broadband-Experience-SmsApi\SMSApi estão entradas como "Aplicativo: Microsoft.SDKSamples.SmsSendReceive enviou mensagem de texto SMS no dispositivo de banda larga móvel: {11111111-1111-1111-1111-111111111111}".

As mensagens SMS recebidas não são detectadas como notificações do operador

Se o SMS recebido não for detectado como notificações de operador, verifique as regras de filtragem personalizadas para notificações administrativas por SMS nos metadados de provisionamento de conta. Para obter mais informações sobre como provisionar metadados, consulte Provisionamento de conta.

Em particular, se os metadados de provisionamento de conta especificarem o número de telefone do remetente, verifique se a formatação de número especificada corresponde à da mensagem recebida usando as APIs de SMS. Para verificar se isso está correspondendo corretamente, altere temporariamente o Padrão para [^]\* para corresponder a todas as mensagens desse remetente.

Arquivo de backgroundtask.js de exemplo

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

Habilitar notificações da operadora móvel e eventos do sistema

Criando e configurando experiências de compartilhamento de Internet