Cordova Plugins for managing contacts
npm install cordova-plugin-contacts-xThis 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
- cordova >= 9.0.0
- cordova-android >= 9.0.0
- ios >= 9
- android >= 22
For normalization the plugin implements Google - libphonenumber
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
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:
``xml`
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:ts`
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:
`json`
{
"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.
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" | ""|
|-------------------|--------------|--------------|-----|
| +49 151 12345 | +4915112345 | +4915112345" | "" |
| (06) 123 4567 | +3161234567 | "" | "" |
| +1 (424) 555-1234 | +14245551234 | +14245551234 | "" |
| +31 (0) 6 987 654 | +316987654 | +316987654 | "" |
For context the "nationalNumber" of the Netherlands is "+31"
The list of available methods for this plugin is described below.
- Success Callback
- Error Callback
`js`
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
`js`
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
`js`
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 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.
- 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
`js`
window.ContactsX.find(function(success) {
console.log(success);
}, function (error) {
console.error(error);
}, {
fields: {
phoneNumbers: true
},
baseCountryCode : 'GB'
});
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
`js`
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
`js`
window.ContactsX.save(
{
firstName: "Hans",
familyName: "Test",
organizationName : "Einfach",
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
`js``
window.ContactsX.delete("some_id",
function(success) {
console.log(success);
},
function (error) {
console.error(error);
});
The full Changelog is available here