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)
  );
});

Contacts

Index

Type aliases

ContactFieldType

Classes

Contact

Contact:

Contains information about a single contact.

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
`Optional` id	`undefined` \| `string`
`Optional` displayName	`undefined` \| `string`
`Optional` name	ContactName
`Optional` nickname	`undefined` \| `string`
`Optional` phoneNumbers	ContactField[]
`Optional` emails	ContactField[]
`Optional` addresses	ContactAddress[]
`Optional` ims	ContactField[]
`Optional` organizations	ContactOrganization[]
`Optional` birthday	`Date` \| `string` \| `null`
`Optional` note	`undefined` \| `string`
`Optional` photos	ContactField[]
`Optional` categories	ContactField[]
`Optional` urls	ContactField[]

Returns: Contact

`<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.

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
`Optional` 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

ContactAddress:

Contact address.

constructor

Parameters:

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

Returns: ContactAddress

`<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:

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

constructor:

constructor

⊕ new ContactError(code: number): ContactError

Parameters:

Name	Type
code	`number`

Returns: ContactError

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

ContactField:

Generic contact field.

constructor

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

Parameters:

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

Returns: ContactField

`<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:

ContactFindOptions. Search options to filter

constructor

Parameters:

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

Returns: ContactFindOptions

`<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

ContactName:

Contact name.

constructor

Parameters:

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

Returns: ContactName

`<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

ContactOrganization:

Contact organization.

constructor

Parameters:

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

Returns: ContactOrganization

`<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

Contacts:

Access and manage Contacts on the device.

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
`Optional` 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
`Optional` 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

Type aliases

ContactFieldType

Changelog

[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
- Classes
- Type aliases
Classes
Type aliases

Installation​

Usage​

Index​

Classes​

Type aliases​

Classes​

Contact​

constructor​

<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​

clone​

display​

remove​

save​

ContactAddress​

constructor​

<Optional> country​

<Optional> formatted​

<Optional> id​

<Optional> locality​

<Optional> postalCode​

<Optional> pref​

<Optional> region​

<Optional> streetAddress​

<Optional> type​

ContactError​

constructor​

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​

constructor​

<Optional> id​

<Optional> pref​

<Optional> type​

<Optional> value​

ContactFindOptions​

constructor​

<Optional> desiredFields​

<Optional> filter​

<Optional> hasPhoneNumber​

<Optional> multiple​

ContactName​

constructor​

<Optional> familyName​

<Optional> formatted​

<Optional> givenName​

<Optional> honorificPrefix​

<Optional> honorificSuffix​

<Optional> middleName​

ContactOrganization​

constructor​

<Optional> department​

<Optional> id​

<Optional> name​

<Optional> pref​

<Optional> title​

<Optional> type​

Contacts​

create​

Installation

Usage

Index

Classes

Type aliases

Classes

Contact

constructor

`<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

clone

display

remove

save

ContactAddress

constructor

`<Optional>` country

`<Optional>` formatted

`<Optional>` id

`<Optional>` locality

`<Optional>` postalCode

`<Optional>` pref

`<Optional>` region

`<Optional>` streetAddress

`<Optional>` type

ContactError

constructor

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

constructor

`<Optional>` id

`<Optional>` pref

`<Optional>` type

`<Optional>` value

ContactFindOptions

constructor

`<Optional>` desiredFields

`<Optional>` filter

`<Optional>` hasPhoneNumber

`<Optional>` multiple

ContactName

constructor

`<Optional>` familyName

`<Optional>` formatted

`<Optional>` givenName

`<Optional>` honorificPrefix

`<Optional>` honorificSuffix

`<Optional>` middleName

ContactOrganization

constructor

`<Optional>` department

`<Optional>` id

`<Optional>` name

`<Optional>` pref

`<Optional>` title

`<Optional>` type

Contacts

create