Persone in Windows

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 le personae per diverse esperienze personali. Windows ora fornisce winUI di terze parti e altre app con l'identità del pacchetto con API per archiviare tutti i contatti.

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

Per iniziare, creare un account dati utente. Le app di terze parti devono essere utilizzate 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");

Quindi, aggiungi "com.microsoft.windows.system" all'elenco dei ExplicitReadAccessPackageFamilyNames 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 il UserDataAccount per archiviare 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.

Elimina il 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.
```
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.

Procedure consigliate per la classificazione

Per massimizzare la pertinenza dei contatti della tua app nella riga dei suggerimenti del pannello di condivisione, segui questi principi di ranking:

Ordina per data recente e frequenza

Calcolare la classificazione come combinazione di:

Recency: Quando l'utente ha interagito l'ultima volta con ciascun contatto
Frequenza: frequenza con cui l'utente interagisce con ogni contatto

Ad esempio, un contatto inviato ieri dall'utente potrebbe avere una classificazione 95, mentre un messaggio di contatto inviato 2 settimane fa potrebbe avere una classificazione 60.

// lastInteraction and interactionCount come from your app's own interaction
// telemetry. The Windows Contact class does not expose interaction history.
private int CalculateRank(DateTime lastInteraction, int interactionCount)
{
    TimeSpan daysSinceLastInteraction = DateTime.Now - lastInteraction;
    int frequencyScore = interactionCount * 10; // Max ~100
    int recencyScore = Math.Max(0, 100 - (daysSinceLastInteraction.Days * 3));

    return (recencyScore + frequencyScore) / 2;
}

Rimuovere i contatti non aggiornati

I contatti con cui l'utente non interagisce da oltre 30 giorni devono essere rimossi o retrocessi significativamente nel ranking. In questo modo i suggerimenti vengono aggiornati e pertinenti:

private async Task PruneStaleContactsAsync()
{
    var now = DateTime.Now;
    var staleCutoff = now.AddDays(-30);
    
    foreach (var contact in this.AllTrackedContacts)
    {
        if (contact.LastInteractionDate < staleCutoff)
        {
            // Remove the annotation or set rank to 0
            var annotation = await GetAnnotationForContactAsync(contact);
            if (annotation != null)
            {
                annotation.ProviderProperties["Rank"] = 0;
                await this.contactAnnotationList.TrySaveAnnotationAsync(annotation);
            }
        }
    }
}

Aggiornare regolarmente i ranghi

Pianificare gli aggiornamenti delle classificazioni in base a una cadenza appropriata per l'app: giornaliera per le app di messaggistica, settimanale per la posta elettronica o mensile per le app del calendario. Usare le attività in background, se necessario:

// Example: Update ranks when the app comes to foreground or on a timer
private async void UpdateRanksOnAppActivated()
{
    var topContacts = GetTopContactsByRecentActivity(50);
    await UpdateAnnotationRanksAsync(topContacts);
}

Aggiungi solo contatti esplicitamente specificati

L'app deve contribuire solo ai contatti che l'utente ha aggiunto o autorizzato in modo esplicito. Mai:

Caricare l'intera rubrica
Sincronizzazione automatica dei contatti senza consenso dell'utente
Condividi i contatti dalle directory aziendali senza autorizzazione esplicita

Chiedere l'autorizzazione prima di archiviare i contatti nel sistema Persone:

private async Task<bool> RequestContactStoreAccessAsync()
{
    // Requesting a writable ContactStore prompts the user for consent.
    // Your app must declare the contacts capability in its manifest.
    ContactStore store = await ContactManager.RequestStoreAsync(
        ContactStoreAccessType.AppContactsReadWrite);
    return store != null;
}

Rispettare le impostazioni di privacy degli utenti

Consenti agli utenti di:

Scegliere i contatti da condividere con Windows
Rifiutare esplicitamente l'integrazione di People
Eliminare i contatti da Windows in qualsiasi momento

// Provide a setting to disable sync
if (this.ShouldSyncContactsWithWindows)
{
    await SyncContactsAsync();
}
else
{
    // Clear contacts if the user disables sync
    await ClearWindowsContactsAsync();
}

Quando si classificano e si mantengono i contatti con le indicazioni precedenti, gli utenti visualizzeranno i contatti principali dell'app nella riga dei suggerimenti del foglio di condivisione Windows. Questo percorso supporta attualmente i contatti di Persone.

Per assicurarsi che i contatti vengano visualizzati:

Crea un UserDataAccount con DisplayName = "com.microsoft.peoplecontract"
Archiviare i contatti con i campi obbligatori (FirstName, RemoteId, DisplayPicture)
Creare un ContactAnnotationList oggetto con classificazioni
Imposta SupportedOperations = Share su ogni annotazione
Aggiorna regolarmente le classifiche in base alla frequenza e alla data più recente
Rimuovi i contatti obsoleti dopo più di 30 giorni

Per la guida completa all'integrazione del foglio di condivisione, vedi Condividere contenuto dall'app e Ricevere contenuto nella tua app .

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-23