Alternatif Capacitor Community Contacts

Jika Anda membutuhkan alternatif kontak komunitas Capacitor, pengganti drop-in paling lengkap adalah @capgo/capacitor-contacts. Ini mencakup apa yang @capacitor-community/contacts lakukan (membaca, membuat, menghapus, dan memilih kontak) serta menambahkan pembaruan kontak tanpa mengubah ID-nya, pagination, grup, akun, layar kontak native, dan pemilihan tanpa izin di Android, yang penting untuk kebijakan kontak Google Play 2027. Panduan ini membandingkan keduanya dan memetakan setiap panggilan agar Anda dapat bermigrasi dalam satu sore.

Mengapa mencari alternatif

@capacitor-community/contacts dipelihara dan memiliki rilis Capacitor 8. Ini pilihan yang baik untuk alur baca dan buat yang sederhana. Tim biasanya melampauinya karena alasan berikut:

• Tidak ada metode update. Anda dapat membuat dan menghapus kontak, tetapi tidak dapat mengedit satu kontak. Menghapus dan membuat ulang akan memberikan ID baru pada kontak, yang merusak referensi yang Anda simpan dan dapat kehilangan data yang tidak dibaca oleh plugin.
• Tidak ada pagination. getContacts mengembalikan seluruh buku alamat dalam satu panggilan. Pada perangkat dengan 5.000 kontak dan foto, itu lambat dan berat secara memori.
• Picking membutuhkan izin di Android. Android pickContact meminta grup izin kontak sebelum membuka picker, lalu membaca kontak dari buku alamat. Di bawah Kebijakan Izin Kontak Google Play, aplikasi yang menargetkan Android 17 hanya dapat menyimpan READ_CONTACTS untuk fitur inti.
• Tanpa grup, akun, atau layar native. Tidak ada cara untuk mendaftar grup, memilih akun tempat kontak baru disimpan, atau membuka formulir “kontak baru” sistem.

Perbandingan fitur

Instal

bun add @capgo/capacitor-contacts
bunx cap sync

Plugin ini tidak menambahkan izin ke manifest Android Anda. Tambahkan hanya yang Anda gunakan:

<!-- Needed for getContacts, getContactById, countContacts, groups, accounts -->
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Needed for createContact, updateContactById, deleteContactById, groups writes -->
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

Di iOS, tambahkan NSContactsUsageDescription ke Info.plist jika Anda membaca atau menulis buku alamat. Memilih kontak tidak membutuhkannya.

Panduan migrasi, panggilan per panggilan

Izin

// Before
import { Contacts } from '@capacitor-community/contacts';
const perm = await Contacts.requestPermissions();
if (perm.contacts !== 'granted') return;

// After
import { CapacitorContacts } from '@capgo/capacitor-contacts';
const status = await CapacitorContacts.requestPermissions({ permissions: ['readContacts'] });
if (status.readContacts !== 'granted' && status.readContacts !== 'limited') {
  await CapacitorContacts.openSettings();
  return;
}

Di iOS 18 dan versi lebih baru, pengguna dapat memberikan akses ke sebagian kontak. Plugin melaporkan hal itu sebagai limited. Anggap saja sudah diberikan dan hanya harapkan kontak yang dibagikan.

Baca semua kontak

// Before: whole address book, projection object
const { contacts } = await Contacts.getContacts({
  projection: { name: true, phones: true, emails: true },
});
const first = contacts[0];
console.log(first.name?.display, first.phones?.[0]?.number);

// After: fields array, paginated
const pageSize = 200;
let offset = 0;
for (;;) {
  const { contacts } = await CapacitorContacts.getContacts({
    fields: ['displayName', 'givenName', 'familyName', 'phoneNumbers', 'emailAddresses'],
    limit: pageSize,
    offset,
  });
  render(contacts);
  if (contacts.length < pageSize) break;
  offset += pageSize;
}

declare function render(list: unknown[]): void;

Gunakan countContacts() terlebih dahulu jika Anda ingin menampilkan progress bar.

Baca satu kontak

// Before
const { contact } = await Contacts.getContact({
  contactId: id,
  projection: { name: true, phones: true },
});

// After
const { contact } = await CapacitorContacts.getContactById({
  id,
  fields: ['displayName', 'phoneNumbers'],
});
if (!contact) console.log('Not found');

Create a contact

// Before
const { contactId } = await Contacts.createContact({
  contact: {
    name: { given: 'Ada', family: 'Lovelace' },
    phones: [{ type: PhoneType.Mobile, number: '+44 20 7946 0000' }],
    emails: [{ type: EmailType.Work, address: 'ada@example.com' }],
  },
});

// After
const { id } = await CapacitorContacts.createContact({
  contact: {
    givenName: 'Ada',
    familyName: 'Lovelace',
    phoneNumbers: [{ type: 'MOBILE', value: '+44 20 7946 0000' }],
    emailAddresses: [{ type: 'WORK', value: 'ada@example.com' }],
  },
});

displayName hanya bisa dibaca di plugin Capgo. Tulis givenName dan familyName, dan perangkat akan memformat nama tampilan.

Perbarui kontak (baru)

await CapacitorContacts.updateContactById({
  id,
  contact: {
    givenName: 'Ada',
    familyName: 'King',
    jobTitle: 'Analyst',
    phoneNumbers: [{ type: 'MOBILE', value: '+44 20 7946 0000' }],
  },
});

ID tetap sama, jadi referensi yang Anda simpan masih berfungsi. Baca kontak terlebih dahulu dan kembalikan field yang ingin dipertahankan, agar Anda tidak menghapus sesuatu secara tidak sengaja.

Jika Anda lebih suka membiarkan pengguna mengedit, buka editor sistem:

await CapacitorContacts.displayUpdateContactById({ id });

Hapus kontak

// Before
await Contacts.deleteContact({ contactId: id });

// After
await CapacitorContacts.deleteContactById({ id });

Pilih kontak

// Before: requests the contacts permission on Android first
const { contact } = await Contacts.pickContact({
  projection: { name: true, phones: true },
});

// After: one phone number, no permission on Android or iOS
import { ContactProperty } from '@capgo/capacitor-contacts';

const { contacts } = await CapacitorContacts.pickContacts({
  property: ContactProperty.PhoneNumber,
});
const phone = contacts[0]?.phoneNumbers?.[0]?.value;

Jika Anda membutuhkan catatan kontak lengkap dari picker, panggil pickContact() tanpa property. Di Android, ini mengembalikan kontak lengkap hanya jika READ_CONTACTS diberikan.

Pemetaan field

Nilai tipe juga berubah: plugin Capgo menggunakan string kapital seperti 'MOBILE', 'HOME', 'WORK' untuk telepon dan email.

Migrasikan satu layar dalam satu waktu

Kedua plugin terdaftar dengan nama native yang berbeda (Contacts dan CapacitorContacts), sehingga keduanya bisa diinstal bersamaan saat Anda memindahkan call site. Adapter kecil menjaga sisa aplikasi Anda tetap tidak berubah:

import { CapacitorContacts } from '@capgo/capacitor-contacts';

export interface AppContact {
  id: string;
  name: string;
  phones: string[];
}

export async function listContacts(limit = 200, offset = 0): Promise<AppContact[]> {
  const { contacts } = await CapacitorContacts.getContacts({
    fields: ['displayName', 'phoneNumbers'],
    limit,
    offset,
  });
  return contacts.map((c) => ({
    id: c.id ?? '',
    name: c.displayName ?? '',
    phones: (c.phoneNumbers ?? []).map((p) => p.value),
  }));
}

Setelah call site terakhir dipindahkan, hapus plugin community tersebut, jalankan bunx cap sync, dan periksa Android manifest yang telah digabung untuk memastikan hanya izin yang Anda butuhkan yang tersisa.

Pemecahan Masalah

getContacts mengembalikan list kosong pada iOS. Pengguna memberikan akses terbatas dan tidak membagikan kontak apa pun, atau menolak akses. Periksa readContacts dan tawarkan openSettings().

Kontak yang dibuat tidak muncul di akun tertentu pada Android. Berikan account (dari getAccounts()) pada kontak yang Anda buat.

Foto membuat list menjadi lambat. Jangan minta photo di tampilan daftar. Muat dengan getContactById ketika pengguna membuka kontak.

Play Console menandai READ_CONTACTS. Pindahkan alur undangan dan berbagi ke pickContacts({ property }) dan hapus izinnya jika tidak ada yang lain yang membutuhkannya.

Rilis

Mengganti plugin adalah perubahan native, jadi butuh build store. Build Capgo bisa menghasilkan build iOS dan Android di cloud. Setelah itu, perbaikan pada layar kontak Anda berupa JavaScript dan bisa dikirim bersama Live updates Capgo. Seluruh API ada di dokumentasi plugin contacts.