Search docs/
Getting StartedNative SolutionsPremier Plugins

Contacts

v1.1.2

The Contacts plugin provides access to read, write, or select device 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)
  );
});
CopyCopied

Index

Classes

Type aliases

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"*

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

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

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

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

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

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

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

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

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

Other Versions