Contacts

EOL Notice

Contacts will reach its end-of-life on July 1, 2024, and will no longer receive updates or support. Please see Support Policy for additional information.

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

EOL Notice

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​

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