How do I use insert and update APIs to create/insert custom data into new or existing contacts?

Android Contacts API Library written in Kotlin with Java interoperability. No more ContentProviders and cursors. Say goodbye to ContactsContract. Build your own contacts app!

How do I use insert and update APIs to create/insert custom data into new or existing contacts?

Regular and custom data can only be created/inserted into the database whenever inserting or updating new or existing contacts.

This library provides several insert and update APIs that support custom data integration.

  1. Insert
  2. ProfileInsert
  3. Update
  4. ProfileUpdate

To help illustrate how custom data integrates with these query APIs, we’ll use the HandleName and Gender custom data.

For more info, read How do I integrate the gender custom data? and How do I integrate the handle name custom data?

Creating/inserting custom data into a RawContact

Custom data, just like regular data kinds, are attached to a RawContact. They follow the same rules as regular data kinds.

For more info, read How do I learn more about the API entities?

For example, you are able to add handle names and set gender of a new RawContact,

newRawContact.addHandleName(contactsApi) {
   handle = "dude91"
}
newRawContact.setGender(contactsApi) {
   type = GenderEntity.Type.MALE
}

Once you have created/insert the custom data into the RawContact, you can perform the insert operation on the new RawContact to commit your changes into the database.

For more info, read How do I create/insert data into new or existing contacts?

The include function and custom data

All of the above mentioned APIs provide an include function that allows you to include only a given set of fields (data) to be processed in the insert operation. Custom data entries provides fields that can be used in this function.

By default, not calling the include function will include all fields, including custom data fields.

For example, to specifically include only HandleName and Gender fields,

.include(HandleNameFields.all + GenderFields.all)

For more info, read How do I include only the data that I want?

Blank data are not inserted

Blank data are data entities that have only null, empty, or blank primary value(s). Blanks are ignored and are not inserted by insert APIs.

For more info, read How do I learn more about “blank” data?