API Persone tra dispositivi

Articolo
18/06/2024

Windows è una piattaforma ideale per le app di terze parti per integrare i contatti principali delle persone. Questa integrazione consente agli utenti di interagire con gli utenti per diverse esperienze di persone. Windows offre ora app WinUI 3, UWP e altre app di terze parti con l'identità del pacchetto con API per archiviare tutti i contatti.

Importante

Alcune informazioni riguardano un prodotto in versione preliminare che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Nota

Le app possono provare questa funzionalità non appena viene rilasciata al Programma Windows Insider (Canale Beta) nelle impostazioni di Windows Update (vedere Introduzione al Programma Windows Insider per altre informazioni).

Una volta che le tue app archivia i loro contatti in Windows, gli utenti potranno visualizzare questi suggerimenti di contatto nel pannello Condividi in Windows per condividere facilmente con i loro contatti principali. Per altre informazioni sul pannello Condividi, vedere Come condividere i file in Esplora file in Windows.

Creazione di un userDataAccount per il contratto People

Per iniziare, creare un account dati utente. Le app di terze parti sono necessarie per creare un UserDataAccount con UserDisplayName come "com.microsoft.peoplecontract".

UserDataAccountStore udas =
    await UserDataAccountManager.RequestStoreAsync(UserDataAccountStoreAccessType.AppAccountsReadWrite);
UserDataAccount uda = await udas.CreateAccountAsync("com.microsoft.peoplecontract");

"com.microsoft.windows.system" Aggiungere quindi all'elenco explictReadAccessPackageFamilyNames per l'account. In questo modo verrà fornito l'accesso limitato dei contatti di terze parti alle esperienze di Windows.

uda.ExplictReadAccessPackageFamilyNames.Add("com.microsoft.windows.system");
await uda.SaveAsync();

Archiviazione dei contatti

Il primo passaggio nell'archiviazione dei contatti consiste nel creare un elenco contatti. A tale scopo, le app di terze parti devono creare il nuovo elenco contatti per un UserDataAccount oggetto in Windows ContactStore. Le app possono scegliere di mantenere il tipo di accesso predefinito OtherAppReadAccess per l'elenco contatti, impostandolo su None impedisce ad altre app di avere accesso a questi contatti. Per l'elenco completo dei tipi di accesso disponibili, vedere l'enumerazione ContactListOtherAppReadAccess .

ContactStore store = await ContactManager.RequestStoreAsync(ContactStoreAccessType.AppContactsReadWrite);
this.contactList = await store.CreateContactListAsync(contactListsName, uda.Id);
contactList.OtherAppReadAccess = ContactListOtherAppReadAccess.None;
await contactList.SaveAsync();

Durante l'archiviazione di un contatto, le app di terze parti devono includere tutte le informazioni rilevanti necessarie per consentire alle esperienze di Windows di attivare un contatto.

Quando si archivia un contatto, sono necessari i campi seguenti:

FirstName
RemoteId
DisplayPicture

I campi seguenti sono facoltativi:

LastName
Phones
Emails

Questo frammento di codice illustra come archiviare un contatto:

foreach (var appContact in AppContacts)
{
  var cont = new Contact
  {
    FirstName = appContact.FirstName,
    LastName = appContact.LastName,
    RemoteId = appContact.Id,
    SourceDisplayPicture = RandomAccessStreamReference.CreateFromUri(new Uri(appContact.ProfilePicPath)),
    Phones = { new ContactPhone { Number = appContact.Phone } }
  };

  await this.contactList.SaveContactAsync(cont);
}

Nota

L'oggetto DisplayName per il contatto viene costruito utilizzando FirstName e LastName. Se il cognome non viene specificato, DisplayName sarà identico alla stringa specificata per il nome.

Archiviazione delle classificazioni per i contatti

È possibile creare un elenco di annotazioni per archiviare UserDataAccount le classificazioni dei contatti. Le app possono archiviare le classificazioni per i contatti principali aggiungendo annotazioni ai contatti. Queste annotazioni vengono archiviate come parte di un elenco di annotazioni nell'archivio contatti.

ContactAnnotationStore annotationStore = await
    ContactManager.RequestAnnotationStoreAsync(ContactAnnotationStoreAccessType.AppAnnotationsReadWrite);
this.contactAnnotationList = await annotationStore.CreateAnnotationListAsync(uda.Id);

È possibile archiviare le classificazioni per i contatti principali usando le annotazioni sui contatti. Le classificazioni vengono archiviate come parte di ProviderProperties in un'annotazione del contatto. Oltre alla classificazione, le app devono impostare SupportedOperations su un'annotazione del contatto come Share.

foreach (var appContact in topAppContacts)
{
  Contact contact = await list.GetContactFromRemoteIdAsync(topAppContact.RemoteID);
  var annotation = new ContactAnnotation
  {
    ContactId = contact.Id,
    SupportedOperations = ContactAnnotationOperations.Share
  };
  annotation.ProviderProperties.Add("Rank", rank);
  await annotationsLst.TrySaveAnnotationAsync(annotation);
}

Aggiornamento delle classificazioni dei contatti

È a discrezione delle app quando aggiornare i ranghi dei contatti archiviati in Windows. Windows consiglia di aggiornare regolarmente gli elenchi classificati per offrire un'esperienza utente ottimale. Ogni volta che è necessario aggiornare un elenco classificato, è necessario seguire diversi passaggi.

Eliminare ContactAnnotationList.

Dopo che l'app ha un elenco aggiornato dei contatti principali, è possibile eliminare l'elenco di annotazioni e creare un nuovo elenco di annotazioni con annotazioni aggiornate per i contatti principali.

C#
```
await this.contactAnnotationList.DeleteAsync();
```
Creare un nuovo ContactAnnotationList. Seguire la procedura descritta nella sezione Archiviazione delle classificazioni per i contatti per creare un nuovo elenco di annotazioni e archiviare le classificazioni per i contatti principali.

Condividi tramite