Partilhar via

Como fazer a transição de usuários de seu aplicativo não empacotado da Web para o aplicativo empacotado do Store

  • Artigo

Se você distribuir seu aplicativo como um download da Web (EXE /MSI) e, no Store, como um aplicativo empacotado (MSIX), convém impedir que os usuários instalem ambas as versões ou migrem usuários da versão da Web não empacotada para a versão do Store. Este guia fornecerá instruções sobre como fazer a transição perfeita dos usuários da versão não empacotada para a versão empacotada.

Dois cenários serão descritos abaixo:

  1. O usuário já instalou a versão não empacotada baseada na Web e você deseja substituí-la pela versão empacotada do Store.
  2. O usuário já instalou as duas versões e você deseja dar prioridade à versão empacotada do Store e desinstalar a versão não empacotada baseada na Web.

Cenário 1: atualizar automaticamente o aplicativo não empacotado da Web para o aplicativo empacotado do Store

Se você pretende migrar automaticamente seus usuários do aplicativo não empacotado da Web para a versão empacotada do Store, recomendamos seguir as seguintes etapas:

  1. Habilite seu aplicativo empacotado do Store para usar pinos existentes da barra de tarefas e do menu Iniciar, garantindo que os usuários mantenham seus atalhos quando o aplicativo empacotado do Store substituir o aplicativo não empacotado da Web.
  2. Baixe e instale silenciosamente a versão do Store a partir de sua versão da Web não empacotada.
  3. Indique aos usuários que o aplicativo será reiniciado para aplicar uma atualização
  4. Depois de baixado e instalado, inicie a versão empacotada do Store e feche a versão não empacotada da Web.
  5. No aplicativo empacotado do Store, migre os dados para a nova pasta de dados do aplicativo.
  6. Finalmente, desinstale programaticamente a versão da Web não empacotada.

Cenário 2: desinstale o aplicativo não empacotado baseado na Web se o usuário tiver instalado as duas versões.

Você pode permitir que seus usuários usem as duas versões do seu aplicativo lado a lado, mas você terá que gerenciar conflitos entre o aplicativo e será responsável por sincronizar os dados entre as duas versões.

Se você preferir que seus usuários usem apenas uma versão e priorizem a versão do Store, estas são algumas recomendações:

  1. Habilite seu aplicativo empacotado do Store para usar pinos existentes da barra de tarefas e do menu Iniciar, garantindo que os usuários mantenham seus atalhos quando o aplicativo empacotado do Store substituir o aplicativo não empacotado da Web.
  2. O aplicativo Store deve detectar se a versão não empacotada está presente e desinstalá-la na inicialização
  3. Quando os usuários iniciam o aplicativo não empacotado, você deve iniciar automaticamente a versão empacotada
  4. Potencialmente migrar os dados, se desejar
  5. Finalmente, desinstale programaticamente a versão da Web não empacotada.

Recomendações técnicas

Como instalar o aplicativo empacotado do Store a partir do seu aplicativo não empacotado da Web

Para iniciar o download e a instalação, você deve saber a ID do Store do seu aplicativo. Essa ID de 12 caracteres pode ser obtida no Partner Center, especificamente na seção "Identidade do produto", mesmo que sua inscrição ainda não tenha sido enviada.

Posteriormente, você pode usar o código a seguir para baixar e instalar silenciosamente o aplicativo do store. Este código irá:

  1. Atribuir um direito ao usuário atual do Store, se houver; caso contrário, o direito será associado ao dispositivo.
  2. Iniciar o download e a instalação do produto sem gerar notificações do sistema.
  3. Você pode monitorar o progresso do download e da instalação usando as APIs de evento.
    private async Task<bool> DownloadStoreVersionAsync()
    {
        var productId = "<Product Id from Partner Center>";
        var applicationName = "<name of your application>";

        var appInstallManager = new AppInstallManager();
        var entitlement = await appInstallManager.GetFreeUserEntitlementAsync(productId, string.Empty, string.Empty);
        if (entitlement.Status is GetEntitlementStatus.NoStoreAccount)
        {
            entitlement = await appInstallManager.GetFreeDeviceEntitlementAsync(productId, string.Empty, string.Empty);
        }
        if (entitlement.Status is not GetEntitlementStatus.Succeeded)
        {
            return false;
        }

        var options = new AppInstallOptions()
        {
            LaunchAfterInstall = true,
            CompletedInstallToastNotificationMode = AppInstallationToastNotificationMode.NoToast
        };
        var items = await appInstallManager.StartProductInstallAsync(productId, string.Empty, applicationName, string.Empty, options);
        var firstItem = items.FirstOrDefault();
        if(firstItem is null)
        {
            return false;
        }
        firstItem.StatusChanged += StoreInstallation_StatusChanged;
        firstItem.Completed += StoreInstallation_Completed;
        return true;
    }

    private void StoreInstallation_Completed(AppInstallItem sender, object args)
    {
        // Launch the new Store version when ready and close this application
        // The Store version will then be responsible of migrating the data and uninstall the unpackaged version
    }

    private void StoreInstallation_StatusChanged(AppInstallItem sender, object args)
    {
        var status = sender.GetCurrentStatus();
        switch(status.InstallState)
        {
            case AppInstallState.Installing:
                {
                    // Show installing status
                }
                break;
            case AppInstallState.Downloading:
                {
                    // Show download progress using status.PercentComplete
                }
                break;
            ...
        }

Como iniciar o aplicativo do Store a partir do seu aplicativo não empacotado da Web

Para iniciar um aplicativo do Store, é necessário saber seu AMUID, que consiste no Nome da Família do Pacote (encontrado na seção "Identidade do Produto" do Partner Center) e o ID do Aplicativo (do seu appxmanifest), separados por um ponto de exclamação (!).

        Process.Start(
            "explorer.exe",
            "shell:AppsFolder\\Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"
        );

Como detectar se a versão empacotada do Store está instalada e iniciá-la

Você pode determinar se sua versão empacotada do aplicativo está instalada usando a API win32 GetPackagesByPackageFamily e enviando o Nome da Família de Pacotes do seu aplicativo empacotado. Se o valor de contagem for maior que zero, isso indica que o aplicativo está instalado.

Como desinstalar seu aplicativo da Web desempacotado do aplicativo empacotado

Para recuperar o caminho absoluto do seu desinstalador, você pode acessar o registro.

Suas informações de desinstalação estão localizadas no registro em:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\<your product code GUID\>

Recupere o comando completo no valor UninstallString e execute-o. É recomendável executar a desinstalação silenciosamente ou informar ao usuário que você está migrando dados e desinstalando o outro aplicativo.

Como migrar dados

Seu aplicativo não empacotado provavelmente armazena seus dados locais em:

%localAppData%/<YourPublisherName\>/<YourAppName\>

Os aplicativos empacotados têm seu espaço reservado para armazenamento de dados, que é excluído automaticamente quando o aplicativo é desinstalado. É altamente recomendável (embora não obrigatório) migrar os dados para este espaço na primeira inicialização. Você pode recuperar o caminho absoluto dessa pasta chamando Windows.Storage.ApplicationData.Current.LocalFolder.Path.

Como migrar aquisições e compras no aplicativo

Compras no aplicativo

Para garantir uma experiência de usuário ideal, é essencial que os usuários possam acessar perfeitamente o conteúdo que compraram na versão não empacotada do seu aplicativo. Com esse objetivo, o Microsoft Store aumentou sua flexibilidade para editores, permitindo o uso de plataformas de comércio próprias ou de terceiros, além das plataformas da Microsoft, desde junho de 2021.

Recomendamos fortemente que os editores continuem verificando os direitos de compra no aplicativo, conforme feito na versão não empacotada de seus aplicativos, além de se integrarem à plataforma Microsoft Commerce para permitir que os usuários comprem seu conteúdo sem esforço com apenas alguns cliques no Windows.

Permitir que usuários pagos do aplicativo não empacotado migrem para a versão empacotada

Se os usuários compraram seu produto em seu site, eles não devem ter que pagar novamente para baixar a versão empacotada do Store. Para garantir uma transição perfeita, recomendamos as seguintes abordagens:

  1. Ofereça uma versão gratuita/de demonstração do seu produto, permitindo que os usuários desbloqueiem a versão completa por meio de compras no aplicativo. Para usuários que já pagaram em seu site, habilite-os a acessar a versão completa, entrando para verificar suas licenças ou inserindo sua chave de licença na interface do usuário do aplicativo.
  2. Defina seu aplicativo como uma oferta paga, mas distribua o código do cupom para seus usuários existentes por meio de seu próprio canal. Esses códigos permitirão que eles baixem a versão do Store sem custo adicional. Mais informações podem ser encontradas em Gerar códigos promocionais.

Como migrar atalhos existentes da barra de tarefas fixada e do Menu Iniciar

Os usuários podem ter colocado seu aplicativo desktop na barra de tarefas ou no Menu Iniciar. Você pode direcionar esses atalhos para seu novo aplicativo empacotado incluindo a extensão "windows.desktopAppMigration" no manifesto do aplicativo.

Exemplo

xmlns:rescap3="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities/3"
...
<Extensions>
<rescap3:Extension Category="windows.desktopAppMigration">
<rescap3:DesktopAppMigration>
<rescap3:DesktopApp AumId="[your_app_aumid]" />
<rescap3:DesktopApp ShortcutPath="%USERPROFILE%\Desktop\[my_app].lnk" />
<rescap3:DesktopApp ShortcutPath="%APPDATA%\Microsoft\Windows\Start Menu\Programs\[my_app].lnk" />
<rescap3:DesktopApp ShortcutPath="%PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\[my_app_folder]\[my_app].lnk"/>
</rescap3:DesktopAppMigration>
</rescap3:Extension>
</Extensions>

Depois de instalar seu aplicativo, os pinos na barra de tarefas ou no menu Iniciar, bem como os blocos (para Windows 10) iniciarão automaticamente o aplicativo do Store.

Como migrar a extensão de arquivo & associações de protocolo

Se seu aplicativo oferecer suporte a associações de protocolo ou extensões de arquivo e os usuários tiverem selecionado seu aplicativo como padrão para extensões de arquivo e protocolos específicos, você terá a opção de migrar essas associações para o aplicativo empacotado do Store. Essa migração pode ser obtida atualizando o manifesto do aplicativo com o seguinte trecho de código.

xmlns:rescap3="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities/3"
...
<Extensions>
<uap:Extension Category="windows.fileTypeAssociation">
<uap3:FileTypeAssociation Name=".foo">
<rescap3:MigrationProgIds>
<rescap3:MigrationProgId>Foo.Bar.1</rescap3:MigrationProgId>
</rescap3:MigrationProgIds>
…
</uap3:FileTypeAssociation>
</uap:Extension>
</Extensions>

Basta listar os identificadores programáticos para os quais você deseja migrar, e o sistema os migrará automaticamente para seu aplicativo após a instalação.