To contribute read CONTRIBUTING.md.
Rx support with react-native-contacts-rx
getAll
is a database intensive process, and can take a long time to complete depending on the size of the contacts list. Because of this, it is recommended you access the getAll
method before it is needed, and cache the results for future use.
Also there is a lot of room for performance enhancements in both iOS and android. PR's welcome!
var Contacts = require('react-native-contacts')
Contacts.getAll((err, contacts) => {
if(err === 'denied'){
// error
} else {
// contacts returned in []
}
})
getContactMatchingString
is meant to alleviate the amount of time it takes to get all contacts, by filtering on the native side based on a string.
var Contacts = require('react-native-contacts')
Contacts.getContactsMatchingString("filter", (err, contacts) => {
if(err === 'denied'){
// x.x
} else {
// Contains only contacts matching "filter"
console.log(contacts)
}
})
run npm install react-native-contacts
- In XCode, in the project navigator, right click
Libraries
➜Add Files to [your project's name]
- add
./node_modules/react-native-contacts/ios/RCTContacts.xcodeproj
- In the XCode project navigator, select your project, select the
Build Phases
tab and in theLink Binary With Libraries
section add libRCTContacts.a
As of Xcode 8 and React Native 0.33 it is now necessary to add kit specific "permission" keys to your Xcode Info.plist
file, in order to make requestPermission
work. Otherwise your app crashes when requesting the specific permission. I discovered this after days of frustration.
Open Xcode > Info.plist > Add a key (starting with "Privacy - ...") with your kit specific permission. The value for the key is optional in development. If you submit to the App Store the value must explain why you need this permission.
You have to add the key "Privacy - Contacts Usage Description".
For versions of RN before v0.21.0 use the old instructions.
- In
android/settings.gradle
...
include ':react-native-contacts'
project(':react-native-contacts').projectDir = new File(settingsDir, '../node_modules/react-native-contacts/android')
- In
android/app/build.gradle
...
dependencies {
...
compile project(':react-native-contacts')
}
- register module (in android/app/src/main/java/com/[your-app-name]/MainApplication.java)
...
import com.rt2zz.reactnativecontacts.ReactNativeContacts; // <--- import module!
public class MainApplication extends Application implements ReactApplication {
...
@Override
protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
new MainReactPackage(),
new ReactNativeContacts() // <--- and add package
);
}
...
}
- add Contacts permission (in android/app/src/main/AndroidManifest.xml)
- only add the permissions you need
READ_PROFILE
may be a required for other permissions
...
<uses-permission android:name="android.permission.READ_PROFILE" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
...
- Preliminary iOS and Android support
- API subject to revision, changelog in release notes
Feature | iOS | Android |
---|---|---|
getAll |
✔ | ✔ |
addContact |
✔ | ✔ |
updateContact |
✔ | ✔ |
deleteContact |
✔ | 😞 |
getContactsMatchingString |
✔ | ✔ |
get with options | 😞 | 😞 |
groups | 😞 | 😞 |
getAll
(callback) - returns all contacts as an array of objectsgetAllWithoutPhotos
- same asgetAll
on Android, but on iOS it will not return uris for contact photos (because there's a significant overhead in creating the images)getPhotoForId(contactId, callback)
- returns a URI (or null) for a contacts photoaddContact
(contact, callback) - adds a contact to the AddressBook.updateContact
(contact, callback) - where contact is an object with a valid recordIDdeleteContact
(contact, callback) - where contact is an object with a valid recordIDgetContactsMatchingString
(string, callback) - where string is any string to match a name (first, middle, family) tocheckPermission
(callback) - checks permission to access ContactsrequestPermission
(callback) - request permission to access Contacts
{
recordID: '6b2237ee0df85980',
company: "",
emailAddresses: [{
label: "work",
email: "carl-jung@example.com",
}],
familyName: "Jung",
givenName: "Carl",
jobTitle: "",
middleName: "",
phoneNumbers: [{
label: "mobile",
number: "(555) 555-5555",
}],
thumbnailPath: 'content://com.android.contacts/display_photo/3',
note: 'some text',
postalAddresses:
[
{
postCode: 'Postcooode',
city: 'City',
neighborhood: 'neighborhood',
street: 'Home Street',
formattedAddress: 'Home Street\nneighborhood\nCity Postcooode',
label: 'work'
}
]
}
NOTE
- on Android the entire display name is passed in the
givenName
field.middleName
andfamilyName
will be""
.
Currently all fields from the contact record except for thumbnailPath are supported for writing
var newPerson = {
emailAddresses: [{
label: "work",
email: "mrniet@example.com",
}],
familyName: "Nietzsche",
givenName: "Friedrich",
}
Contacts.addContact(newPerson, (err) => { /*...*/ })
//contrived example
Contacts.getAll( (err, contacts) => {
//update the first record
let someRecord = contacts[0]
someRecord.emailAddresses.push({
label: "junk",
email: "mrniet+junkmail@test.com",
})
Contacts.updateContact(someRecord, (err) => { /*...*/ })
//delete the second record
Contacts.deleteContact(contacts[1], (err) => { /*...*/ })
})
Update and delete reference contacts by their recordID (as returned by the OS in getContacts). Apple does not guarantee the recordID will not change, e.g. it may be reassigned during a phone migration. Consequently you should always grab a fresh contact list with getContacts
before performing update and delete operations.
You can also delete a record using only it's recordID like follows: Contacts.deleteContact({recordID: 1}, (err) => {})}
The thumbnailPath is the direct URI for the temp location of the contact's cropped thumbnail image.
<Image source={{uri: contact.thumbnailPath}} />
checkPermission
(callback) - checks permission to access Contacts.
requestPermission
(callback) - request permission to access Contacts.
Usage as follows:
Contacts.checkPermission( (err, permission) => {
// Contacts.PERMISSION_AUTHORIZED || Contacts.PERMISSION_UNDEFINED || Contacts.PERMISSION_DENIED
if(permission === 'undefined'){
Contacts.requestPermission( (err, permission) => {
// ...
})
}
if(permission === 'authorized'){
// yay!
}
if(permission === 'denied'){
// x.x
}
})
These methods do not re-request permission if permission has already been granted or denied. This is a limitation in iOS, the best you can do is prompt the user with instructions for how to enable contacts from the phone settings page Settings > [app name] > contacts
.
On android permission request is done upon install so this function will only show if the permission has been granted.
- android feature parity
- migrate iOS from AddressBook to Contacts
- implement
get
with options - groups support