Agregar compatibilidad con Mis allegados a una aplicaciónAdding My People support to an application

Nota

A partir de la actualización de Windows 10 de mayo de 2019 (versión 1903), las instalaciones nuevas de Windows 10 ya no mostrarán "personas en la barra de tareas" de forma predeterminada.As of the Windows 10 May 2019 Update (version 1903), new Windows 10 installations will no longer show ‘People in the taskbar’ by default. Para habilitar la característica, los clientes pueden hacer clic con el botón derecho en la barra de tareas y presionar "Mostrar personas en la barra de tareas".Customers can enable the feature by right-clicking on the taskbar and pressing “Show People on the taskbar.” No se recomienda que los desarrolladores agreguen soporte técnico a sus aplicaciones y visite el blog para desarrolladores de Windows para obtener más información sobre la optimización de aplicaciones para 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.

La característica mis personas permite a los usuarios anclar contactos de una aplicación directamente a su barra de tareas, lo que crea un nuevo objeto de contacto con el que pueden interactuar de varias maneras.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. En este artículo se muestra cómo puede Agregar compatibilidad con esta característica, lo que permite a los usuarios anclar contactos directamente desde su aplicación.This article shows how you can add support for this feature, allowing users to pin contacts directly from your app. Cuando se anclan los contactos, se ponen a su disposición nuevos tipos de interacción con el usuario, como el uso compartido y las notificacionesde mis personas.When contacts are pinned, new types of user interaction become available, such as My People sharing and notifications.

Chat mis personas

RequisitosRequirements

Información generalOverview

Hay tres cosas que debe hacer para permitir que la aplicación use la característica mis personas:There are three things you need to do to enable your application to use the My People feature:

  1. Declare la compatibilidad con el contrato de activación shareTarget en el manifiesto de aplicación.Declare support for the shareTarget activation contract in your application manifest.
  2. Anote los contactos que los usuarios pueden compartir para usar la aplicación.Annotate the contacts that the users can share to using your app.
  3. Compatibilidad con varias instancias de la aplicación que se ejecutan al mismo tiempo.Support multiple instances of your application running at the same time. Los usuarios deben poder interactuar con una versión completa de la aplicación mientras la usan en un panel de contactos.Users must be able to interact with a full version of your application while using it in a contact panel. Incluso pueden usarlo en varios paneles de contacto a la vez.They may even use it in multiple contact panels at once. Para admitir esto, la aplicación debe ser capaz de ejecutar varias vistas simultáneamente.To support this, your application needs to be able to run multiple views simultaneously. Para obtener información sobre cómo hacerlo, vea el artículo "Mostrar varias vistas de una aplicación".To learn how to do this, see the article "show multiple views for an app".

Cuando lo haya hecho, la aplicación aparecerá en el panel de contactos para los contactos anotados.When you’ve done this, your application will appear in the contact panel for annotated contacts.

Declarar la compatibilidad del contratoDeclaring support for the contract

Para declarar la compatibilidad con el contrato mis personas, abra la aplicación en Visual Studio.To declare support for the My People contract, open your application in Visual Studio. En el Explorador de soluciones, haga clic con el botón derecho en Package. Appxmanifest y seleccione abrir con.From the Solution Explorer, right click Package.appxmanifest and select Open With. En el menú, seleccione Editor XML (texto)) y haga clic en Aceptar.From the menu, select XML (Text) Editor) and click OK. Realice los siguientes cambios en el manifiesto: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>

DespuésAfter

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

Con esta adición, la aplicación ahora se puede iniciar a través de **Windows. ** Contrato de ContactPanel, que permite interactuar con los paneles de contacto.With this addition, your application can now be launched through the windows.ContactPanel contract, which allows you to interact with contact panels.

Anotar contactosAnnotating contacts

Para permitir que los contactos de la aplicación aparezcan en la barra de tareas mediante el panel mis personas, debe escribirlos en el almacén de contactos de 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 obtener información sobre cómo escribir contactos, vea el ejemplo de tarjeta Contact.To learn how to write contacts, see the Contact Card sample.

La aplicación también debe escribir una anotación para cada contacto.Your application must also write an annotation to each contact. Las anotaciones son fragmentos de datos de la aplicación que están asociados a un contacto.Annotations are pieces of data from your application that are associated with a contact. La anotación debe contener la clase activable correspondiente a la vista deseada en su miembro ProviderProperties y declarar la compatibilidad con la operación ContactProfile .The annotation must contain the activatable class corresponding to your desired view in its ProviderProperties member, and declare support for the ContactProfile operation.

Puede anotar contactos en cualquier momento mientras la aplicación se está ejecutando, pero generalmente debe anotar los contactos en cuanto se agreguen al almacén de contactos de 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));
}

"AppId" es el nombre de familia del paquete, seguido de "!".The “appId” is the Package Family Name, followed by ‘!’ y el identificador de clase activable.and the activatable class ID. Para buscar el nombre de familia del paquete, Abra Package. appxmanifest con el editor predeterminado y mire en la pestaña "empaquetado". Aquí, "app" es la clase activable correspondiente a la vista de inicio de la aplicación.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 a los contactos invitar a nuevos usuarios potencialesAllow contacts to invite new potential users

De forma predeterminada, la aplicación solo aparecerá en el panel de contactos para los contactos que haya anotado específicamente.By default, your application will only appear in the contact panel for contacts that you have specifically annotated. Esto es para evitar la confusión con los contactos con los que no se puede interactuar a través de la aplicación.This is to avoid confusion with contacts that can’t be interacted with through your app. Si desea que la aplicación aparezca para los contactos que la aplicación no conoce (para invitar a los usuarios a agregar ese contacto a su cuenta, por ejemplo), puede agregar lo siguiente al manifiesto: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>

DespuésAfter

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

Con este cambio, la aplicación aparecerá como una opción disponible en el panel de contacto para todos los contactos que el usuario haya anclado.With this change, your application will appear as an available option in the contact panel for all contacts that the user has pinned. Cuando la aplicación se activa mediante el contrato del panel de contactos, debe comprobar si el contacto es uno de los que conoce su aplicación.When your application is activated using the contact panel contract, you should check to see if the contact is one your application knows about. Si no es así, debe mostrar la nueva experiencia de usuario de la aplicación.If not, you should show your app’s new user experience.

Panel de contactos Mis allegados

Compatibilidad con aplicaciones de correo electrónicoSupport for email apps

Si está escribiendo una aplicación de correo electrónico, no es necesario anotar cada contacto manualmente.If you are writing an email app, you don’t need to annotate every contact manually. Si declara la compatibilidad con el panel contacto y para el protocolo mailto:, la aplicación aparecerá automáticamente para los usuarios con una dirección de correo electrónico.If you declare support for the contact pane and for the mailto: protocol, your application will automatically appear for users with an email address.

Ejecución en el panel de contactosRunning in the contact panel

Ahora que la aplicación aparece en el panel de contactos de algunos o de todos los usuarios, debe controlar la activación con el contrato del panel de contactos.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();
    }
}

Cuando la aplicación se active con este contrato, recibirá un objeto ContactPanelActivatedEventArgs.When your application is activated with this contract, it will receive a ContactPanelActivatedEventArgs object. Contiene el identificador del contacto con el que la aplicación está intentando interactuar en el inicio y un objeto ContactPanel .This contains the ID of the Contact that your application is trying to interact with on launch, and a ContactPanel object. Debe mantener una referencia a este objeto ContactPanel, que le permitirá interactuar con el panel.You should keep a reference to this ContactPanel object, which will allow you to interact with the panel.

El objeto ContactPanel tiene dos eventos para los que la aplicación debe escuchar:The ContactPanel object has two events your application should listen for:

  • El evento LaunchFullAppRequested se envía cuando el usuario ha invocado el elemento de la interfaz de usuario que solicita que se inicie la aplicación completa en su propia ventana.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. La aplicación es responsable de iniciarse, pasando todo el contexto necesario.Your application is responsible for launching itself, passing along all necessary context. Puede hacerlo de forma gratuita si lo desea (por ejemplo, mediante el inicio de protocolo).You are free to do this however you’d like (for example, via protocol launch).
  • El evento de cierre se envía cuando la aplicación está a punto de cerrarse, lo que le permite guardar cualquier contexto.The Closing event is sent when your application is about to be closed, allowing you to save any context.

El objeto ContactPanel también le permite establecer el color de fondo del encabezado del panel de contacto (si no se establece, el valor predeterminado será el tema del sistema) y cerrar mediante programación el panel contacto.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.

Compatibilidad con distintivos de notificaciónSupporting notification badging

Si desea que los contactos anclados a la barra de tareas se contengan en el distintivo cuando lleguen nuevas notificaciones de la aplicación que están relacionadas con esa persona, debe incluir el parámetro Hint-People en las notificaciones del sistema y las notificaciones expresivas de mis personas.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.

Distintivos de notificación de personas

Para notificar a un contacto, el nodo notificador de nivel superior debe incluir el parámetro Hint-People para indicar el envío o el contacto relacionado.To badge a contact, the top-level toast node must include the hint-people parameter to indicate the sending or related contact. Este parámetro puede tener cualquiera de los siguientes valores:This parameter can have any of the following values:

  • Dirección de correo electrónicoEmail address
    • Por ejemplo,E.g. mailto:johndoe@mydomain.commailto:johndoe@mydomain.com
  • Número de teléfonoTelephone number
    • Por ejemplo,E.g. Tel: 888-888-8888tel:888-888-8888
  • Id. remotoRemote ID
    • Por ejemplo,E.g. remoteid: 1234remoteid:1234

Este es un ejemplo de cómo identificar una notificación del sistema relacionada con una persona específica: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>

Nota

Si la aplicación usa las API de ContactStore y usa la propiedad StoredContact. RemoteId para vincular contactos almacenados en el equipo con contactos almacenados de forma remota, es fundamental que el valor de la propiedad RemoteId sea estable y único.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. Esto significa que el identificador remoto debe identificar de forma coherente una sola cuenta de usuario y debe contener una etiqueta única para garantizar que no entra en conflicto con los identificadores remotos de otros contactos en el equipo, incluidos los contactos que son propiedad de otras aplicaciones.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. Si no se garantiza que los identificadores remotos usados por la aplicación sean stable y Unique, puede usar la clase RemoteIdHelper que se muestra más adelante en este tema para agregar una etiqueta única a todos los identificadores remotos antes de agregarlos al 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. O bien, puede optar por no usar la propiedad RemoteId en absoluto y, en su lugar, crear una propiedad extendida personalizada en la que almacenar los identificadores remotos para sus contactos.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.

La clase PinnedContactManagerThe PinnedContactManager class

El PinnedContactManager se usa para administrar los contactos que se anclan a la barra de tareas.The PinnedContactManager is used to manage which contacts are pinned to the taskbar. Esta clase le permite anclar y desanclar contactos, determinar si un contacto está anclado y determinar si el anclaje en una superficie determinada es compatible con el sistema en el que se está ejecutando actualmente la aplicación.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.

Puede recuperar el objeto PinnedContactManager mediante el método GetDefault :You can retrieve the PinnedContactManager object using the GetDefault method:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Anclar y desanclar contactosPinning and unpinning contacts

Ahora puede anclar y desanclar contactos con el PinnedContactManager que acaba de crear.You can now pin and unpin contacts using the PinnedContactManager you just created. Los métodos RequestPinContactAsync y RequestUnpinContactAsync proporcionan al usuario cuadros de diálogo de confirmación, por lo que deben llamarse desde el subproceso de la aplicación de contenedor uniproceso (asta o IU).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);
}

También puede anclar varios contactos a la vez:You can also pin multiple contacts at the same time:

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

Nota

Actualmente no hay ninguna operación por lotes para desanclar contactos.There is currently no batch operation for unpinning contacts.

Nota:Note:

Vea tambiénSee also