Skip to content

Contacts API Setup

The main library functions are all accessible via the contacts.core.Contacts API.

There's no setup required. Just create an instance of Contacts and the world of contacts is at your disposal =)

In Kotlin,

Contacts(context)

in Java,

ContactsFactory.create(context);

ℹ️ The context parameter can come from anywhere; Application, Activity, Fragment, or View. It does not matter what context you pass in. The API will only use and store the Application context, to avoid leaks.

It's up to you if you just want to create instances on demand. Or, hold on to instances as a singleton that is injected to your dependency graph (via something like dagger, hilt, or koin), which will make black box testing and white box testing a walk in the park!

Sync adapter operations

Instances of Contacts may be initialized with callerIsSyncAdapter: Boolean to set the value of ContactsContract.CALLER_IS_SYNCADAPTER for all CRUD APIs provided by the instance that use android.provider.ContactsContract URIs.

For more info, read the in-code documentation of contacts.core.Contacts.callerIsSyncAdapter.

Logging support

Instances of Contacts may be initialized with logger: Logger for logging support.

For more info, read Log API input and output.

Custom data integration

Instances of Contacts may be initialized with customDataRegistry: CustomDataRegistry for custom data integration.

For more info, read Integrate custom data.

It is recommended to use a single instance of the Contacts API throughout your application using dependency injection. This will allow you to;

  1. Use the same Contacts API instance throughout your app.
    • This especially important when integrating custom data.
  2. Easily substitute your Contacts API instance with an instance of TestContacts.
    • This is useful in black box testing (UI instrumentation tests; androidTest/).
    • It may also be used in your production apps "test mode".
  3. Easily substitute your Contacts API instance with an instance of MockContacts

For more info, read Contacts API Testing.

ℹ️ This library does not (and will not) force you to do things you don't want. If you don't care about all of the above and just want to get out a quick prototype of a feature in your app or an entire app, then go for it!