Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wix-incubator/react-native-paged-contacts

Paged contacts for React Native
https://github.com/wix-incubator/react-native-paged-contacts

android contacts ios react-native

Last synced: 2 months ago
JSON representation

Paged contacts for React Native

Host: GitHub
URL: https://github.com/wix-incubator/react-native-paged-contacts
Owner: wix-incubator
License: mit
Created: 2016-11-24T10:17:34.000Z (about 8 years ago)
Default Branch: master
Last Pushed: 2023-09-03T17:44:17.000Z (over 1 year ago)
Last Synced: 2024-11-06T18:15:48.389Z (3 months ago)
Topics: android, contacts, ios, react-native
Language: Java
Size: 299 KB
Stars: 80
Watchers: 277
Forks: 24
Open Issues: 13
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# 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.imageUri` — Image uri. (**Android only**)
- `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": "[email protected]"
}
],
"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)