public class ContactPicker

Lets the user hand the application a small number of contacts they chose themselves, without the application gaining access to the address book.

This is the privacy-minimized counterpart to ContactsManager. Where ContactsManager enumerates the whole address book – and therefore needs the broad contacts permission – this class shows the platform’s own contact picker. The user selects, the platform copies just the fields that were asked for out of just the contacts that were selected, and the application never gets to see anything else.

Prefer it whenever the application needs “a phone number the user picked” rather than “the address book”. Google Play requires exactly that distinction: from 2027-01-27, an app targeting Android 17 (API level 37) or later that carries READ_CONTACTS without core-functionality justification has to pass a Play Console declaration, and an app that only ever calls this class never asks for that permission in the first place.

Requesting fields

The requested fields are a bit set of the constants on this class. Only those fields are populated on the returned contacts; everything else is left null or zero. Asking for less is not merely polite – on Android the request also decides which contacts the picker offers, and the platform refuses to return anything that was not asked for.

ContactPicker picker = new ContactPicker();
picker.setRequestedFields(ContactPicker.NAME | ContactPicker.PHONE);
picker.pick(new ActionListener<ActionEvent>() {
    public void actionPerformed(ActionEvent ev) {
        Contact[] picked = ContactPicker.getPickedContacts(ev);
        if(picked.length == 0) {
            // the user backed out
            return;
        }
        numberField.setText(picked[0].getPrimaryPhoneNumber());
    }
});

The result is a snapshot

The contacts handed to the callback are plain copies. The application has no continuing access to them: it cannot re-read them later, and on Android the temporary grant behind them is gone by the time the callback returns. Anything that has to outlive the callback must be copied out of the Contact and stored by the application.

One getter does not follow the rule that an unrequested field stays null, and cannot be made to. Contact#getDisplayName() never returns null: on a contact carrying no name it makes one up from the primary phone number, the primary email or the id, and caches it. That is how every Contact in the framework behaves, not only a picked one, so a picker that suppressed it would be the odd one out rather than the correct one. Ask Contact#getFirstName() and Contact#getFamilyName() when what you need to know is whether a name was actually supplied.

For the same reason Contact#getId() on a picked contact is only an opaque platform identifier useful for telling two picked contacts apart. Passing it to ContactsManager#getContactById(String) needs full address-book access, which is the thing this class exists to avoid.

What a platform can actually deliver

A picker returns what its platform is able to hand over without the broad permission, and that is not the same everywhere. Read every field you asked for defensively: a null one means the user’s contact did not carry it, or the platform could not supply it.

Android 17 and later, iOS and the simulator serve every field on this class. Android before 17 has no contact picker of its own, so the fallback is the contacts app’s own single-row picker: it returns one contact carrying one kind of data, #NAME plus whichever of #PHONE, #EMAIL and #ADDRESS was requested first. #PHOTO, #BIRTHDAY and #WEBSITE are best-effort there – they are read through the granted contact’s own data rows, which some devices allow and some refuse – and #setMultiSelect(boolean) and #setRequireAllRequestedFields(boolean) have no effect. None of that ever escalates into a permission prompt; the fields simply come back null.

Availability

#isSupported() reports whether the platform has a picker at all. Where it does not, #pick(ActionListener) reports an empty selection rather than quietly falling back to reading the address book, because that fallback would need the permission the caller was trying not to ask for.