Ajout de la prise en charge de Mes Contacts à une application

  • Article

Important

La fonction Mes contacts n'est plus prise en charge dans les versions de Windows 11 et Windows 10 sur lesquelles Ko5034203 est appliqué.

Remarque

À compter de la Mise à jour de mai 2019 de Windows 10 (version 1903), les nouvelles installations de Windows 10 n’affichent plus « Contacts dans la barre des tâches » par défaut. Les clients peuvent activer la fonctionnalité en cliquant avec le bouton droit sur la barre des tâches et en appuyant sur « Afficher Contacts dans la barre des tâches ». Il est déconseillé pour les développeurs d’ajouter la prise en charge de Mes Contacts à leurs applications et doivent consulter le Blog des développeurs Windows pour plus d’informations sur l’optimisation des applications pour Windows 10.

La fonctionnalité Mes contacts permet aux utilisateurs d’épingler les contacts d’une application directement à leur barre des tâches, créant ainsi un objet Contacts avec lequel ils peuvent interagir de plusieurs façons. Cet article explique comment ajouter la prise en charge de cette fonctionnalité permettant aux utilisateurs d’épingler des contacts directement à partir de votre application. Lorsque les contacts sont épinglés, de nouveaux types d’interaction utilisateur deviennent disponibles, tels que Partage de Mes Contacts et Notifications.

My people chat

Spécifications

Vue d’ensemble

Vous devez effectuer trois opérations pour permettre à votre application d’utiliser la fonctionnalité Mes contacts :

  1. Déclarez la prise en charge du contrat d’activation shareTarget dans le manifeste de votre application.
  2. Annotez les contacts que les utilisateurs peuvent partager à l’aide de votre application.
  3. Activez la prise en charge simultanée de plusieurs instances de votre application. Les utilisateurs doivent pouvoir interagir avec une version complète de votre application tout en l’utilisant dans un panneau de contacts. Ils peuvent même l’utiliser dans plusieurs panneaux de contacts à la fois. Pour ce faire, votre application doit pouvoir exécuter plusieurs affichages simultanément. Pour savoir comment procéder, consultez l’article « Afficher plusieurs vues d'une application ».

Une fois cette opération effectuée, votre application s’affiche dans le panneau de contacts pour les contacts annotés.

Déclaration de la prise en charge du contrat

Pour déclarer la prise en charge du contrat Mes contacts, ouvrez votre application dans Visual Studio. Depuis l’Explorateur de solutions, cliquez avec le bouton droit sur le fichier Package.appxmanifest et sélectionnez Ouvrir avec. Dans le menu, sélectionnez Éditeur XML (Texte) et cliquez sur OK. Appliquez les modifications suivantes au manifeste :

Avant le

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

Après

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

Avec cet ajout, votre application peut maintenant être lancée via le contrat windows.ContactPanel, qui vous permet d’interagir avec les panneaux de contacts.

Annotation des contacts

Pour permettre aux contacts de votre application d’apparaître dans la barre des tâches via le volet Mes contacts, vous devez les écrire dans le magasin de contacts Windows. Pour savoir comment écrire des contacts, consultez l’exemple de carte de visite.

Votre application doit également écrire une annotation pour chaque contact. Les annotations sont des éléments de données de votre application associés à un contact. L’annotation doit contenir la classe activable correspondant à l’affichage souhaité dans son membre ProviderProperties et déclarer la prise en charge de l’opération ContactProfile.

Vous pouvez annoter des contacts à tout moment pendant l’exécution de votre application, mais en règle générale, vous devez les annoter dès qu’ils sont ajoutés au magasin de contacts 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));
}

« appId » est le nom de famille du package, suivi de « ! » et l’ID de classe activable. Pour rechercher le nom de famille de votre package, ouvrez Package.appxmanifest à l’aide de l’éditeur par défaut, puis recherchez l’onglet « Packaging ». Là, « Application » est la classe activable correspondant à l'affichage au démarrage de l’application.

Autoriser les contacts à inviter de nouveaux utilisateurs potentiels

Par défaut, votre application apparaît uniquement dans le panneau de contacts pour les contacts que vous avez spécifiquement annotés. Cela permet d’éviter toute confusion avec les contacts avec lesquels il n'est pas possible d'interagir via votre application. Si vous souhaitez que votre application apparaisse pour les contacts qu'elle ne connaît pas (pour inviter les utilisateurs à ajouter ce contact à leur compte, par exemple), vous pouvez ajouter ce qui suit à votre manifeste :

Avant le

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

Après

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

Avec cette modification, votre application apparaît en tant qu’option disponible dans le panneau de contacts pour tous les contacts épinglés par l’utilisateur. Lorsque votre application est activée à l’aide du contrat du panneau de contacts, vous devez vérifier que le contact fait partie des contacts que votre application connaît. Si ce n’est pas le cas, vous devez afficher la nouvelle expérience utilisateur de votre application.

My People contact panel

Prise en charge des applications de messagerie

Si vous écrivez une application de messagerie, vous n’avez pas besoin d’annoter manuellement chaque contact. Si vous déclarez la prise en charge du panneau de contacts et du protocole mailto:, votre application s’affiche automatiquement pour les utilisateurs possédant une adresse e-mail.

Exécution dans le panneau de contacts

Maintenant que votre application apparaît dans le panneau de contacts pour certains ou tous les utilisateurs, vous devez gérer l’activation avec le contrat du panneau de contacts.

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();
    }
}

Lorsque votre application est activée avec ce contrat, elle reçoit un objet ContactPanelActivatedEventArgs. Celui-ci contient l’ID du contact avec lequel votre application tente d’interagir lors du lancement, ainsi qu'un objet ContactPanel. Vous devez conserver une référence à cet objet ContactPanel, laquelle vous permettra d’interagir avec le panneau.

L’objet ContactPanel comporte deux événements que votre application doit écouter :

  • L’événement LaunchFullAppRequested est envoyé lorsque l’utilisateur a appelé l’élément d’interface utilisateur qui demande que l'intégralité de votre application soit lancée dans sa propre fenêtre. Votre application est chargée de se lancer elle-même, en transmettant tout le contexte nécessaire. Vous êtes toutefois libre de le faire comme vous le souhaitez (par exemple, via le lancement du protocole).
  • L’événement de fermeture est envoyé lorsque votre application est sur le point d’être fermée, ce qui vous permet d’enregistrer n’importe quel contexte.

L’objet ContactPanel vous permet également de définir la couleur d’arrière-plan de l’en-tête du panneau de contacts (si elle n’est pas définie, elle est réglée par défaut sur le thème système) et de fermer par programme le panneau de contacts.

Prise en charge du badgeage de notification

Si vous souhaitez que les contacts épinglés à la barre des tâches soient badgés lorsque de nouvelles notifications, associées à ce contact, arrivent de votre application, alors vous devez inclure le paramètre hint-people dans vos notifications en incrustation et notifications Mes contacts descriptives.

People notification badging

Pour badger un contact, le nœud d'incrustation de niveau supérieur doit inclure le paramètre hint-people pour indiquer l’envoi ou le contact associé. Ce paramètre peut prendre l'une ou l'autre des valeurs suivantes :

Voici un exemple d’identification d’une notification en incrustation liée à un contact spécifique :

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

Remarque

Si votre application utilise les API ContactStore et la propriété StoredContact.RemoteId pour lier des contacts stockés sur le PC avec des contacts stockés à distance, il est essentiel que la valeur de la propriété RemoteId soit stable et unique. Cela signifie que l’ID distant doit identifier de manière cohérente un seul compte d’utilisateur et doit contenir une balise unique pour garantir l'absence de conflit avec les ID distants d’autres contacts sur le PC, y compris les contacts appartenant à d’autres applications. Si les ID distants utilisés par votre application ne sont pas garantis comme étant stables et uniques, vous pouvez utiliser la classe RemoteIdHelper présentée plus loin dans cette rubrique pour ajouter une balise unique à tous vos ID distants avant de les ajouter au système. Vous pouvez également choisir de ne pas utiliser la propriété RemoteId du tout et de créer une propriété étendue personnalisée dans laquelle stocker des ID distants pour vos contacts.

Classe PinnedContactManager

La classe PinnedContactManager est utilisée pour gérer les contacts qui sont épinglés à la barre des tâches. Elle vous permet d’épingler et de désépiner les contacts, de déterminer si un contact est épinglé et de déterminer si l’épinglage sur une surface particulière est prise en charge par le système sur lequel votre application s’exécute actuellement.

Vous pouvez récupérer l’objet PinnedContactManager à l’aide de la méthode GetDefault :

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Épinglage et désépinglage des contacts

Vous pouvez désormais épingler et désépingler des contacts à l’aide de la classe PinnedContactManager que vous venez de créer. Les méthodes RequestPinContactAsync et RequestUnpinContactAsync fournissent à l’utilisateur des boîtes de dialogue de confirmation. Elles doivent donc être appelées à partir de votre thread ASTA (Application Single-Threaded Apartment, ou interface utilisateur).

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

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

Vous pouvez également épingler plusieurs contacts en même temps :

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

Remarque

Il n’existe actuellement aucune opération de désépinglage des contacts par lots.

Remarque :

Voir aussi