Skip to content

Sync contact data across devices

Syncing contact data, including groups, are done automatically by the Contacts Provider depending on the account sync settings. You can typically find these account sync settings via Settings -> Accounts -> -> Account sync -> "Contacts". Of course, in addition to having Contacts syncing enabled in settings, you must also have network connection to sync between the device and remote servers.

Account sync settings

When you have Contacts syncing enabled, as long as the android.accounts.Account has active sync adapters and remote services and you have network connection, data belonging to that account (e.g. "vestrel00@gmail.com" is a Google account) are synced across devices and online. This means that any contacts you create, update, or delete will be synced on all devices and services associated with that account.

ℹ️ Besides Google Accounts, there is also Samsung, Xiaomi, Yahoo, MSN/Hotmail, etc.

Syncing contacts across devices is possible with sync adapters and Contacts' lookup key, more specifically the RawContact's source ID.

ℹ️ For more info, read about Contact lookup key vs ID.

Adding or removing Accounts

When an Account is added to the system and Contacts syncing is enabled and there is network connection, the Contacts Provider will automatically fetch all Contacts, RawContacts, Data, and Groups that belong to that Account.

Similarly, when an Account is removed from the system though regardless of Contacts syncing enabled or network availability, the Contacts Provider will automatically remove Contacts, RawContacts, Data, and Groups that belong to that Account.

Only contacts that are associated with an Account are synced

More specifically, RawContacts that are not associated with an Account (local, device-only) are not synced.

ℹ️ For more info, read about Local (device-only) contacts.

Syncing is account specific (and therefore specific to RawContacts as a Contact may have one or more constituent RawContacts from different Accounts), which is why you must turn on Contact syncing in the system settings.

For example, data belonging to a RawContact that is associated with a Google account (e.g. Gmail) will be available anywhere the Google account is used; in any Android or iOS device, a web browser, etc... Data is synced by Google’s sync adapters between devices and their remote servers. Syncing depends on the account sync settings, which can be configured in the system settings app and possibly through some remote configuration.

Here is an example of a newly created RawContact associated with a com.google Account prior to syncing,

#### Contacts table
Contact id: 31, lookupKey: 2059r31-38462A40563E3A4436
#### RawContacts table
RawContact id: 31, contactId: 31, sourceId:null

After sync,

#### Contacts table
Contact id: 31, lookupKey: 2059i7b975d4a8fec684e
#### RawContacts table
RawContact id: 31, contactId: 31, sourceId:7b975d4a8fec684e

For a RawContact that is not associated with an Account (null),

#### Contacts table
Contact id: 32, lookupKey: 0r32-3032543A2E324644405A
#### RawContacts table
RawContact id: 32, contactId: 32, sourceId:null

When are changes synced?

In general, the Contacts Provider and the registered sync adapters are responsible for triggering sync events as long as Contacts sync is enabled for the Account in the system settings.

You can manually trigger a sync through the system sync settings. Some events that will probably trigger a sync are;

  • Getting network connection from a state where there was no network connection (offline -> online).
  • Adding an Account.
  • Removing an Account.

Until changes are synced, local changes will not take effect. Some examples are;

  • RawContact rows are marked for deletion but remain until synced.
  • Group rows are marked for deletion but remain until synced.
  • Newly created RawContacts may have a null or temporary source ID.
  • New lookup key is not assigned after associating a local RawContact to an Account.

Some custom data provided in this library are not synced

The Gender, HandleName, Pokemon, RpgStats, and RpgProfession custom data will not be synced because they are not account specific and they have no sync adapters and no remote service to interface with.

ℹ️ For more info, read Integrate custom data.

Custom data from other apps may be synced

This library does not sync contact data that belongs to other apps and services. For example, Google Contacts, WhatsApp, and other apps define their own set of custom data that their own sync adapters sync with their own remote services, which requires authentication.

ℹ️ For more info, read Integrate custom data from other apps.

This library does not provide sync adapters

This library does not have any APIs related to syncing. It is considered out of scope of this library as it requires access to remote databases and account-specific data. Let's talk about it though since it is good to know how it works if you just want more insight.

https://developer.android.com/guide/topics/providers/contacts-provider#SyncAdapters

The Contacts Provider is specifically designed for handling synchronization of contacts data between a device and an online service. This allows users to download existing data to a new device and upload existing data to a new account. Synchronization also ensures that users have the latest data at hand, regardless of the source of additions and changes. Another advantage of synchronization is that it makes contacts data available even when the device is not connected to the network.

Although you can implement synchronization in a variety of ways, the Android system provides a plug-in synchronization framework that automates the following tasks:

  • Checking network availability.
  • Scheduling and executing synchronization, based on user preferences.
  • Restarting synchronizations that have stopped.

To use this framework, you supply a sync adapter plug-in. Each sync adapter is unique to a service and content provider, but can handle multiple account names for the same service. The framework also allows multiple sync adapters for the same service and provider.

This library does not provide any sync adapters. Instead, it relies on existing sync adapters to do the syncing. Sync adapters and syncing are really out of scope of this library. Syncing is its own thing that typically happens outside of an application UI. This library is focused on Create, Read, Update, and Delete (CRUD) operations on native and custom data to and from the local database. Syncing the local database to and from a remote database in the background is a totally different story altogether.

ℹ️ For more info, read Integrate custom data.