Orang-orang di Windows

Windows adalah platform ideal bagi aplikasi pihak ketiga untuk mengintegrasikan kontak orang teratas mereka. Integrasi ini memungkinkan pengguna berinteraksi dengan persona untuk berbagai pengalaman orang. Windows sekarang menyediakan WinUI pihak ketiga dan aplikasi lain dengan identitas paket dengan API untuk menyimpan semua kontak mereka.

Setelah aplikasi Anda menyimpan kontak mereka di Windows, pengguna akan dapat melihat saran kontak ini di panel Berbagi di Windows untuk berbagi dengan mulus dengan kontak teratas mereka. Lihat Cara berbagi file di File Explorer di Windows untuk informasi selengkapnya tentang panel Berbagi .

Membuat UserDataAccount untuk Kontrak Pengguna

Mulailah dengan membuat akun data pengguna. Aplikasi pihak ketiga diperlukan untuk membuat UserDataAccount dengan UserDisplayName berfungsi sebagai "com.microsoft.peoplecontract".

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

Selanjutnya, tambahkan "com.microsoft.windows.system" ke daftar ExplictReadAccessPackageFamilyNames untuk akun tersebut. Ini akan memberikan akses terbatas dari kontak pihak ketiga ke pengalaman Windows.

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

Menyimpan kontak

Langkah pertama dalam menyimpan kontak adalah membuat daftar kontak. Untuk melakukan ini, aplikasi pihak ketiga harus membuat daftar kontak baru untuk UserDataAccount di ContactStore Windows. Aplikasi dapat memilih untuk menyimpan jenis akses default OtherAppReadAccess untuk daftar kontak, sambil mengaturnya None akan mencegah aplikasi lain memiliki akses ke kontak ini. Lihat enum ContactListOtherAppReadAccess untuk daftar lengkap jenis akses yang tersedia.

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

Saat menyimpan kontak, aplikasi pihak ketiga harus menyertakan semua informasi relevan yang diperlukan agar pengalaman Windows mendukung Kontak.

Bidang berikut diperlukan saat menyimpan kontak:

FirstName
RemoteId
DisplayPicture

Bidang berikut bersifat opsional:

LastName
Phones
Emails

Cuplikan kode ini menunjukkan cara menyimpan kontak:

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

Catatan

DisplayName untuk Kontak dibangun menggunakan FirstName dan LastName. Jika nama belakang tidak disediakan, DisplayName akan identik dengan string yang disediakan untuk nama depan.

Menyimpan peringkat untuk kontak

Anda dapat membuat daftar anotasi untuk UserDataAccount untuk menyimpan peringkat untuk kontak Anda. Aplikasi dapat menyimpan peringkat untuk kontak teratas mereka dengan menambahkan anotasi ke kontak. Anotasi ini disimpan sebagai bagian dari daftar anotasi di penyimpanan kontak.

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

Anda dapat menyimpan peringkat untuk kontak teratas Anda dengan menggunakan anotasi pada kontak. Peringkat disimpan sebagai bagian dari ProviderProperties pada anotasi kontak. Bersama dengan peringkat, aplikasi harus mengatur SupportedOperations pada anotasi kontak menjadi 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);
}

Memperbarui peringkat kontak

Ini atas kebijakan aplikasi kapan harus memperbarui peringkat kontak yang disimpan di Windows. Windows merekomendasikan agar daftar peringkat diperbarui secara teratur untuk memberikan pengalaman pengguna terbaik. Setiap kali Anda perlu memperbarui daftar peringkat, Anda harus mengikuti beberapa langkah.

Hapus ContactAnnotationList.

Setelah aplikasi memiliki daftar kontak teratas yang diperbarui, daftar anotasi dapat dihapus dan daftar anotasi baru dengan anotasi yang diperbarui untuk kontak teratas mereka dapat dibuat.
```
await this.contactAnnotationList.DeleteAsync();
```
Buat sebuah ContactAnnotationList baru. Ikuti langkah-langkah di bagian Menyimpan peringkat untuk kontak untuk membuat daftar anotasi baru dan menyimpan peringkat untuk kontak teratas Anda.

Praktik terbaik untuk pemeringkatan

Untuk memaksimalkan relevansi kontak aplikasi Anda di baris saran Share Sheet, ikuti prinsip peringkat berikut:

Urutkan berdasarkan yang terbaru dan frekuensi

Hitung peringkat sebagai kombinasi dari:

Resensi: Saat pengguna terakhir berinteraksi dengan setiap kontak
Frekuensi: Seberapa sering pengguna berinteraksi dengan setiap kontak

Misalnya, kontak yang dikirimkan pengguna kemarin mungkin memiliki peringkat 95, sementara kontak yang dikirim 2 minggu yang lalu mungkin memiliki peringkat 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;
}

Menghapus kontak kedaluarsa

Kontak yang belum berinteraksi dengan pengguna dalam 30+ hari harus dihapus atau di bawah peringkat secara signifikan. Ini menjaga saran tetap segar dan relevan:

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

Memperbarui peringkat secara teratur

Jadwalkan pembaruan peringkat pada irama yang masuk akal untuk aplikasi Anda - setiap hari untuk aplikasi olahpesan, mingguan untuk email, atau bulanan untuk aplikasi kalender. Gunakan tugas latar belakang jika perlu:

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

Hanya tambahkan kontak yang jelas disebutkan

Aplikasi Anda hanya boleh berkontribusi pada kontak yang telah ditambahkan atau diotorisasi pengguna secara eksplisit. Tidak pernah:

Mengunggah seluruh buku alamat
Menyinkronkan kontak secara otomatis tanpa persetujuan pengguna
Berbagi kontak dari direktori perusahaan tanpa izin eksplisit

Minta izin sebelum menyimpan kontak di sistem People:

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

Menghormati pengaturan privasi pengguna

Izinkan pengguna:

Pilih kontak mana yang akan dibagikan dengan Windows
Keluar dari integrasi People
Menghapus kontak mereka dari Windows kapan saja

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

Saat Anda memberi peringkat dan mempertahankan kontak Anda dengan panduan di atas, pengguna akan melihat kontak teratas aplikasi Anda di baris saran Windows Share Sheet. Jalur ini saat ini mendukung kontak Orang.

Untuk memastikan kontak Anda muncul:

Buat UserDataAccount dengan DisplayName = "com.microsoft.peoplecontract"
Simpan kontak dengan kolom wajib (FirstName, RemoteId, DisplayPicture)
Buat ContactAnnotationList dengan peringkat
Atur SupportedOperations = Share pada setiap anotasi
Perbarui peringkat secara teratur berdasarkan keterkinian dan frekuensi
Pangkas kontak kedaluarsa setelah 30+ hari

Lihat Berbagi konten dari aplikasi Anda dan Menerima konten di aplikasi Anda untuk panduan integrasi Share Sheet lengkap.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-23