Native APIs | Contacts: Scripting

This section provides a guide to work with Contacts scripting APIs.

You can access the Contacts submodule APIs via the DeviceContacts class under the EasyMobile namespace.

Requesting Android Permissions

On Android 6.0 and newer platforms which support runtime permissions, you must check and request the following permissions if they're not granted before using the Contacts API.

android.permission.WRITE_CONTACTS is required for the AddContact and DeleteContact methods.
android.permission.READ_CONTACTS is required for the GetContacts and PickContact methods.

Unity has provided useful APIs for checking and requesting Android permissions in the Permission class of their UnityEngine.Android namespace.

// Check if android.permission.WRITE_CONTACTS has been granted and request it if not.
// Similar logic can be applied for other permissions.
if (Permission.HasUserAuthorizedPermission("android.permission.WRITE_CONTACTS"))
{
    // The permission has been granted!
    // Here we can proceed with adding or deleting contacts...
}
else
{
    // android.permission.WRITE_CONTACTS has not been granted,
    // we need to ask for this permission before using related Contacts API methods.
    Permission.RequestUserPermission("android.permission.WRITE_CONTACTS");

    // Note that the permission won't be granted immediately, so a simple approach
    // is to start a coroutine and keep checking 
    // Permission.HasUserAuthorizedPermission("android.permission.WRITE_CONTACTS")
    // until it returns true before proceeding with your actions.
}

Fetching All Contacts

Get all the contacts from the device.

DeviceContacts.GetContacts(GetContactsCallback);

This callback will be invoked after the operation completes.

private void GetContactsCallback(string error, Contact[] contacts)
{
    if(!string.IsNullOrEmpty(error))
    {
        // This means there was an error when fetching contacts.
        // You should show the error to users.
    }
    else
    {
        // Otherwise this means all contacts have been collected successfully.
        // Now you can access them via the contacts array.

        foreach (Contact contact in contacts)
            Debug.Log(contact); // Log info of each contact.
    }
}

Adding a Contact

Create a contact class and provide information as needed.

All contact information pieces are optional, just provide what you need.

// Initialize contact's emails.
// Key is the email's label.
// Value is the actual email.
KeyValuePair<string, string>[] emails = new KeyValuePair<string, string>[]
{
    new KeyValuePair<string, string>("Home", "0123456789"),
    new KeyValuePair<string, string>("Work", "1234567890")
};

// Initialize the contact's phone numbers.
// Key is the phone number's label.
// Value is the actual phone number.
KeyValuePair<string, string>[] phoneNumbers = new KeyValuePair<string, string>[]
{
    new KeyValuePair<string, string>("Home", "Home@home.com"),
    new KeyValuePair<string, string>("Work", "Work@work.com")
};

Contact contact = new Contact()
{
    FirstName = "contact's first name",
    MiddleName = "contact's middle name",
    LastName = "contact's last name",
    Emails = emails,
    PhoneNumbers = phoneNumbers,
    Company = "contact's company",
    Photo = photo, // Contact's photo (Texture2D)
    Birthday = new DateTime(1970, 1, 1) // Contact's birth day
};

Add the contact created above into the device's contacts.

string error = DeviceContacts.AddContact(contact);

if (!string.IsNullOrEmpty(error))
{
    // This means there was an error when adding new contact into the device.
    // You should show the error to user.
}
else
{
    // This means the contact is added successfully.
}

Deleting a Contact

Delete an existing contact.

DeviceContacts.DeleteContact(contact);

You can also delete a contact with its id.

DeviceContacts.DeleteContact("contact's id");

Picking a Contact

Open native UI to pick a contact.

DeviceContacts.PickContact(PickContactCallback);

This callback will be invoked after the user picks a contact and returns to your app.

private void PickContactCallback(string error, Contact contact)
{
    if (!string.IsNullOrEmpty(error))
    {
        // This means there was an error when picking contact.
        // You should show the error to users.
    }
    else
    {
        // This means the contact is picked successfully.
        // You can get all its info from the "contact" parameter.
        Debug.Log(contact); // Log all info of the selected contact.
    }
}

Scripting