cordova-plugin-contacts-x

ContactsX Cordova Plugin

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
  • Normalization E.164
• Api
  • hasPermission
  • requestPermission
  • requestWritePermission
  • find
  • pick
  • save
  • delete
• Objects
  • ContactX
  • ContactXPhoneNumber
  • ContactXEmail
• Changelog

Install

Requirements

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

Android

For normalization the plugin implements Google - libphonenumber

iOS

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

I developed it, testing with cordova-ios@6.1.0.

For normalization on iOS the plugin implements marmelroy - PhoneNumberKit

Environment Variables

iOS

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>

Usage

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';

Failure Callbacks

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.

Error Codes

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.

Normalization E.164

If baseCountryCode is passed as an option to the find method, the plugin attempts to resolve the normalized phone numbers in E.164 format. Setting a wrong (ISO 3166-1 alpha-2) value would cause the libary to not be able to (correctly) resolve the normalized number. Typically the value should correspond to the device (SIM) country.

Output example

Assuming that the device is from the "Netherlands", the correct baseCountryCode would be "NL".

baseCountryCode:	"NL"	"US"	""
[phone]	[phone]	[phone]"	""
[phone]	[phone]	""	""
[phone]	[phone]	[phone]	""
[phone]	[phone]	[phone]	""

For context the "nationalNumber" of the Netherlands is "+31"

Api

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

hasPermission

Parameters:

• Success Callback
• Error Callback

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

SuccessType:

This Method returns an Object with the following field:

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

Quirks

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

requestPermission

Request Contact Permission

Parameters:

• Success Callback
• Error Callback

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

SuccessType:

Same SuccessType as hasPermission()

requestWritePermission

Request Contact Write Permission (android only)

Parameters:

• Success Callback
• Error Callback

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

SuccessType:

Same SuccessType as hasPermission()

find

Find Contacts by given options. If you don't set a field in fields to true, it is not included or empty in the result. When baseCountryCode is defined (using a valid ISO 3166-1 alpha 2 code), the plugin attempts to resolve the normalized E.164 phone numbers in the phoneNumbers Array.

Parameters:

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

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

SuccessType:

This Method returns an Array of ContactX.

pick

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

Parameters:

• Success Callback
• Error Callback

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

SuccessType:

This Method returns a single ContactX object.

save

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

Parameters:

• contact (ContactX)
• Success Callback
• Error Callback

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

SuccessType:

This Method returns the final ContactX object.

delete

Delete a contact by id

Parameters:

• id (string)
• Success Callback
• Error Callback

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

Objects

ContactX

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

ContactXPhoneNumber

• id (string)
• normalized (string) if baseCountryCode is set/valid
• type (string)
• value (string)

ContactXEmail

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

Changelog

The full Changelog is available here

Changelog

2.1.2 (2023-05-04)

Bug Fixes

• ios: declare error codes enum within main class (1d83826)