Como manipular a ativação de URI (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Um aplicativo pode ser registrado para ser o manipulador padrão de um determinado nome de esquema de URI (Uniform Resource Identifier). Tanto os aplicativos de área de trabalho quanto os aplicativos do Tempo de Execução do Windows podem ser registrados para ser um manipulador padrão de nomes de esquema de URI. Se o usuário escolher seu aplicativo como o manipulador padrão para um nome de esquema de URI, seu aplicativo será ativado toda vez que esse tipo de URI for iniciado.

Recomendamos que você só se registre para um nome de esquema de URI se quiser manipular todas as inicializações de URI desse tipo de URI. Se você decidir se registrar para um nome de esquema de URI, você deve fornecer ao usuário final a funcionalidade esperada quando o seu aplicativo for ativado para esse esquema de URI. Por exemplo, um aplicativo que se registra para o nome de esquema de URI mailto: deve ser aberto para uma nova mensagem de email para que o usuário possa criar um novo email. Para saber mais sobre associações de URIs, veja Diretrizes e lista de verificação para tipos de arquivos e URIs.

Essas etapas mostram como registrar um nome de esquema de URI personalizado, alsdk://, e como seu aplicativo pode ser ativado quando o usuário inicia um URI alsdk://.

Observação

Nos aplicativos da Loja do Windows Phone, determinados URIs e extensões de arquivo são reservados para uso por aplicativos nativos e pelo sistema operacional. Tentativas de registrar seu aplicativo com um URI ou extensão de arquivo reservada serão ignoradas. Para saber mais, consulte a lista nesta página.

Instruções

Etapa 1: Especificar o ponto de extensão no manifesto do pacote

O aplicativo recebe os eventos de ativação somente para os nomes de esquema de URI listados no manifesto do pacote. Veja como indicar se seu aplicativo manipula o nome de esquema de URI alsdk .

Clique duas vezes para abrir package.appxmanifest no Gerenciador de Soluções.

Veja uma breve descrição de cada um dos campos que devem ser preenchidos no manifesto do pacote:

Campo	Descrição
Nome	Escolha o nome de um grupo de tipos de arquivos que compartilham o mesmo nome de exibição, logotipo, dica de informações e sinalizadores de edição. Escolha um nome de grupo que se mantenha nas atualizações de aplicativos. Observação O nome tem que ser todo com letras minúsculas. Tipos de arquivos reservados e proibidos Aqui estão listas alfabéticas de esquemas de Uri que você não pode registrar em seu aplicativo porque eles são reservados ou proibidos: Observação Para aplicativos da Windows Store application.manifest, application.reference, batfile, blob, cerfile, chm.file, cmdfile, comfile, cplfile, dllfile, drvfile, exefile, explorer.assocactionid.burnselection, explorer.assocactionid.closesession, explorer.assocactionid.erasedisc, explorer.assocactionid.zipselection, explorer.assocprotocol.search-ms, explorer.burnselection, explorer.closesession, explorer.erasedisc, explorer.zipselection, file, fonfile, hlpfile, htafile, inffile , insfile, internetshortcut, jsefile, lnkfile, microsoft.powershellscript.1, ms-accountpictureprovider, ms-appdata, ms-appx, ms-autoplay, msi.package, msi.patch, ms-windows-store, ocxfile, piffile, regfile, scrfile, scriptletfile, shbfile, shcmdfile, shsfile,smb, sysfile, ttffile,unknown, usertileprovider,vbefile,vbsfile, windows.gadget,wsffile, wsfile,wshfile Observação Para aplicativos da Windows Phone Store O Windows Phone reserva os seguintes esquemas de Uri para aplicativos integrados. bing, callto, dtmf, http, https, mailto, maps, ms-excel, ms-powerpoint, ms-settings-airplanemode, ms-settings-bluetooth, ms-settings-cellular, ms-settings-emailandaccounts, ms-settings-location, ms-settings-lock, ms-settings-wifi, ms-word, office, onenote, tel, wallet, xbls, zune O Windows Phone reserva os seguintes esquemas de Uri para o sistema operacional. Explorer.AssocActionId.BurnSelection, Explorer.AssocActionId.CloseSession, Explorer.AssocActionId.EraseDisc, Explorer.AssocActionId.ZipSelection, Explorer.AssocProtocol.search-ms, Explorer.BurnSelection, Explorer.CloseSession, Explorer.EraseDisc, Explorer.ZipSelection, File, Iehistory, Ierss, Javascript, Jscript, LDAP, Res, rlogin, StickyNotes, telnet, tn3270, Vbscript, windowsmediacenterapp, windowsmediacenterssl, windowsmediacenterweb, WMP11.AssocProtocol.MMS
Nome de Exibição	Especifique o nome de exibição para identificar o nome de esquema de URI em Definir Programas Padrão no Painel de Controle.
Logotipo	Especifique o logotipo que é usado para identificar o nome de esquema de URI em Definir Programas Padrão no Painel de Controle. Se nenhum logotipo for especificado, o logotipo pequeno do aplicativo será usado.
Exibição desejada (somente Windows)	Especifique o campo Desired View para indicar a quantidade de espaço que a janela do aplicativo precisa para ser iniciada para o nome do esquema URI. Os valores possíveis do Desired View são Default, UseLess, UseHalf, UseMore ou UseMinimum. Observação O Windows leva em conta vários fatores diferentes para determinar o tamanho da janela final do aplicativo de destino, por exemplo, a preferência do aplicativo de origem, o número de aplicativos na tela, a orientação da tela e assim por diante. A definição de Modo de Exibição Desejado não garante um comportamento de janelas específico para o aplicativo de destino. Windows 8.1: Desired View não é suportado até o Windows 8.1 e Windows Server 2012 R2. Windows Phone: Desired View não é suportado no no Windows Phone.

Selecione a guia Declarações.
Selecione Protocolo na lista suspensa e clique em Adicionar.
Insira alsdk como o Nome.
Insira “images\Icon.png” como o logotipo.
Pressione Ctrl+S para salvar a alteração para package.appxmanifest.

Isto adiciona ao manifesto do pacote um elemento Extension similar a este. A categoria windows.protocol indica se o aplicativo manipula o nome do esquema de URI alsdk .


<Package xmlns="https://schemas.microsoft.com/appx/2010/manifest" xmlns:m2="https://schemas.microsoft.com/appx/2013/manifest">
   <Applications>
      <Application Id="AutoLaunch.App">
         <Extensions>
            <Extension Category="windows.protocol">
               <Protocol Name="alsdk"/>
               <Logo>images\logo.png</Logo>                                     
               <DisplayName>SDK Sample URI Scheme</DisplayName>
            </Extension>                      
         </Extensions>
      </Application>
   </Applications>
</Package>

Etapa 2: Adicione os ícones apropriados

Os aplicativos que se tornam padrão para um nome de esquema de URI terão seus ícones exibidos em vários locais em todo o sistema; por exemplo, no Painel de Controle de Programas Padrão.

Recomendamos que você inclua no seu projeto os ícones apropriados para que seu logotipo fique legal em todos esses locais. Para um aplicativo da Windows Store, inclua na sua pasta de imagens tamanhos de logotipos e ícones pequenos de 16/32/48/256 pixels. Para um aplicativo da Loja do Windows Phone, inclua versões de 63/129/336 pixels. Combine a aparência do logotipo do bloco do aplicativo com a paleta de cores incorporada e faça o logotipo se estender para a borda sem preenchê-la. Teste seus ícones em telas segundo plano brancas. Para ícones de exemplo, veja a Amostra de lançamento de associação (Windows).

O Gerenciador de Soluções com uma exibição dos arquivos na pasta de imagens. Existem versões de 16, 32, 48 e 256 pixels de ‘Icon.targetsize’ e ‘smallTile-sdk’

Etapa 3: Registrar-se para o evento ativado

Registre-se no evento activated para manipular a ativação de URIs.

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

Etapa 4: Manipular o evento ativado

O manipulador de eventos activated registrado na etapa 1 recebe todos os eventos de ativação. A propriedade kind indica o tipo de evento de ativação. Este exemplo é configurado para manipular os eventos de ativação protocol.

function onActivatedHandler(eventArgs) {
   if (eventArgs.detail.kind == Windows.ApplicationModel.Activation.ActivationKind.protocol) 
   {
       // TODO: Handle URI activation.

       // The received URI is eventArgs.detail.uri.rawUri
   }
}

Comentários

Qualquer aplicativo ou site pode usar seu nome de esquema de URI, inclusive os maliciosos. Assim, qualquer dado que você obtenha no URI pode vir de uma fonte não confiável. Recomendamos que você nunca execute uma ação permanente com base nos parâmetros recebidos no URI. Por exemplo, os parâmetros de URI poderiam ser usados para iniciar o aplicativo em uma página de conta de usuário, mas nunca devem ser usados para modificar diretamente a conta do usuário.

Observação Se você está criando um novo nome de esquema de URI para seu aplicativo, siga a diretriz em RFC 4395. Isso garante que seu nome atenda aos padrões de esquemas de URI.

Observação

Quando iniciado por Contrato de Protocolo, os aplicativos da Loja do Windows Phone devem assegurar que o botão Voltar leve o usuário de volta à tela que iniciou o aplicativo e não ao conteúdo anterior do aplicativo.

É recomendado que os aplicativos criem um novo Quadro XAML para cada evento de ativação que abre um novo destino de Uri. Dessa forma, o backstack de navegação para o novo Quadro XAML não terá nenhum conteúdo anterior que o aplicativo possa ter na janela atual quando suspenso.

Aplicativos que decidem usar um único Quadro XAML para contratos de Ativação e Protocolo devem limpar as páginas do diário de navegação do Quadro antes de navegar para uma nova página. Quando ativado por Contrato de Protocolo, os aplicativos devem considerar incluir uma interface do usuário que permite ao usuário voltar para o início do aplicativo.