quiin/unifiedcontactpicker

Unified Contact Picker Android Library

Introduction

This library unifies the user contacts in a compact and user intuitive way allowing the end-user to choose between the contact's available communication options (email/phone number) follows Material Design guidelines.

Although there is a standard way to call the contact list in Android, it does not always feel well-integrated in your app Android applications. UnifiedContactPicker is an Android library which allows you to easily integrate contact picking workflow into your application with minimal effort

IMPORTANT ❗

---

This library is no longer in active development. However, pull requests for new features or bugfixes are always welcomed and will be attended.

Demo

Features

• Unifies user's contacts
• Customizable UI
• Easy and redy to use
• Display list of contacts
• Intuitive interface
• Follows Material Design guidelines
• Asynchronous contact loading

Installation

In order to use the library, add the following line to your root gradle file:

 
repositories {
    jcenter()
    maven { url "https://jitpack.io" }
    ...
}
 

As well as this line in your project build.gradle file

 
dependencies {
    compile 'com.github.quiin:unifiedContactPicker:{LATEST_VERSION}'
    ...
}
 

Usage

To use UnifiedContactPicker in your app simply follow this 3 simple steps:

1. Add read contacts permission in your manifest

    <uses-permission android:name="android.permission.READ_CONTACTS"/>

2. Launch ContactPickerActivity.java as activity result

// Your Activity or Fragment
public void launchContactPicker(View view) {
        int permissionCheck = ContextCompat.checkSelfPermission(this, Manifest.permission.READ_CONTACTS);
        if(permissionCheck == PackageManager.PERMISSION_GRANTED){
            Intent contactPicker = new Intent(this, ContactPickerActivity.class);
            startActivityForResult(contactPicker, CONTACT_PICKER_REQUEST);
        }else{
            ActivityCompat.requestPermissions(this,
                    new String[] {Manifest.permission.READ_CONTACTS},
                    READ_CONTACT_REQUEST);
        }
    }

3. Override onActivityResult() and wait for the user to select the contacts.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    switch (requestCode){
        case CONTACT_PICKER_REQUEST:
            if(resultCode == RESULT_OK){
                TreeSet<SimpleContact> selectedContacts = (TreeSet<SimpleContact>)data.getSerializableExtra(ContactPickerActivity.CP_SELECTED_CONTACTS);
                for (SimpleContact selectedContact : selectedContacts)
                        Log.e("Selected", selectedContact.toString());
            }else
                Toast.makeText(this, "No contacts selected", Toast.LENGTH_LONG).show();
        break;
        default:
            super.onActivityResult(requestCode,resultCode,data);
        }
}

Contacts are returned in a TreeSet of SimpleContact; each SimpleContact object ha the following accessible properties:

• DisplayName - Contact display name
• Communication - Contact selected communication (email/phone)

⚠️ IMPORTANT

As of SDK 23 (Android 6) developers are requested to explicitly ask for permissions at runtime. So please be sure to request for contact reading permissions using the previous code or any other means you prefer.

Customization

The following UI views can be customized:

UI component	Intent extra	Expected value	Type	Sugestion
FAB color	CP_EXTRA_FAB_COLOR	hexColor	String	-
Selection color	CP_EXTRA_SELECTION_COLOR	hexColor	String	-
Selection Drawable	CP_EXTRA_SELECTION_DRAWABLE	Image	byte []	use PickerUtils.sendDrawable()
Fab drawable	CP_EXTRA_FAB_DRAWABLE	Image	byte []	use PickerUtils.sendDrawable()
Chips	CP_EXTRA_SHOW_CHIPS	boolean	boolean	-

Aditionally, you can customize the contact query parameters used to extract the user's contacts adding the following extras to the intent

Extra	Type
CP_EXTRA_PROJECTION	String []
CP_EXTRA_SELECTION	String
CP_EXTRA_SELECTION_ARGS	String []
CP_EXTRA_HAS_CUSTOM_SELECTION_ARGS	boolean
CP_EXTRA_SORT_BY	String

Example

public void launchContactPicker(View view) {
        int permissionCheck = ContextCompat.checkSelfPermission(this, Manifest.permission.READ_CONTACTS);
        if(permissionCheck == PackageManager.PERMISSION_GRANTED){
            Intent contactPicker = new Intent(this, ContactPickerActivity.class);
            //Don't show Chips
            contactPicker.putExtra(ContactPickerActivity.CP_EXTRA_SHOW_CHIPS, false);
            //Customize Floating action button color
            contactPicker.putExtra(ContactPickerActivity.CP_EXTRA_FAB_COLOR, "#FFF722");
            //Customize Selection drawable
            contactPicker.putExtra(ContactPickerActivity.CP_EXTRA_SELECTION_DRAWABLE, PickerUtils.sendDrawable(getResources(),R.drawable.my_drawable));
            startActivityForResult(contactPicker, CONTACT_PICKER_REQUEST);
        }else{
            ActivityCompat.requestPermissions(this,
                    new String[] {Manifest.permission.READ_CONTACTS},
                    READ_CONTACT_REQUEST);
        }
    }

Default values & behavior

• Default projection columns:

  • ContactsContract.Data._ID
  • ContactsContract.Contacts.DISPLAY_NAME
  • ContactsContract.CommonDataKinds.Phone.NUMBER
  • ContactsContract.Data.MIMETYPE

• Default selection query:

"(" + ContactsContract.Data.MIMETYPE + "=? OR " + ContactsContract.Data.MIMETYPE + "=?)"

• Default selection params:
  • ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE
  • ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
• Default sorting: DisplayName Ascendant
• A chip is added to the textview when one of the following happens:
  • User chooses a contact from the contact list
  • User writes a new email/phone - the chip is created after an empty space is found (" ")

Considerations

• In the absence of any of these extras, its value will fallback to the default value
• If you wish to use a custom selection string (CP_EXTRA_SELECTION) with custom selection arguments (CP_EXTRA_SELECTION_ARGS) the use of CP_EXTRA_HAS_CUSTOM_SELECTION_ARGS is required in order for the query to work (see defaults section for more information)

Support & extension

• Feel free to make any pull request to add a new behaviour or fix some existing bug
• Feel free to open issues if you find some bug or unexpected behaviour
• I'll keep polishing and giving support to this library in my free time

Acknowledgments

• MaterialLetterIcon For the cool image icon in contact list
• RoundedImageView For the rounded icon once a contact is selected
• ExpandableRecyclerView For the expandable recycler view in contact list
• Nachos For the chip view

unifiedcontactpicker's Issues

I dont want emails . I want to extract phone numbers only

Hey The library is awesome and build very well. I want to implement phone numbers not email . There should be an optional argument for both contact phone number and contact email.

Searching for contacts emails only

Hey, is there any way to only search for contacts' email addresses? Also, is the search bar in the preview gif a part of the library? Thanks

Search option for contacts

The current search option inside the chips is really bad, it doesnt show all possible options for the string entered.

Is there anyway I can override this and implement my own search algo?

Any contacts picker should have a neat search option.

Restrict portrait mode

How can I restrict to portrait mode only?

Scrolling

while scrolling list of contacts last contact have multiple phone numbers can't able to expand

Contacts selected as search result does not return display name

If we search for a contact in the search box and select it by ticking, the returned SimpleContact object does not give DisplayName correctly. Instead the phone number is returned

java.util.ConcurrentModificationException while searching contact

E/AndroidRuntime: FATAL EXCEPTION: java.util.ConcurrentModificationException at java.util.ArrayList$Itr.next(ArrayList.java:831) at mx.com.quiin.contactpicker.adapters.AutoCompleteAdapter$ContactFilter.publishResults(AutoCompleteAdapter.java:112) at android.widget.Filter$ResultsHandler.handleMessage(Filter.java:282) at android.os.Handler.dispatchMessage(Handler.java:102) at android.os.Looper.loop(Looper.java:154) at android.app.ActivityThread.main(ActivityThread.java:6121) at java.lang.reflect.Method.invoke(Native Method) at com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run(ZygoteInit.java:889)

Hiding the actionbar

Is there a way to hide the action bar on the ContactPickerActivity - I've tried setting this in my manifest file but to no avail;

<activity android:name="mx.com.quiin.contactpicker.ui.ContactPickerActivity"
            android:theme="@style/AppTheme.NoActionBar">
</activity>

Hiding the chips make contact search bar disappear.

Hiding the chips using this code disappears search bar also. I really want search bar still there, so the user can find contacts easily

contactPicker.putExtra(ContactPickerActivity.CP_EXTRA_SHOW_CHIPS, false);

When clearing chips from search bar, contact selected from the list still appeared as selected instead of clear/unselected

Selected a contact from list, then i clear the chip from search bar. But contact still found selected in the list. When i click the FAB, there is no out put ( selectedContact is empty).

Can I use Mobile & Email Address Both for Communication ?.

Hey The library is awesome and build very well. I want to implement phone numbers and email both .Is it possible to do that ?.