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

ionic cordova plugin add @ionic-enterprise/contacts

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

Usage
Index
Changelog

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​

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