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

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

Installation#

Usage#

Contacts#

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#

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