# React Native Paged Contacts Paged contacts manager for React Native. **Currently, only fetching contacts is supported.** ## Installation #### iOS * Add `RCTPagedContacts.xcodeproj` to your project. * In you project's target, under `Build Phases` — `Target Dependencies`, add `RCTPagedContacts`. * In you project's target, under `Build Phases` — `Link Libraries With Libraries`, add `RCTPagedContacts`. * Add `NSContactsUsageDescription` privacy key description to `Info.plist` #### Android * Add the following to `settings.gradle`: ```groovy include ':pagedcontacts' project(':pagedcontacts').projectDir = new File( rootProject.projectDir, '../node_modules/react-native-paged-contacts/android/') ``` * Update dependencies in `build.gradle`. ```groovy dependencies { compile fileTree(dir: 'libs', include: ['*.jar']) compile project(':pagedcontacts') // <— Add this ... } ``` (The dependency will be satisfied after `npm install` on the Example project) * Add the package `PagedContactsPackage`, to `MainApplication.java` ```java import com.wix.pagedcontacts.PagedContactsPackage; // <- Add this @Override protected List getPackages() { return Arrays.asList( new MainReactPackage(), new PagedContactsPackage() // <- Add this ); } ``` * FYI: The `READ_CONTACTS` permission will automatically be merged into your build's `AndroidManifest.xml` ```xml ``` * The `WRITE_CONTACTS` permission is needed to use `addContact` method. and should be added to your build's `AndroidManifest.xml` ```xml ``` ## API - `new PagedContacts()` — Create a paged contacts manager for all device contacts. - `new PagedContacts(nameMatch)` — Create a paged contacts manager for contacts matching the provided name. - `getAuthorizationStatus()` — Returns the current authorization status to access the contact data. - `requestAccess()` — Request contacts access from the operating system. This must be called before calling other APIs. - `setNameMatch(matchName)` — Change the result set to filter contacts by matching name. Set to `null` to receive all contacts. - `getContactsCount()` — Get the count of the current contacts set. - `getContactsWithRange(offset, batchSize, keysToFetch)` — Get contacts within the requested `batchSize`, starting from `offset`. Only the keys requested in `keysToFetch` will be provided (contact identifiers are always provided). - `getContactsWithIdentifiers(identifiers, keysToFetch)` — Get contacts with the provided `identifiers`. Only the keys requested in `keysToFetch` will be provided (contact identifiers are always provided). - `addContact(contact)` - Add a contact to the device. Fields that can be set are the same as the keys described below. [[1]](#imageUrl) - `dispose()` — Disposes the native components. Call this method when the manager object is no longer required. Must not call any other methods of the contacts manager after calling `dispose`. #### Authorization Status - `PagedContacts.notDetermined` — The user has not yet made a choice regarding whether the application may access contact data. - `PagedContacts.authorized` — The application is authorized to access contact data. - `PagedContacts.denied` — The user explicitly denied access to contact data for the application. - `PagedContacts.restricted` — The application is not authorized to access contact data. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place. #### Available Keys to Fetch - `PagedContacts.identifier` — The contact’s unique identifier. - `PagedContacts.displayName` - `PagedContacts.namePrefix` — Name prefix. - `PagedContacts.givenName` — Given name. - `PagedContacts.middleName` — Middle name. - `PagedContacts.familyName` — Family prefix. - `PagedContacts.previousFamilyName` — Previous family name. (**iOS only**) - `PagedContacts.nameSuffix` — Name suffix. - `PagedContacts.nickname` — Nickname. - `PagedContacts.organizationName` — Organization name. - `PagedContacts.departmentName` — Department name. - `PagedContacts.jobTitle` — Job title. - `PagedContacts.phoneticGivenName` — Phonetic given name. - `PagedContacts.phoneticMiddleName` — Phonetic middle name. - `PagedContacts.phoneticFamilyName` — Phonetic family name. - `PagedContacts.phoneticOrganizationName` — Phonetic organization name. - `PagedContacts.birthday` — Birthday. - `PagedContacts.nonGregorianBirthday` — Non-Gregorian birthday. (**iOS only**) - `PagedContacts.note` — Note. - `PagedContacts.imageData` — Image data. - `PagedContacts.thumbnailImageData` — Thumbnail data. - `PagedContacts.phoneNumbers` — Phone numbers. - `PagedContacts.emailAddresses` — Email addresses. - `PagedContacts.postalAddresses` — Postal addresses. - `PagedContacts.dates` — Contact dates. - `PagedContacts.urlAddresses` — URL addresses. - `PagedContacts.relations` — Contact relations. - `PagedContacts.socialProfiles` — Social profiles. (**iOS only**) - `PagedContacts.instantMessageAddresses` — Instant message addresses. ## Usage Import the library and create a new `PagedContacts` instance. ```javascript import {PagedContacts} from 'react-native-paged-contacts'; let pg = new PagedContacts(); ``` First request authorization, and, if granted, request the contacts. (**iOS only**) ```javascript pg.requestAccess().then((granted) => { if(granted !== true) { return; } pg.getContactsCount().then( (count) => { pg.getContactsWithRange(0, count, [PagedContacts.displayName, PagedContacts.thumbnailImageData, PagedContacts.phoneNumbers, PagedContacts.emailAddresses]).then((contacts) => { //Use contacts here }); }); }); ``` This is a very intensive way of obtaining specific keys of all contacts. Instead, use the paging mechanism to obtain contacts within a range, and only request keys you need. #### Example of a Contact Result ```json { "familyName": "Zakroff", "nonGregorianBirthday": "1961-12-25T22:00:00.000Z", "birthday": "1961-12-26T00:00:00.000Z", "contactRelations": [ { "label": "sister", "value": "Kate Bell" } ], "nickname": "Hanky Panky", "displayName": "Prof. Hank M. Zakroff Esq.", "organizationName": "Financial Services Inc.", "departmentName": "Legal", "namePrefix": "Prof.", "nameSuffix": "Esq.", "socialProfiles": [ { "label": "twitter", "value": { "urlString": "http:\/\/twitter.com\/HankyPanky", "username": "HankyPanky", "service": "Twitter" } }, { "label": "facebook", "value": { "urlString": "http:\/\/www.facebook.com\/HankZakoff", "username": "HankZakoff", "service": "Facebook" } } ], "dates": [ { "label": "anniversary", "value": "0001-12-01T00:00:00.000Z" }, { "label": "other", "value": "2014-09-25T00:00:00.000Z" } ], "phoneNumbers": [ { "label": "work", "value": "(555) 766-4823" }, { "label": "other", "value": "(707) 555-1854" } ], "identifier": "60CB0169-0747-4494-9F10-22F387226676", "urlAddresses": [ { "label": "homepage", "value": "https:\/\/google.com" } ], "postalAddresses": [ { "label": "work", "value": { "ISOCountryCode": "us", "state": "CA", "street": "1741 Kearny Street", "city": "San Rafael", "country": "", "postalCode": "94901" } }, { "label": "home", "value": { "ISOCountryCode": "il", "state": "", "street": "151 Jerusalem Avenue", "city": "Tel Aviv - Jaffa", "country": "Israel", "postalCode": "68152" } } ], "middleName": "M.", "jobTitle": "Partner", "note": "Best lawyer ever!", "emailAddresses": [ { "label": "work", "value": "hank-zakroff@mac.com" } ], "givenName": "Hank", "instantMessageAddresses": [ { "label": "Facebook", "value": { "service": "Facebook", "username": "HankZakoff" } }, { "label": "Skype", "value": { "service": "Skype", "username": "HZakoff" } } ] } ``` 1 : Contact's image can be set using an extra `imageUrl` field (iOS only)