Skip to main content

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:

npm install @ionic-enterprise/contactsnpx cap sync

Usage#

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

// Angularimport { 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+/TypeScriptimport { 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 JSdocument.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#

Classes#

Type aliases#


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:

NameType
Optional idundefined | string
Optional displayNameundefined | string
Optional nameContactName
Optional nicknameundefined | string
Optional phoneNumbersContactField[]
Optional emailsContactField[]
Optional addressesContactAddress[]
Optional imsContactField[]
Optional organizationsContactOrganization[]
Optional birthdayDate | string | null
Optional noteundefined | string
Optional photosContactField[]
Optional categoriesContactField[]
Optional urlsContactField[]

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:

NameTypeDescription
Optional allowEditundefined | false | truetrue 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#

new ContactAddress(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): ContactAddress

Parameters:

NameType
Optional prefundefined | false | true
Optional typeundefined | string
Optional formattedundefined | string
Optional streetAddressundefined | string
Optional localityundefined | string
Optional regionundefined | string
Optional postalCodeundefined | string
Optional countryundefined | 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:

NameType
codenumber

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:

NameType
Optional typeundefined | string
Optional valueundefined | string
Optional prefundefined | 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#

new ContactFindOptions(filter?: undefined | string, multiple?: undefined | false | true, desiredFields?: string[], hasPhoneNumber?: undefined | false | true): ContactFindOptions

Parameters:

NameType
Optional filterundefined | string
Optional multipleundefined | false | true
Optional desiredFieldsstring[]
Optional hasPhoneNumberundefined | 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#

new ContactName(formatted?: undefined | string, familyName?: undefined | string, givenName?: undefined | string, middleName?: undefined | string, honorificPrefix?: undefined | string, honorificSuffix?: undefined | string): ContactName

Parameters:

NameType
Optional formattedundefined | string
Optional familyNameundefined | string
Optional givenNameundefined | string
Optional middleNameundefined | string
Optional honorificPrefixundefined | string
Optional honorificSuffixundefined | 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#

new ContactOrganization(type?: undefined | string, name?: undefined | string, department?: undefined | string, title?: undefined | string, pref?: undefined | false | true): ContactOrganization

Parameters:

NameType
Optional typeundefined | string
Optional nameundefined | string
Optional departmentundefined | string
Optional titleundefined | string
Optional prefundefined | 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:

NameTypeDescription
Optional propertiesanyan 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:

NameTypeDescription
fieldsContactFieldType[]that should be searched
Optional optionsContactFindOptionsthat 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#

Ƭ ContactFieldType: "" | "addresses" | "birthday" | "categories" | "country" | "department" | "displayName" | "emails" | "name.familyName" | "name.formatted" | "name.givenName" | "name.honorificPrefix" | "name.honorificSuffix" | "id" | "ims" | "locality" | "name.middleName" | "name" | "nickname" | "note" | "organizations" | "phoneNumbers" | "photos" | "postalCode" | "region" | "streetAddress" | "title" | "urls"*


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