Adicionando o suporte para Minhas Pessoas a um aplicativo

O recurso Minhas Pessoas permite que os usuários fixem contatos de um aplicativo diretamente na barra de tarefas, o que cria um novo objeto de contato com o qual eles podem interagir de várias maneiras. Este artigo mostra como você pode adicionar suporte para esse recurso, permitindo que os usuários fixem contatos diretamente do seu aplicativo. Quando os contatos são fixados, novos tipos de interação do usuário ficam disponíveis, como Notificação e compartilhamento de Minhas Pessoas.

Requisitos

• Windows 10 e Microsoft Visual Studio 2019. Para obter detalhes de instalação, consulte Configurar com o Visual Studio.
• Conhecimento básico de C# ou de uma linguagem de programação similar orientada a objeto. Para começar a usar o C#, consulte Criar um aplicativo "Olá, mundo"..

Visão geral

Há três coisas que você precisa fazer para permitir que seu aplicativo use o recurso Minhas Pessoas:

1. Declare suporte para o contrato de ativação shareTarget no manifesto do aplicativo.
2. Anote os contatos que os usuários podem compartilhar usando seu aplicativo.
3. Ofereça suporte a várias instâncias do seu aplicativo em execução ao mesmo tempo. Os usuários devem ser capazes de interagir com uma versão completa do seu aplicativo ao usá-lo em um painel de contatos. Eles podem até usá-lo em vários painéis de contato ao mesmo tempo. Para oferecer suporte a isso, seu aplicativo precisa ser capaz de executar várias exibições simultaneamente. Para saber como fazer isso, consulte o artigo "mostrar várias exibições para um aplicativo".

Quando você fizer isso, seu aplicativo aparecerá no painel de contatos para contatos anotados.

Declarando apoio ao contrato

Para declarar suporte para o contrato Minhas Pessoas, abra seu aplicativo no Visual Studio. No Gerenciador de Soluções, clique com o botão direito do mouse em Package.appxmanifest e selecione Abrir com. No menu, selecione Editor XML (Texto) e clique em OK. Faça as seguintes alterações no manifesto:

Antes

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	    </Application>
	</Applications>

Depois

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	      <Extensions>
	        <uap4:Extension Category="windows.contactPanel" />
	      </Extensions>
	    </Application>
	</Applications>

Com esta adição, a sua aplicação pode agora ser iniciada através do contrato windows.ContactPanel, que permite interagir com painéis de contato.

Anotando contatos

Para permitir que os contatos do seu aplicativo apareçam na barra de tarefas por meio do painel Minhas Pessoas, você precisa gravá-los no repositório de contatos do Windows. Para saber como escrever contatos, consulte a amostra Cartão de contato.

Seu aplicativo também deve escrever uma anotação para cada contato. Anotações são partes de dados do seu aplicativo que estão associadas a um contato. A anotação deve conter a classe ativável correspondente à exibição desejada em seu membro ProviderProperties, e declarar apoio à operação ContactProfile.

Você pode anotar contatos a qualquer momento enquanto seu aplicativo estiver em execução, mas geralmente você deve anotar contatos assim que eles forem adicionados ao repositório de contatos do Windows.

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 5))
{
	// Create a new contact annotation
	ContactAnnotation annotation = new ContactAnnotation();
	annotation.ContactId = myContact.Id;

	// Add appId and contact panel support to the annotation
	String appId = "MyApp_vqvv5s4y3scbg!App";
	annotation.ProviderProperties.Add("ContactPanelAppID", appId);
	annotation.SupportedOperations = ContactAnnotationOperations.ContactProfile;

	// Save annotation to contact annotation list
	// Windows.ApplicationModel.Contacts.ContactAnnotationList 
	await contactAnnotationList.TrySaveAnnotationAsync(annotation));
}

O "appId" é o Nome da Família do Pacote, seguido de "!" e o ID de classe ativável. Para localizar seu Nome da Família de Pacotes, abra Package.appxmanifest usando o editor padrão e procure na guia "Embalagem". Aqui, "Aplicativo" é a classe ativável correspondente à visualização de inicialização do aplicativo.

Permitir que os contatos convidem novos usuários em potencial

Por padrão, seu aplicativo só aparecerá no painel de contatos para contatos que você anotou especificamente. O objetivo é evitar confusão com contatos que não podem ser interagidos por meio do seu aplicativo. Se você quiser que seu aplicativo apareça para contatos que ele não conhece (para convidar usuários a adicionar esse contato à conta deles, por exemplo), você pode adicionar o seguinte ao manifesto:

Antes

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
    	<uap4:Extension Category="windows.contactPanel" />
	  </Extensions>
	</Application>
</Applications>

Depois

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
		<uap4:Extension Category="windows.contactPanel">
	    	<uap4:ContactPanel SupportsUnknownContacts="true" />
		</uap4:Extension>
	  </Extensions>
	</Application>
</Applications>

Com essa alteração, seu aplicativo aparecerá como uma opção disponível no painel de contatos para todos os contatos que o usuário fixou. Quando seu aplicativo é ativado usando o contrato do painel de contato, você deve verificar se é um contato que seu aplicativo conhece. Caso contrário, você deve mostrar a nova experiência de usuário do seu aplicativo.

Suporte para aplicativos de email

Se você estiver escrevendo um aplicativo de email, não precisará anotar todos os contatos manualmente. Se você declarar suporte para o painel de contatos e para o protocolo mailto:, seu aplicativo aparecerá automaticamente para usuários com um endereço de email.

Executar no painel de contatos

Agora que seu aplicativo aparece no painel de contatos para alguns ou todos os usuários, você precisa lidar com a ativação com o contrato do painel de contatos.

override protected void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.ContactPanel)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        var rootFrame = new Frame();

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;

        // Navigate to the page that shows the Contact UI.
        rootFrame.Navigate(typeof(ContactPage), e);

        // Ensure the current window is active
        Window.Current.Activate();
    }
}

Quando seu aplicativo for ativado com este contrato, ele receberá um objeto ContactPanelActivatedEventArgs. Ele contém a ID do contato com o qual seu aplicativo está tentando interagir na inicialização e um objeto ContactPanel. Você deve manter uma referência a esse objeto ContactPanel, que permitirá que você interaja com o painel.

O objeto ContactPanel tem dois eventos que seu aplicativo deve escutar:

• O evento LaunchFullAppRequested é enviado quando o usuário invoca o elemento da IU que solicita que seu aplicativo completo seja iniciado em sua própria janela. Seu aplicativo é responsável por seu autoinício, passando todo o contexto necessário. Você é livre para fazer isso como quiser (por exemplo, via lançamento de protocolo).
• O evento Closing é enviado quando seu aplicativo está prestes a ser fechado, permitindo que você salve qualquer contexto.

O objeto ContactPanel também permite que você defina a cor de plano de fundo do cabeçalho do painel de contatos (se não estiver definido, ele será o padrão para o tema do sistema) e feche programaticamente o painel de contatos.

Suporte a atribuição de selo de notificação

Se quiser que os contatos fixados na barra de tarefas sejam marcados quando novas notificações chegarem do seu aplicativo relacionadas a essa pessoa, inclua o parâmetro hint-people nas suas notificações "toast" e notificações expressivas do Minhas Pessoas.

Para marcar um contato, o nó do sistema de nível superior deve incluir o parâmetro hint-people para indicar o contato de envio ou relacionado. Esse parâmetro pode ter um dos seguintes valores:

• Endereço de email
  • Por exemplo, johndoe@mydomain.com
• Telephone number
  • Por exemplo, 888-888-8888
• ID remota
  • Por exemplo, remoteid:1234

Este é um exemplo de como identificar que uma notificação do sistema está relacionada a uma pessoa específica:

<toast hint-people="mailto:johndoe@mydomain.com">
    <visual lang="en-US">
        <binding template="ToastText01">
            <text>John Doe posted a comment.</text>
        </binding>
    </visual>
</toast>

A classe PinnedContactManager

PinnedContactManager é usado para gerenciar quais contatos são fixados na barra de tarefas. Essa classe permite fixar e desafixar contatos, determinar se um contato está fixado e determinar se a fixação em uma superfície específica é suportada pelo sistema em que seu aplicativo está sendo executado no momento.

Você pode recuperar o objeto PinnedContactManager usando o método GetDefault:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Fixando e desafixando contatos

Agora, você pode fixar e desafixar contatos usando o PinnedContactManager que você acabou de criar. Os métodos RequestPinContactAsync e RequestUnpinContactAsync fornecem ao usuário caixas de diálogo de confirmação, portanto, elas devem ser chamadas a partir do single-threaded apartment de aplicativo (ASTA ou interface do usuário).

async void PinContact (Contact contact)
{
    await pinnedContactManager.RequestPinContactAsync(contact,
                                                      PinnedContactSurface.Taskbar);
}

async void UnpinContact (Contact contact)
{
    await pinnedContactManager.RequestUnpinContactAsync(contact,
                                                        PinnedContactSurface.Taskbar);
}

Você também pode fixar vários contatos ao mesmo tempo:

async Task PinMultipleContacts(Contact[] contacts)
{
    await pinnedContactManager.RequestPinContactsAsync(
        contacts, PinnedContactSurface.Taskbar);
}

Observação:

Confira também

• Compartilhamento de Minhas Pessoas
• Notificações de Minhas Pessoas
• Amostra de integração Minhas Pessoas
• Amostra de cartões de contato
• Documentação da classe PinnedContactManager
• Conectar seu aplicativo a ações em um cartão de visita