This Cordova Plugin is for managing Contacts. Why use this Plugin and not the "Official" one. Well, first: it's deprectated and no more work will be done there. Second (and more important): it uses a deprecated Library in iOS.

This Plugin is in active development!

This and other Open-Source Cordova Plugins are developed in my free time. To help ensure this plugin is kept updated, new features are added and bugfixes are implemented quickly, please donate a couple of dollars (or a little more if you can stretch) as this will help me to afford to dedicate time to its maintenance. Please consider donating if you're using this plugin in an app that makes you money, if you're being paid to make the app, if you're asking for new features or priority bug fixes.

Table of Content

• Install
  • Requirements
  • Android
  • iOS
• Environment Variables
  • iOS
• Usage
  • Failure Callbacks
  • Error Codes
• Api
  • hasPermission
  • requestPermission
  • requestWritePermission
  • find
  • pick
  • save
  • delete
• Objects
  • ContactX
  • ContactXPhoneNumber
  • ContactXEmail
• Changelog

• cordova >= 9.0.0
• cordova-android >= 9.0.0
• ios >= 9
• android >= 22

This Plugin is developed in Swift and automaticaly adds the Plugin to Support Swift.

I developed it, testing with [email protected].

The iOS platform defines:

• NSContactsUsageDescription: This app requires access to the contacts to manage them.

You can easily change it, by configure your config.xml by:

<edit-config file="*-Info.plist" mode="merge" target="NSContactsUsageDescription">
    <string>your text</string>
</edit-config>

The plugin is available via a global variable named window.ContactsX. A TypeScript definition is included out of the Box. You can import it like this:

import ContactsX from 'cordova-plugin-contacts-x';

If an Error appeared this Plugin returns an Object in the failureCallback, that always has the following Structure:

{
  "code": 0,
  "message": "Some additional Info"
}

The code is one of the Error Codes and always present, while the message can be empty. This is mostly something like an Exception Message.

The following Error Codes can be fired by this Plugin:

• UnsupportedAction
• WrongJsonObject
• PermissionDenied
• UnknownError

They can be accessed over window.ContactsX.ErrorCodes and are present in the TypeScript definition too of course.

The list of available methods for this plugin is described below.

• Success Callback
• Error Callback

window.ContactsX.hasPermission(function(success) {
  console.log(success);
}, function (error) {
  console.error(error);
});

This Method returns an Object with the following field:

• read (boolean) has read permission
• write (boolean) has write permission

Apple only has one Permission, so in iOS read and write are always the same value.

Request Contact Permission

• Success Callback
• Error Callback

window.ContactsX.requestPermission(function(success) {
  console.log(success);
}, function (error) {
  console.error(error);
});

Same SuccessType as hasPermission()

Request Contact Write Permission (android only)

• Success Callback
• Error Callback

window.ContactsX.requestWritePermission(function(success) {
  console.log(success);
}, function (error) {
  console.error(error);
});

Same SuccessType as hasPermission()

Find Contacts by given options. If you don't set a field to true, it is not included or empty in the result

• Success Callback
• Error Callback
• Options:
  • fields:
    • displayName (boolean) - Android only, default: true
    • firstName (boolean) - default: true
    • middleName (boolean) - default: true
    • familyName (boolean) - default: true
    • phoneNumbers (boolean)
    • emails (boolean)

window.ContactsX.find(function(success) {
  console.log(success);
}, function (error) {
  console.error(error);
}, {
  fields: {
    phoneNumbers: true
  }
});

This Method returns an Array of ContactX.

Launches the Contact Picker to select a single contact. Currently, all available fields are returned.

• Success Callback
• Error Callback

window.ContactsX.pick(function(success) {
  console.log(success);
}, function (error) {
  console.error(error);
});

This Method returns a single ContactX object.

Save or update a contact. If you provide the id the contact will be updated. (remember to add rawId on android also).

• contact (ContactX)
• Success Callback
• Error Callback

window.ContactsX.save(
  {
    firstName: "Hans",
    familyName: "Test",
    phoneNumebers: [{
      type: "mobile",
      value: "110"
    }]
  },
  function(success) {
    console.log(success);
  },
  function (error) {
  console.error(error);
});

This Method returns the final ContactX object.

Delete a contact by id

• id (string)
• Success Callback
• Error Callback

window.ContactsX.delete("some_id",
  function(success) {
    console.log(success);
  },
  function (error) {
  console.error(error);
});

• id (string) - a unique identifier
• displayName (string) - Android only
• firstName (string)
• middleName (string)
• familyName (string)
• phoneNumbers (ContactXPhoneNumber[])
• emails (ContactXEmail[])

• id (string)
• type (string)
• value (string)

• id (string)
• type (string)
• value (string)

The full Changelog is available here