Your best friend when working with the latest and greatest Contacts Framework in iOS 9+.

Requires iOS 9+

Apple recently did a complete overhaul of their Contacts Framework that does a number of things, including:

1. Making it simpler to use the framework.

2. Use the same framework across all their platforms, including iOS, tvOS, watchOS and even OS X.

3. Get unified Contact details not only from a User's local Contact entry, but also from the user's social accounts, like Facebook and Twitter. This allows you to get a Facebook profile picture for a Contact you have in your contact database.

There are a couple of react native packages that give you access to Contacts already (react-native-contacts and react-native-addressbook) but neither of them utilize the new Unified Contacts framework available in iOS 9+. For good reason too, as most people are still supporting devices that are pre-iOS 9.

However, if you have the luxury of supporting iOS 9 and up, you should definitely use this library to make use of this great new framework by Apple.

Installation

1. Install the npm package:

npm install --save react-native-unified-contacts

This will install the latest react-native-unified-contacts package and add it to your package.json file.

2. In Xcode, click the "Add Files to ":

3. Navigate to <your-project-directory>/node_modules/react-native-unified-contacts/ and click on the RNUnifiedContacts directory:

Usage

Require Library

var Contacts  = require('react-native-unified-contacts');

Getting Contacts

Get a Single Contact

let contactIdentifier = 'A7806266-6574-4731-82E1-C54946F63E1C';

Contacts.getContact( contactIdentifier, (error, contact) =>  {
  if (error) {
    console.error(error);
  }
  else {
    console.log(contact);
  }
});

Get All Contacts

Contacts.getContacts( (error, contacts) =>  {
  if (error) {
    console.error(error);
  }
  else {
    console.log(contacts);
  }
});

Search All Contacts

Contacts.searchContacts( 'Don Draper', (error, contacts) =>  {
  if (error) {
    console.error(error);
  }
  else {
    console.log(contacts);
  }
});

This will search the given (first) and family (last) name of all of the Contacts for the provided string. Future versions will allow you to search other fields as well, like phone or email.

Adding Contacts

Add a Single Contact

let contactData = {
  'givenName':        'John',
  'familyName':       'Appleseed',
  'organizationName': 'Apple Inc',
  'phoneNumbers': [
    {'label': Contacts.phoneNumberLabel.HOME, 'stringValue': '555-522-8243'},
    {'label': Contacts.phoneNumberLabel.WORK, 'stringValue': '(408) 555-5270'},
  ],
  'emailAddresses': [
    {'label': Contacts.emailAddressLabel.WORK, 'value': 'john.appleseed@apple.com'},
    {'label': Contacts.emailAddressLabel.HOME, 'value': 'john@gmail.com'},
  ],
}

Contacts.addContact( contactData, (error, success) => {
  if (error) {
    console.log(error);
  }
  else {
    console.log(success);
  }
});

Updating Contacts

Update a Single Contact

let contactIdentifier = 'A7806266-6574-4731-82E1-C54946F63E1C';

let contactData = {
  'givenName':        'John',
  'familyName':       'Appleseed',
  'organizationName': 'Apple Inc',
  'phoneNumbers': [
    {'label': Contacts.phoneNumberLabel.HOME, 'stringValue': '555-522-8243'},
    {'label': Contacts.phoneNumberLabel.WORK, 'stringValue': '(408) 555-5270'},
  ],
  'emailAddresses': [
    {'label': Contacts.emailAddressLabel.WORK, 'value': 'john.appleseed@apple.com'},
    {'label': Contacts.emailAddressLabel.HOME, 'value': 'john@gmail.com'},
  ],
}

Contacts.updateContact(contactIdentifier, contactData, (error, success) => {
  if (error) {
    console.log(error);
  }
  else {
    console.log(success);
  }
});

NOTE: If your contactData includes the keys phoneNumbers or emailAddresses, the associated value will completely replace any Phone Numbers or Email Addresses for that Contact, respectively. In other words, if you have a contact with two Phone Numbers and you'd like to add a third, you need to pass in ALL THREE Phone Numbers, not just the new one. Same goes for Email Addresses.

Deleting Contacts

Delete a Single Contact

let contactIdentifier = 'A7806266-6574-4731-82E1-C54946F63E1C';

Contacts.deleteContact( contactIdentifier, (error, success) => {
  if (error) {
    console.log(error);
  }
  else {
    console.log(success);
  }
}

Accessing the User's Contacts

Can The User Access Contacts?

Contacts.userCanAccessContacts( (userCanAccessContacts) => {
  if (userCanAccessContacts) {
    console.log("User has access to Contacts!");
  }
  else {
    console.log("User DOES NOT have access to Contacts!");
  }
});

This will not request access. For that, use the requestAccessToContacts.

Request Access To Contacts

Contacts.requestAccessToContacts( (userCanAccessContacts) => {
  if (userCanAccessContacts) {
    console.log("User has access to Contacts!");
  }
  else {
    console.log("User DOES NOT have access to Contacts!");
  }
});

This will do everything you'd expect. Here's the workflow:

1. Does the user already have access to Contacts?

   1. Yes. Return true.

   2. No.

   3. If the User has not been asked before (first time asking), prompt user for access:

   1. Yes. Return `true`.
   
   2. No. Return `false`.
   

   2. If user has already denied access to Contacts, return false.

      The user will have to go to their privacy settings and allow access manually. We provide a openPrivacySettings method that allows you to bring up the privacy page easily for the user. See below.

Open the User's Privacy Settings

Contacts.openPrivacySettings()

In the event that the User has denied access to their Contacts, you will need to have them manually change their setting in the privacy page. This method will open up the right page automatically for them and improves the experience for the user.

Here's an example of how you might alert the user that they need to update their privacy settings:

// Alert the User that we can't access their Contact.
// Provide a link that will open up their Privacy Settings for ntwrk.
//
function alertUserToAllowAccessToContacts() {
  Alert.alert(
    "Can't Access Your Contacts",
    "Click on Open Settings and allow ntwrk to access your Contacts.\n" +
    "\n" +
    "Then come back!",
    [
      {text: 'Open Settings', onPress: () => Contacts.openPrivacySettings() },
      {text: "Later"}
    ]
  )
}

This will produce an alert similar to this:

Contact Object

The returned Contact object(s) will look something like this:

{
  familyName: "Draper",
  givenName:  "Donald",
  identifier: "A7806266-6574-4731-82E1-C54946F63E1C",
  imageDataAvailable: false,
  phoneNumbers: [
    {
      countryCode: "us",
      digits:      "4032694148",
      identifier:  "9CDE4C1B-412F-4974-BE8D-80C951004694",
      label:       "work",
      stringValue: "(403) 269-4147"  
    },
    {
      countryCode: "us",
      digits:      "4036071713",
      identifier:  "40477249-B50B-46A8-BF35-0A62B895A15A",
      label:       "mobile",
      stringValue: "(403) 607-1713"  
    }  
  ],
  emailAddresses: [
    {
      identifier: "9CDE4C1B-412F-4974-BE8D-80C951004694",
      label:      "work",
      value:      "don.draper@scdp.com"
    },
    {
      identifier: "9CDE4C1B-412F-4974-BE8D-80C951004694",
      label:      "home",
      value:      "theonedon@gmail.com"
    }
  ],
  postalAddresses: [
    {
      city:        "Menlo Park",
      country:     "United States",
      identifier:  "7481D15D-C27C-4805-876F-D2C0D413CEBD",
      label:       "work",
      postalCode:  "94025",
      state:       "CA",
      street:      "3000 Sand Hill Road, 3-290"
      stringValue: "3000 Sand Hill Road, 3-290.↵Menlo Park CA 94025↵"
    }
  ],
  birthday: [
    {
      day:   "15",
      month: "4",
      year:  "1985"
    }
  ],
  note: "What you call love was invented by guys like me … to sell nylons."
}

NOTE: The birthday key will not be included if the Contact's birthday is not set. Also, it's possible for a Contact's birthday to not include the year. In this case, year will be null.

Thumbnail Image

Thumbnail Image Data is stored in a base64 format and can easily be used with the Image component of React Native as follows:

// contact is a single Contact record retrieved from something like Contacts.getContacts().
var base64ImageUri = 'data:image/png;base64,' + contact.thumbnailImageData;

<Image source={{uri: base64ImageUri}}/>

Many Thanks To

• My friend Smixx for working through adding a Swift library to a React Native project over his lunch hour.
• Ismail Pelaseyed (homanp) for adding a couple of huge PRs for Creating, Updating and Deleting Contacts.

TODO

• Add Create/Update/Delete methods for Contacts. (Thanks homanp!)
• Add Android support.
• Add integration with Contacts-UI (Coming Soon!).

License

The MIT License (MIT)

Copyright 2016 - Time.now() by Joshua Pinter