Adicionando o suporte para Minhas Pessoas a um aplicativoAdding My People support to an application

Observação

A partir do Windows 10 de maio de 2019 atualização (versão 1903), as novas instalações do Windows 10 não mostrarão mais "pessoas na barra de tarefas" por padrão.As of the Windows 10 May 2019 Update (version 1903), new Windows 10 installations will no longer show ‘People in the taskbar’ by default. Os clientes podem habilitar o recurso clicando com o botão direito do mouse na barra de tarefas e pressionando "mostrar pessoas na barra de tarefas".Customers can enable the feature by right-clicking on the taskbar and pressing “Show People on the taskbar.” Os desenvolvedores são desencorajados de adicionar o suporte de minhas pessoas aos seus aplicativos e devem visitar o blog do Windows Developer para obter mais informações sobre como otimizar aplicativos para o Windows 10.Developers are discouraged from adding My People support to their applications, and should visit the Windows Developer Blog for more information about optimizing apps for Windows 10.

O recurso Minhas Pessoas permite que os usuários fixem contatos de um aplicativo diretamente à sua barra de tarefas, que cria um novo objeto de contato com o qual eles possam interagir de várias maneiras.The My People feature allows users to pin contacts from an application directly to their taskbar, which creates a new contact object that they can interact with in several ways. Este artigo mostra como você pode adicionar suporte para esse recurso, permitindo que os usuários fixem contatos diretamente de seu app.This article shows how you can add support for this feature, allowing users to pin contacts directly from your app. Quando os contatos são fixados, novos tipos de interação do usuário se tornam disponíveis, como compartilhamento e notificações do Minhas Pessoas.When contacts are pinned, new types of user interaction become available, such as My People sharing and notifications.

Chat do Minhas Pessoas

RequisitosRequirements

Visão geralOverview

Há três coisas que você precisa fazer para permitir que seu aplicativo use o recurso Minhas Pessoas:There are three things you need to do to enable your application to use the My People feature:

  1. Declare o suporte para o contrato de ativação shareTarget no manifesto do aplicativo.Declare support for the shareTarget activation contract in your application manifest.
  2. Anote os contatos com os quais os usuários podem compartilhar usando seu aplicativo.Annotate the contacts that the users can share to using your app.
  3. Dê suporte a várias instâncias do seu aplicativo em execução ao mesmo tempo.Support multiple instances of your application running at the same time. Os usuários devem poder interagir com a versão completa de seu aplicativo enquanto o usam em um painel de contato.Users must be able to interact with a full version of your application while using it in a contact panel. Eles podem até usá-lo em vários painéis de contato ao mesmo tempo.They may even use it in multiple contact panels at once. Para dar suporte a isso, seu aplicativo precisa ser capaz de executar várias exibições simultaneamente.To support this, your application needs to be able to run multiple views simultaneously. Para saber como fazer isso, consulte o artigo "Mostrar vários modos de exibição para um aplicativo".To learn how to do this, see the article "show multiple views for an app".

Feito isso, seu aplicativo será exibido no painel de contato para os contatos anotados.When you’ve done this, your application will appear in the contact panel for annotated contacts.

Declarando suporte para o contratoDeclaring support for the contract

Para declarar o suporte para o contrato do recurso Minhas Pessoas, abra seu aplicativo no Visual Studio.To declare support for the My People contract, open your application in Visual Studio. No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo Package.appxmanifest e selecione Abrir com.From the Solution Explorer, right click Package.appxmanifest and select Open With. No menu, selecione Editor de XML (texto)) e clique em OK.From the menu, select XML (Text) Editor) and click OK. Faça as seguintes alterações no manifesto:Make the following changes to the manifest:

AntesBefore

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

DepoisAfter

<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 essa adição, agora seu aplicativo pode ser iniciado por meio do contrato windows.ContactPanel, que permite que você interaja com os painéis de contato.With this addition, your application can now be launched through the windows.ContactPanel contract, which allows you to interact with contact panels.

Anotando contatosAnnotating contacts

Para permitir que os contatos do seu aplicativo apareçam na barra de tarefas por meio do painel Minhas Pessoas, você precisa anotá-los no repositório de contato do Windows.To allow contacts from your application to appear in the taskbar via the My People pane, you need to write them to the Windows contact store. Para saber como gravar contatos, consulte o exemplo de cartão de contato.To learn how to write contacts, see the Contact Card sample.

Seu aplicativo também deve escrever uma anotação para cada contato.Your application must also write an annotation to each contact. Anotações são dados do seu aplicativo que são associados a um contato.Annotations are pieces of data from your application that are associated with a contact. A anotação deve conter a classe ativável correspondente ao seu modo de exibição desejado no membro ProviderProperties e declarar suporte para a operação ContactProfile.The annotation must contain the activatable class corresponding to your desired view in its ProviderProperties member, and declare support for the ContactProfile operation.

Você pode anotar contatos a qualquer momento enquanto seu aplicativo estiver em execução, mas geralmente é necessário anotar os contatos assim que eles são adicionados ao repositório de contatos do Windows.You can annotate contacts at any point while your app is running, but generally you should annotate contacts as soon as they are added to the Windows contact store.

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 de Pacotes, seguido por '!'The “appId” is the Package Family Name, followed by ‘!’ e a ID da classe ativável.and the activatable class ID. Para localizar o Nome da Família de Pacotes, abra Package.appxmanifest usando o editor de padrão e procure na guia "Empacotamento". Aqui, o "Aplicativo" é a classe ativável correspondente ao modo de exibição do aplicativo.To find your Package Family Name, open Package.appxmanifest using the default editor, and look in the “Packaging” tab. Here, “App” is the activatable class corresponding to the application startup view.

Permitir que os contatos convidem novos usuários em potencialAllow contacts to invite new potential users

Por padrão, seu aplicativo só aparecerá no painel de contato para os contatos que você tiver anotado especificamente.By default, your application will only appear in the contact panel for contacts that you have specifically annotated. Isso é para evitar confusão com os contatos que não podem interagir por meio de seu app.This is to avoid confusion with contacts that can’t be interacted with through your app. Se você quiser que o aplicativo apareça para os contatos que ele não conhece (para convidar os usuários a adicionarem esse contato à conta deles, por exemplo), você poderá adicionar o seguinte ao seu manifesto:If you want your application to appear for contacts that your application doesn’t know about (to invite users to add that contact to their account, for instance), you can add the following to your manifest:

AntesBefore

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

DepoisAfter

<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 será exibido como uma opção disponível no painel de contato para todos os contatos que o usuário fixou.With this change, your application will appear as an available option in the contact panel for all contacts that the user has pinned. Quando seu aplicativo for ativado usando o contrato do painel de contato, verifique se o contato é aquele que seu aplicativo conhece.When your application is activated using the contact panel contract, you should check to see if the contact is one your application knows about. Caso contrário, você deverá mostrar a nova experiência do usuário do seu aplicativo.If not, you should show your app’s new user experience.

Painel de contato do recurso Minhas Pessoas

Suporte para aplicativos de emailSupport for email apps

Se você estiver escrevendo um aplicativo de email, não precisa anotar todos os contatos manualmente.If you are writing an email app, you don’t need to annotate every contact manually. Se você declarar o suporte para o painel de contato e para o protocolo mailto:, seu aplicativo aparecerá automaticamente para os usuários com um endereço de email.If you declare support for the contact pane and for the mailto: protocol, your application will automatically appear for users with an email address.

Execução no painel de contatoRunning in the contact panel

Agora que seu aplicativo aparece no painel de contato para alguns ou todos os usuários, você precisa processar a ativação com o contrato do painel de contato.Now that your application appears in the contact panel for some or all users, you need to handle activation with the contact panel contract.

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 esse contrato, ele receberá um objeto ContactPanelActivatedEventArgs.When your application is activated with this contract, it will receive a ContactPanelActivatedEventArgs object. Contém a ID do contato com o qual seu aplicativo está tentando interagir na inicialização e um objeto ContactPanel.This contains the ID of the Contact that your application is trying to interact with on launch, and a ContactPanel object. Você deve manter uma referência a esse objeto ContactPanel, que permitirá a interação com o painel.You should keep a reference to this ContactPanel object, which will allow you to interact with the panel.

O objeto ContactPanel tem dois eventos que seu aplicativo deve escutar:The ContactPanel object has two events your application should listen for:

  • O evento LaunchFullAppRequested é enviado quando o usuário chama o elemento de interface que solicita que seu aplicativo completo seja iniciado na própria janela.The LaunchFullAppRequested event is sent when the user has invoked the UI element that requests that your full application be launched in its own window. Seu aplicativo é responsável pela própria inicializando, passando todo o contexto necessário.Your application is responsible for launching itself, passing along all necessary context. Você é livre para fazer isso da maneira que quiser (por exemplo, por meio de inicialização de protocolo).You are free to do this however you’d like (for example, via protocol launch).
  • O evento Closing é enviado quando seu aplicativo está prestes a ser fechado, permitindo que você salve qualquer contexto.The Closing event is sent when your application is about to be closed, allowing you to save any context.

O objeto ContactPanel também permite que você defina a cor de fundo do cabeçalho do painel de contato (se não for definida, o padrão será o tema do sistema) e feche o painel de contato programaticamente.The ContactPanel object also allows you to set the background color of the contact panel header (if not set, it will default to the system theme) and to programmatically close the contact panel.

Suporte a selos de notificaçãoSupporting notification badging

Se você deseja fixar contatos na barra de tarefas para marcação quando chegam novas notificações do aplicativo relacionados à pessoa, você deve incluir o parâmetro hint-people nas notificações do sistema e Notificações expressivas de Minhas Pessoas.If you want contacts pinned to the taskbar to be badged when new notifications arrive from your app that are related to that person, then you must include the hint-people parameter in your toast notifications and expressive My People notifications.

Selos de notificações de pessoas

Para marcar um contato, o nó de nível superior da notificação do sistema deve incluir o parâmetro hint-people para indicar o envio ou o contato relacionado.To badge a contact, the top-level toast node must include the hint-people parameter to indicate the sending or related contact. Esse parâmetro pode ter qualquer um dos seguintes valores:This parameter can have any of the following values:

  • Endereço de emailEmail address
    • Por ex.:E.g. mailto:johndoe@mydomain.commailto:johndoe@mydomain.com
  • Número de telefoneTelephone number
    • Por ex.:E.g. tel:888-888-8888tel:888-888-8888
  • ID remotaRemote ID
    • Por ex.:E.g. remoteid:1234remoteid:1234

Aqui está um exemplo de como identificar uma notificação do sistema está relacionado a uma determinada pessoa:Here is an example of how to identify a toast notification is related to a specific person:

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

Observação

Se seu app utiliza as APIs de ContactStore e utiliza a propriedade StoredContact.RemoteId para associar contatos armazenados no computador com contatos armazenados remotamente, é fundamental que o valor para a propriedade RemoteId seja estável e exclusivo.If your app uses the ContactStore APIs and uses the StoredContact.RemoteId property to link contacts stored on the PC with contacts stored remotely, it is essential that the value for the RemoteId property is both stable and unique. Isso significa que a ID remota deve identificar consistentemente uma única conta de usuário e deve manter uma única marca para garantir que ele não entre em conflito com as IDs remotas de outros contatos no computador, incluindo contatos que são de propriedade de outros aplicativos.This means that the remote ID must consistently identify a single user account and should contain a unique tag to guarantee that it does not conflict with the remote IDs of other contacts on the PC, including contacts that are owned by other apps. Se as IDs remotas usadas por seu app não forem com certeza estáveis e exclusivas, você pode usar a classe RemoteIdHelper mostrada mais adiante neste tópico para adicionar uma marca exclusiva a todas as IDs remotas antes de você adicioná-las ao sistema.If the remote IDs used by your app are not guaranteed to be stable and unique, you can use the RemoteIdHelper class shown later in this topic in order to add a unique tag to all of your remote IDs before you add them to the system. Ou você pode optar por não usar a propriedade RemoteId e criar uma propriedade estendida personalizada na qual armazenar as IDs remotas de seus contatos.Or you can choose to not use the RemoteId property at all and instead you create a custom extended property in which to store remote IDs for your contacts.

A classe PinnedContactManagerThe PinnedContactManager class

O PinnedContactManager é usado para gerenciar quais contatos são fixados à barra de tarefas.The PinnedContactManager is used to manage which contacts are pinned to the taskbar. Essa classe permite que você fixe e desafixe contatos, determine se um contato está fixado e se há suporte para fixação em uma superfície específica no sistema em que seu aplicativo está sendo executado.This class lets you pin and unpin contacts, determine whether a contact is pinned, and determine if pinning on a particular surface is supported by the system your application is currently running on.

Você pode recuperar o objeto PinnedContactManager usando o método GetDefault:You can retrieve the PinnedContactManager object using the GetDefault method:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Fixando e desafixando contatosPinning and unpinning contacts

Agora você pode fixar e desafixar contatos usando o PinnedContactManager que acabou de criar.You can now pin and unpin contacts using the PinnedContactManager you just created. Os métodos RequestPinContactAsync e RequestUnpinContactAsync fornecem ao usuário caixas de diálogo de confirmação, para que sejam chamadas pelo thread do ASTA (Application Single-Threaded Apartment) ou da interface do usuário.The RequestPinContactAsync and RequestUnpinContactAsync methods provide the user with confirmation dialogs, so they must be called from your Application Single-Threaded Apartment (ASTA, or UI) thread.

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:You can also pin multiple contacts at the same time:

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

Observação

Atualmente, não há uma operação em lote para desafixar contatos.There is currently no batch operation for unpinning contacts.

Observação:Note:

Veja tambémSee also