Personen op Windows

Windows is een ideaal platform voor apps van derden om hun belangrijkste contactpersonen te integreren. Met deze integratie kunnen gebruikers communiceren met de persona's voor verschillende gebruikerservaringen. Windows biedt nu WinUI van derden en andere apps met pakketidentiteit met API's om al hun contactpersonen op te slaan.

Zodra uw apps hun contactpersonen opslaan in Windows, kunnen gebruikers deze suggesties voor contactpersonen zien in het deelvenster Delen in Windows om naadloos te delen met hun belangrijkste contactpersonen. Zie Bestanden delen in Verkenner op Windows voor meer informatie over het Deel paneel.

Een UserDataAccount voor het People Contract maken

Begin met het maken van een gebruikersgegevensaccount. Apps van derden zijn vereist voor het maken van een UserDataAccount met UserDisplayName als "com.microsoft.peoplecontract".

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

Voeg "com.microsoft.windows.system" vervolgens toe aan de lijst met ExplicitReadAccessPackageFamilyNames voor het account. Dit biedt beperkte toegang tot contactpersonen van derden voor Windows-ervaringen.

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

Contactpersonen opslaan

De eerste stap bij het opslaan van contactpersonen is het maken van een lijst met contactpersonen. Hiervoor moeten apps van derden de nieuwe lijst met contactpersonen maken voor een UserDataAccount in de Windows ContactStore. Apps kunnen ervoor kiezen om het standaardtoegangstype OtherAppReadAccess voor de lijst met contactpersonen te behouden, terwijl het None zo wordt ingesteld dat andere apps geen toegang hebben tot deze contactpersonen. Zie de opsomming ContactListOtherAppReadAccess voor de volledige lijst met beschikbare toegangstypen.

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

Tijdens het opslaan van een contactpersoon moeten apps van derden alle relevante informatie bevatten die vereist is voor Windows-ervaringen om een contactpersoon te activeren.

De volgende velden zijn vereist bij het opslaan van een contactpersoon:

• FirstName
• RemoteId
• DisplayPicture

De volgende velden zijn optioneel:

• LastName
• Phones
• Emails

Dit codefragment laat zien hoe u een contactpersoon opslaat:

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

Rangschikkingen opslaan voor contactpersonen

U kunt een aantekeningslijst maken voor het UserDataAccount om rangschikkingen voor uw contactpersonen te beheren. Apps kunnen rangschikkingen opslaan voor hun belangrijkste contactpersonen door aantekeningen toe te voegen aan de contactpersonen. Deze aantekeningen worden opgeslagen als onderdeel van een annotatielijst in de contactenopslag.

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

U kunt rangschikkingen opslaan voor uw belangrijkste contactpersonen door de aantekeningen op contactpersonen te gebruiken. Rangschikkingen worden opgeslagen als onderdeel van ProviderProperties op een contactpersoonaantekening. Naast rang moeten apps de SupportedOperations instellen op een aantekening van een contactpersoon als 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);
}

Contactrangschikkingen bijwerken

Het is naar eigen goeddunken van apps wanneer de rangschikkingen van de contactpersonen die zijn opgeslagen in Windows moeten worden bijgewerkt. Windows raadt aan dat gerangschikte lijsten regelmatig worden bijgewerkt om de beste gebruikerservaring te bieden. Wanneer u een gerangschikte lijst moet bijwerken, moet u verschillende stappen uitvoeren.

1. Verwijder de ContactAnnotationList.

   Zodra de app een bijgewerkte lijst met belangrijkste contactpersonen heeft, kan de lijst met aantekeningen worden verwijderd en kan een nieuwe lijst met aantekeningen met bijgewerkte aantekeningen voor de belangrijkste contactpersonen worden gemaakt.

   await this.contactAnnotationList.DeleteAsync();
   

2. Maak een nieuwe ContactAnnotationList. Volg de stappen in de sectie Contactpersonen opslaan om een nieuwe lijst met aantekeningen te maken en rangschikkingen op te slaan voor uw belangrijkste contactpersonen.

Aanbevolen procedures voor rangschikking

Volg de volgende classificatieprincipes om de relevantie van de contactpersonen van uw app in de rij Suggesties voor Share Sheet te maximaliseren:

Sorteren op recentheid en frequentie

Rang berekenen als een combinatie van:

• Recency: Wanneer de gebruiker voor het laatst interactie heeft gehad met elke contactpersoon
• Frequentie: Hoe vaak de gebruiker communiceert met elke contactpersoon

Een contactpersoon waaraan de gebruiker gisteren een bericht heeft gestuurd, kan bijvoorbeeld score 95 hebben, terwijl een contactpersoon waaraan 2 weken geleden een bericht is gestuurd, score 60 kan hebben.

// 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;
}

Verouderde contactpersonen verwijderen

Contactpersonen waarmee de gebruiker in 30+ dagen geen interactie heeft gehad, moeten aanzienlijk worden verwijderd of lager gerangschikt. Hiermee blijven suggesties actueel en relevant:

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

Rangschikkingen regelmatig bijwerken

Plan rangschikkingsupdates op een frequentie die zinvol is voor uw app: dagelijks voor berichten-apps, wekelijks voor e-mail of maandelijks voor agenda-apps. Gebruik indien nodig achtergrondtaken:

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

Privacy en toestemming

Voeg alleen uitdrukkelijk opgegeven contactpersonen toe

Uw app moet alleen bijdragen aan de contactpersonen die de gebruiker expliciet heeft toegevoegd of geautoriseerd. Nooit:

• Het hele adresboek uploaden
• Contactpersonen automatisch synchroniseren zonder toestemming van de gebruiker
• Contactpersonen delen vanuit bedrijfsadresboeken zonder expliciete toestemming

Vraag om toestemming voordat u contactpersonen opslaat in het systeem Personen:

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

Privacy-instellingen voor gebruikers respecteren

Gebruikers toestaan om:

• Kiezen welke contactpersonen u wilt delen met Windows
• Afmelden voor de People-integratie
• Hun contactpersonen op elk gewenst moment verwijderen uit Windows

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

Integratie met het shareblad

Wanneer u uw contactpersonen rangschikt en onderhoudt met de bovenstaande richtlijnen, zien gebruikers de belangrijkste contactpersonen van uw app in de rij suggesties van het Windows Share Sheet. Dit pad ondersteunt momenteel People-contactpersonen.

Zo zorgt u ervoor dat uw contacten worden weergegeven:

1. Maak een UserDataAccount met DisplayName = "com.microsoft.peoplecontract"
2. Contactpersonen opslaan met vereiste velden (FirstName, RemoteId, DisplayPicture)
3. Maak een ContactAnnotationList met ranglijsten
4. Stel SupportedOperations = Share in voor elke annotatie
5. Rangschikkingen regelmatig bijwerken op basis van recency en frequentie
6. Verwijder oude contacten na 30+ dagen

Zie Inhoud van uw app delen en inhoud ontvangen in uw app voor de volledige integratiehandleiding voor Share Sheet.

Verwante inhoud

• Inhoud delen vanuit uw app
• Inhoud ontvangen in uw app
• Opties voor delen integreren in uw Windows-app
• UserDataAccount
• ContactStore
• Windows.ApplicationModel.Contacts-naamruimte