Contacts

The Contacts plugin provides access to read, write, or select device contacts.

Installation#

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

Capacitor
Cordova

npm install @ionic-enterprise/contacts
npx cap sync

Usage#

The Contacts plugin ship with a native Angular & es2015+/Typescript wrappers as well as being available on window.

// Angular
import { Contacts } from '@ionic-enterprise/contacts/ngx';
import { Contact, ContactName, ContactField  } from '@ionic-enterprise/contacts';

...

constructor(private contacts: Contacts) { }

async createContact() {
  let contact = this.contacts.create();
  contact.name = new ContactName(null, 'Smith', 'John');
  contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
  contact.save().then(
    () => console.log('Contact saved!', contact),
    (error: any) => console.error('Error saving contact.', error)
  );
}

...

// ES2015+/TypeScript
import { Contacts, Contact, ContactName, ContactField } from '@ionic-enterprise/contacts';

let contact = Contacts.create();
contact.name = new ContactName(null, 'Smith', 'John');
contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
contact.save().then(
  () => console.log('Contact saved!', contact),
  (error: any) => console.error('Error saving contact.', error)
);

...

// Vanilla JS
document.addEventListener('deviceready', () => {
  let contact = IonicContacts.create();
  contact.name = {familyName: 'Smith', givenName: 'John'};
  contact.phoneNumbers = {type: 'mobile', value: '6471234567'};
  contact.save().then(
    () => console.log('Contact saved!', contact),
    (error) => console.error('Error saving contact.', error)
  );
});

Index#

Type aliases#

ContactFieldType

Type aliases#

ContactFieldType#

Support for searching varies between platforms. iOS only supports the following types for a text search:

'name'
'emails'
'phoneNumbers'

In addition, the wildcard '*' character is required to return all contacts.

Android supports all defined fields.

Contact#

Contains information about a single contact.

Constructors#

constructor#

+ new Contact(id?: undefined | string, displayName?: undefined | string, name?: ContactName, nickname?: undefined | string, phoneNumbers?: ContactField[], emails?: ContactField[], addresses?: ContactAddress[], ims?: ContactField[], organizations?: ContactOrganization[], birthday?: Date | string | null, note?: undefined | string, photos?: ContactField[], categories?: ContactField[], urls?: ContactField[]): Contact

Parameters:

Name	Type
`id?`	undefined \| string
`displayName?`	undefined \| string
`name?`	ContactName
`nickname?`	undefined \| string
`phoneNumbers?`	ContactField[]
`emails?`	ContactField[]
`addresses?`	ContactAddress[]
`ims?`	ContactField[]
`organizations?`	ContactOrganization[]
`birthday?`	Date \| string \| null
`note?`	undefined \| string
`photos?`	ContactField[]
`categories?`	ContactField[]
`urls?`	ContactField[]

Returns: Contact

Properties#

`Optional` addresses#

• addresses? : ContactAddress[] | null

An array of all the contact's addresses.

`Optional` birthday#

• birthday? : Date | string | null

The birthday of the contact.

`Optional` categories#

• categories? : ContactField[] | null

An array of all the user-defined categories associated with the contact.

`Optional` displayName#

• displayName? : string | null

The name of this Contact, suitable for display to end users.

`Optional` emails#

• emails? : ContactField[] | null

An array of all the contact's email addresses.

`Optional` id#

• id? : string | null

A globally unique identifier.

`Optional` ims#

• ims? : ContactField[] | null

An array of all the contact's IM addresses.

`Optional` name#

• name? : ContactName | null

An object containing all components of a persons name.

`Optional` nickname#

• nickname? : string | null

A casual name by which to address the contact.

`Optional` note#

• note? : string | null

A note about the contact on Android.

`Optional` organizations#

• organizations? : ContactOrganization[] | null

An array of all the contact's organizations.

`Optional` phoneNumbers#

• phoneNumbers? : ContactField[] | null

An array of all the contact's phone numbers.

`Optional` photos#

• photos? : ContactField[] | null

An array of the contact's photos.

`Optional` rawId#

• rawId? : string | null

A globally unique identifier on Android.

`Optional` urls#

• urls? : ContactField[] | null

An array of web pages associated with the contact.

Methods#

clone#

▸ clone(): Contact

Creates a deep copy of this Contact. With the contact ID set to null.

Returns: Contact

copy of this Contact

display#

▸ display(allowEdit?: undefined | false | true): Promise‹any›

iOS only Display a contact in the native Contact Picker UI

Parameters:

Name	Type	Description
`allowEdit?`	undefined \| false \| true	true display the contact and allow editing it false (default) display contact without editing

Returns: Promise‹any›

remove#

▸ remove(): Promise‹any›

Removes contact from device storage.

Returns: Promise‹any›

save#

▸ save(): Promise‹any›

Persists contact to device storage.

Returns: Promise‹any›

Contactaddress#

Contact address.

Constructors#

constructor#

Parameters:

Name	Type
`pref?`	undefined \| false \| true
`type?`	undefined \| string
`formatted?`	undefined \| string
`streetAddress?`	undefined \| string
`locality?`	undefined \| string
`region?`	undefined \| string
`postalCode?`	undefined \| string
`country?`	undefined \| string

Returns: ContactAddress

Properties#

`Optional` country#

• country? : string | null

The country name.

`Optional` formatted#

• formatted? : string | null

The full address formatted for display.

`Optional` id#

• id? : string | null

unique identifier, should only be set by native code

`Optional` locality#

• locality? : string | null

The city or locality.

`Optional` postalCode#

• postalCode? : string | null

The zip code or postal code.

`Optional` pref#

• pref? : undefined | false | true

Set to true if this ContactAddress contains the user's preferred value.

`Optional` region#

• region? : string | null

The state or region.

`Optional` streetAddress#

• streetAddress? : string | null

The full street address.

`Optional` type#

• type? : string | null

A string indicating what type of field this is, home for example.

Contacterror#

ContactError. An error code assigned by an implementation when an error has occurred

Constructors#

constructor#

+ new ContactError(code: number): ContactError

Parameters:

Name	Type
`code`	number

Returns: ContactError

Properties#

code#

• code: number

Error code

`Optional` message#

• message? : undefined | string

Error message

`Static` INVALID_ARGUMENT_ERROR#

▪ INVALID_ARGUMENT_ERROR: number = 1

`Static` IO_ERROR#

▪ IO_ERROR: number = 4

`Static` NOT_SUPPORTED_ERROR#

▪ NOT_SUPPORTED_ERROR: number = 5

`Static` OPERATION_CANCELLED_ERROR#

▪ OPERATION_CANCELLED_ERROR: number = 6

`Static` PENDING_OPERATION_ERROR#

▪ PENDING_OPERATION_ERROR: number = 3

`Static` PERMISSION_DENIED_ERROR#

▪ PERMISSION_DENIED_ERROR: number = 20

`Static` TIMEOUT_ERROR#

▪ TIMEOUT_ERROR: number = 2

`Static` UNKNOWN_ERROR#

▪ UNKNOWN_ERROR: number = 0

Error codes

Contactfield#

Generic contact field.

Constructors#

constructor#

+ new ContactField(type?: undefined | string, value?: undefined | string, pref?: undefined | false | true): ContactField

Parameters:

Name	Type
`type?`	undefined \| string
`value?`	undefined \| string
`pref?`	undefined \| false \| true

Returns: ContactField

Properties#

`Optional` id#

• id? : string | null

unique identifier, should only be set by native code

`Optional` pref#

• pref? : undefined | false | true

Set to true if this ContactField contains the user's preferred value.

`Optional` type#

• type? : string | null

A string that indicates what type of field this is, home for example.

`Optional` value#

• value? : string | null

The value of the field, such as a phone number or email address.

Contactfindoptions#

ContactFindOptions. Search options to filter

Constructors#

constructor#

Parameters:

Name	Type
`filter?`	undefined \| string
`multiple?`	undefined \| false \| true
`desiredFields?`	string[]
`hasPhoneNumber?`	undefined \| false \| true

Returns: ContactFindOptions

Properties#

`Optional` desiredFields#

• desiredFields? : string[]

Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields.

`Optional` filter#

• filter? : undefined | string

The search string used to find navigator.contacts.

`Optional` hasPhoneNumber#

• hasPhoneNumber? : undefined | false | true

(Android only): Filters the search to only return contacts with a phone number informed.

`Optional` multiple#

• multiple? : undefined | false | true

Determines if the find operation returns multiple navigator.contacts. Defaults to false.

Contactname#

Contact name.

Constructors#

constructor#

Parameters:

Name	Type
`formatted?`	undefined \| string
`familyName?`	undefined \| string
`givenName?`	undefined \| string
`middleName?`	undefined \| string
`honorificPrefix?`	undefined \| string
`honorificSuffix?`	undefined \| string

Returns: ContactName

Properties#

`Optional` familyName#

• familyName? : string | null

The contact's family name.

`Optional` formatted#

• formatted? : string | null

The complete name of the contact.

`Optional` givenName#

• givenName? : string | null

The contact's given name.

`Optional` honorificPrefix#

• honorificPrefix? : string | null

The contact's prefix (example Mr. or Dr.)

`Optional` honorificSuffix#

• honorificSuffix? : string | null

The contact's suffix (example Esq.).

`Optional` middleName#

• middleName? : string | null

The contact's middle name.

Contactorganization#

Contact organization.

Constructors#

constructor#

Parameters:

Name	Type
`type?`	undefined \| string
`name?`	undefined \| string
`department?`	undefined \| string
`title?`	undefined \| string
`pref?`	undefined \| false \| true

Returns: ContactOrganization

Properties#

`Optional` department#

• department? : string | null

The department the contract works for.

`Optional` id#

• id? : string | null

unique identifier, should only be set by native code

`Optional` name#

• name? : string | null

The name of the organization.

`Optional` pref#

• pref? : undefined | false | true

Set to true if this ContactOrganization contains the user's preferred value.

`Optional` title#

• title? : string | null

The contact's title at the organization.

`Optional` type#

• type? : string | null

A string that indicates what type of field this is, home for example.

Contacts#

Access and manage Contacts on the device.

Methods#

create#

▸ create(properties?: any): Contact

This function creates a new contact, but it does not persist the contact to device storage. To persist the contact to device storage, invoke contact.save().

Parameters:

Name	Type	Description
`properties?`	any	an object whose properties will be examined to create a new Contact

Returns: Contact

new Contact object

find#

▸ find(fields: ContactFieldType[], options?: ContactFindOptions): Promise‹Contact[]›

Returns an array of Contacts matching the search criteria.

Parameters:

Name	Type	Description
`fields`	ContactFieldType[]	that should be searched (see platform specific notes)
`options?`	ContactFindOptions	that can be applied to contact searching

Returns: Promise‹Contact[]›

a promise that resolves with the array of Contacts matching search criteria

newContactUI#

▸ newContactUI(): Promise‹string›

iOS only Create a contact using the iOS Contact Picker UI

returns: a promise that resolves with the id of the created contact as param to successCallback

Returns: Promise‹string›

pickContact#

▸ pickContact(): Promise‹Contact›

This function picks contact from phone using contact picker UI

Returns: Promise‹Contact›

a promise that resolves with the selected Contact object

Changelog#

[1.1.2] (2020-06-10)#

Bug Fixes#

ios: Adding additional search predicates on iOS

[1.1.1] (2020-05-28)#

Bug Fixes#

ios: make wildcard return all contacts

[1.1.0] (2020-04-24)#

Features#

ios: enable wildcard fetch-all contacts

[1.0.6] (2020-02-07)#

Bug Fixes#

ios: make save work on existing contacts

[1.0.5] (2019-11-22)#

Bug Fixes#

prevent devideready block when package is not installed as plugin

[1.0.4] (2019-11-08)#

Bug Fixes#

ios: make pickContact prompt for permission if not granted

[1.0.3] (2019-11-04)#

Bug Fixes#

make plugin don't break web context

[1.0.2] (2019-10-02)#

Bug Fixes#

ios: remove contact notes code to work on iOS 13

1.0.1 (2019-09-20)#

Bug Fixes#

plugin files not included on published package

Installation#

Usage#

Index#

Classes#

Type aliases#

Type aliases#

ContactFieldType#

Contact#

Constructors#

constructor#

Properties#

Optional addresses#

Optional birthday#

Optional categories#

Optional displayName#

Optional emails#

Optional id#

Optional ims#

Optional name#

Optional nickname#

Optional note#

Optional organizations#

Optional phoneNumbers#

Optional photos#

Optional rawId#

Optional urls#

Methods#

clone#

display#

remove#

save#

Contactaddress#

Constructors#

constructor#

Properties#

Optional country#

Optional formatted#

Optional id#

Optional locality#

Optional postalCode#

Optional pref#

Optional region#

Optional streetAddress#

Optional type#

Contacterror#

Constructors#

constructor#

Properties#

code#

Optional message#

Static INVALID_ARGUMENT_ERROR#

Static IO_ERROR#

Static NOT_SUPPORTED_ERROR#

Static OPERATION_CANCELLED_ERROR#

Static PENDING_OPERATION_ERROR#

Static PERMISSION_DENIED_ERROR#

Static TIMEOUT_ERROR#

Static UNKNOWN_ERROR#

Contactfield#

Constructors#

constructor#

Properties#

Optional id#

Optional pref#

Optional type#

Optional value#

Contactfindoptions#

Constructors#

constructor#

Properties#

Optional desiredFields#

Optional filter#

Optional hasPhoneNumber#

Optional multiple#

Contactname#

Constructors#

constructor#

Properties#

Optional familyName#

Optional formatted#

`Optional` addresses#

`Optional` birthday#

`Optional` categories#

`Optional` displayName#

`Optional` emails#

`Optional` id#

`Optional` ims#

`Optional` name#

`Optional` nickname#

`Optional` note#

`Optional` organizations#

`Optional` phoneNumbers#

`Optional` photos#

`Optional` rawId#

`Optional` urls#

`Optional` country#

`Optional` formatted#

`Optional` id#

`Optional` locality#

`Optional` postalCode#

`Optional` pref#

`Optional` region#

`Optional` streetAddress#

`Optional` type#

`Optional` message#

`Static` INVALID_ARGUMENT_ERROR#

`Static` IO_ERROR#

`Static` NOT_SUPPORTED_ERROR#

`Static` OPERATION_CANCELLED_ERROR#

`Static` PENDING_OPERATION_ERROR#

`Static` PERMISSION_DENIED_ERROR#

`Static` TIMEOUT_ERROR#

`Static` UNKNOWN_ERROR#

`Optional` id#

`Optional` pref#

`Optional` type#

`Optional` value#

`Optional` desiredFields#

`Optional` filter#

`Optional` hasPhoneNumber#

`Optional` multiple#

`Optional` familyName#

`Optional` formatted#

`Optional` givenName#

`Optional` honorificPrefix#

`Optional` honorificSuffix#

`Optional` middleName#

`Optional` department#

`Optional` id#

`Optional` name#

`Optional` pref#

`Optional` title#

`Optional` type#