Titanium.Contacts

The top-level Contacts module, used for accessing and modifying the system contacts address book.

See examples for more information.

iOS Platform Notes

On iOS, the contacts database may be modified by an external application, causing any Person or Group objects you've retrieved to be out of sync with the database. The IDs of these objects are not guaranteed to remain the same, so updating an object when it is out of sync may have unpredictable results.

To avoid this, listen for the reload event. When you receive a reload event, you should assume that any existing Person or Group objects are invalid and reload them from the Contacts module before modifying them.

See the examples for a sample use of the reload event.

If 'ABAddressBookErrorDomain error 0' occurs, it implies that you are not allowed to add or edit certain fields. Check your default account in the iOS settings under contacts. If it's not 'iCloud', most likely it will not support fields such as alternateBirthday or socialProfile.

These APIs are unavailable on macOS if the app is built on a version of Xcode < 12.

Extends: Titanium.Module · Since: 0.8, 0.8, 0.8, 9.2.0 · Platforms: android, iphone, ipad, macos

Properties #

apiName#

extended

Type: String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.

AUTHORIZATION_AUTHORIZED#

Type: Number

A contactsAuthorization value
indicating that the application is authorized to use the address book.

This value is always returned on Android devices, as well as on iOS versions earlier than 6.0.

AUTHORIZATION_DENIED#

Type: Number

A contactsAuthorization value
indicating that the application is not authorized to use the address book.

AUTHORIZATION_UNKNOWN#

Type: Number

A contactsAuthorization value
indicating that the authorization state is unknown.

bubbleParent#

extended

Type: Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often
established by the add() method. For example, for a button added to a window, a
click event on the button would bubble up to the window. Other common parents are
table sections to their rows, table views to their sections, and scrollable views
to their views. Set this property to false to disable the bubbling to the proxy's parent.

CONTACTS_KIND_ORGANIZATION#

Type: Number

Specifies that a contact is an organization.

Used with the Titanium.Contacts.Person.kind property.

One of the group of contact "kind" constants
CONTACTS_KIND_ORGANIZATION,
and CONTACTS_KIND_PERSON.

CONTACTS_KIND_PERSON#

Type: Number

Specifies that a contact is a person.

Used with the Titanium.Contacts.Person.kind property.
One of the group of contact "kind" constants CONTACTS_KIND_ORGANIZATION, and CONTACTS_KIND_PERSON.

CONTACTS_SORT_FIRST_NAME#

Type: Number

Specifies that group members will be sorted by first name.

Used with the Titanium.Contacts.Group.sortedMembers method.
One of the group of contact group "sort" constants CONTACTS_SORT_FIRST_NAME, and CONTACTS_SORT_LAST_NAME.

CONTACTS_SORT_LAST_NAME#

Type: Number

Specifies that group members will be sorted by last name.

Used with the Titanium.Contacts.Group.sortedMembers method.
One of the group of contact group "sort" constants CONTACTS_SORT_FIRST_NAME, and CONTACTS_SORT_LAST_NAME.

contactsAuthorization#

Type: Number

Returns an authorization constant indicating if the application has access to the address book.

Always returns AUTHORIZATION_AUTHORIZED on iOS pre-6.0 and Android devices.

If contactsAuthorization is AUTHORIZATION_RESTRICTED, you should not
attempt to re-authorize: this will lead to issues.

includeNote#

Type: Boolean

A boolean value that indicates whether to fetch the notes stored in contacts or not.

This property need to be set before calling contacts APIs.
From iOS 13 or later if your app fetch note field from contact, the app must have to set key 'com.apple.developer.contacts.notes' to 'true' in entitlements section of tiapp.xml.

<key>com.apple.developer.contacts.notes</key>
<true/>

See more details at https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_contacts_notes and https://developer.apple.com/contact/request/contact-note-field.

lifecycleContainer#

extended

Type: Titanium.UI.Window, Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.

Methods #

addEventListener #

extended

Adds the specified callback as an event listener for the named event.

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to invoke when the event is fired.	No

applyProperties #

extended

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that
myproxy[key] = value.

Parameters:

Name	Type	Summary	Optional
`props`	`Dictionary`	A dictionary of properties to apply.	No

createGroup #

Creates and returns an instance of Titanium.Contacts.Group.

This method must be followed by Titanium.Contacts.save to commit its changes.

Parameters:

Name	Type	Summary	Optional
`parameters`	`Dictionary<Titanium.Contacts.Group>`	Properties to set on a new object, including any in Titanium.Contacts.Group except those marked as non-creation or read-only.	Yes

Returns: Titanium.Contacts.Group

createPerson #

Creates and returns an instance of Titanium.Contacts.Person, and commits all pending
changes to the underlying contacts database.

Parameters:

Name	Type	Summary	Optional
`parameters`	`Dictionary<Titanium.Contacts.Person>`	Properties to set on a new object, including any in Titanium.Contacts.Person except those marked as non-creation or read-only.	Yes

Returns: Titanium.Contacts.Person

fireEvent #

extended

Fires a synthesized event to any registered listeners.

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`event`	`Dictionary`	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.	Yes

getAllGroups #

Gets all groups.

Returns: Array<Titanium.Contacts.Group>

getAllPeople #

Gets all people, unless a limit is specified.

Parameters:

Name	Type	Summary	Optional
`limit`	`Number`	Maximum number of people. Android only.	No

Returns: Array<Titanium.Contacts.Person>

getGroupByIdentifier #

Gets the group with the specified identifier.

Parameters:

Name	Type	Summary	Optional
`id`	`String`	Group identifier.	No

Returns: Titanium.Contacts.Group

getPeopleWithName #

Gets people with a firstName, middleName or lastName field, or a combination
of these fields, that match the specified name.

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name to match.	No

Returns: Array<Titanium.Contacts.Person>

getPersonByIdentifier #

Gets the person with the specified identifier.

Parameters:

Name	Type	Summary	Optional
`id`	`Number`	Contact identifier.	No

Returns: Titanium.Contacts.Person

hasContactsPermissions #

Returns true if the app has contacts access.

Returns: Boolean

removeEventListener #

extended

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function
in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters:

Name	Type	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to remove. Must be the same function passed to `addEventListener`.	No

removeGroup #

Removes a group from the address book.

This method must be followed by Titanium.Contacts.save to commit its changes.

Parameters:

Name	Type	Summary	Optional
`group`	`Titanium.Contacts.Group`	Contact group.	No

removePerson #

Removes a contact from the address book.

On iOS:

This method must be followed by a save action to commit the data to the underlying database,
which can be done explicitly using Titanium.Contacts.save or implicitly using
Titanium.Contacts.createPerson. Although the Titanium.Contacts.Person object will still
exist once committed, it will no longer be valid. Continuing to use it will result in
unpredictable behavior, including crashes.

On Android:

This method will remove the person from the Contacts book automatically.

Parameters:

Name	Type	Summary	Optional
`person`	`Titanium.Contacts.Person`	Contact.	No

requestContactsPermissions #

Requests for contacts access.

On Android, the request view will show if the permission is not accepted by the user, and the user did
not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again,"
the user has to manually enable the permission in device settings.

This method requests Manifest.permission.READ_CONTACTS and Manifest.permission.WRITE_CONTACTS on Android.
If you require other permissions, you can also use Titanium.Android.requestPermissions.

In iOS 6, Apple introduced the Info.plist key NSContactsUsageDescription that is used to display an
own description while authorizing contacts permissions. In iOS 10, this key is mandatory and the application
will crash if your app does not include the key. Check the Apple docs for more information.

Parameters:

Name	Type	Summary	Optional
`callback`	`Callback<ContactsAuthorizationResponse>`	Function to call upon user decision to grant contacts access. Optional on SDK 10, as this method will return a `Promise`, which may be used to handle the result.	Yes

Returns: Promise<ContactsAuthorizationResponse> — On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.

save #

Commits all pending changes to the underlying contacts database.

On Android:

Takes an array of Titanium.Contacts.Person objects and saves changes for
the specified contacts only.

Parameters:

Name	Type	Summary	Optional
`contacts`	`Array<Titanium.Contacts.Person>`	List of contacts to save. Used on Android only.	No

showContacts #

Displays a picker that allows a person to be selected.

Parameters:

Name	Type	Summary	Optional
`params`	`showContactsParams`	Argument containing parameters for this method. Optional on Android.	No

Events #

reload #

Fired when the database backing the contacts module is modified externally.

If you have an existing reference to a Person or Group object, you should obtain
a new reference from the Contacts module. Using the existing object may result
in unpredictable behavior, such as updating the wrong contact.

Examples #

Request access to the address book

var performAddressBookFunction = function(){...};
var addressBookDisallowed = function(){...};
if (Ti.Contacts.hasContactsPermissions()) {
    performAddressBookFunction();
} else {
    Ti.Contacts.requestContactsPermissions(function(e) {
        if (e.success) {
            performAddressBookFunction();
        } else {
            addressBookDisallowed();
        }
    });
}

Query Existing System Address Book Records

Output to the console all properties of all people.

var singleValue = [
  'recordId', 'firstName', 'middleName', 'lastName', 'fullName', 'prefix', 'suffix',
  'nickname', 'firstPhonetic', 'middlePhonetic', 'lastPhonetic', 'organization',
  'jobTitle', 'department', 'note', 'birthday', 'created', 'modified', 'kind'
];
var multiValue = [
  'email', 'address', 'phone', 'instantMessage', 'relatedNames', 'date', 'url'
];
var people = Ti.Contacts.getAllPeople();
Ti.API.info('Total contacts: ' + people.length);
for (var i=0, ilen=people.length; i<ilen; i++){
  Ti.API.info('---------------------');
  var person = people[i];
  for (var j=0, jlen=singleValue.length; j<jlen; j++){
    Ti.API.info(singleValue[j] + ': ' + person[singleValue[j]]);
  }
  for (var j=0, jlen=multiValue.length; j<jlen; j++){
    Ti.API.info(multiValue[j] + ': ' + JSON.stringify(person[multiValue[j]]));
  }
}

Add New System Address Book Records

Create two new records in the system address book. Note that the <Titanium.Contacts.Person> object is queried in the same way that it is created (as shown in the previous example.)

Ti.API.info('Saving contact...');
Ti.Contacts.createPerson({
  firstName: 'Paul',
  lastName: 'Dowsett',
  address:{
    work:[
      {
        CountryCode: 'gb', // determines how the address is displayed
        Street: '200 Brook Drive\nGreen Park',
        City: 'Reading',
        County: 'Berkshire',
        Country: 'England',
        ZIP: 'RG2 6UB'
      },
      {
        CountryCode: 'gb', // determines how the address is displayed
        Street: '1 St Pauls Road\nClerkenwell',
        City: 'City of London',
        State: 'London',
        Country: 'England',
        ZIP: 'EC1 1AA'
      }
    ],
    home:[
      {
        CountryCode: 'gb', // determines how the address is displayed
        Street: '2 Boleyn Court',
        City: 'London',
        State: 'Greenwich',
        Country: 'England',
        ZIP: 'SE10'
      }
    ]
  },
  birthday: '2012-01-01T12:00:00.000+0000',
  instantMessage:{
    home:[
      {
        service: 'AIM',
        username: 'leisureAIM'
      },
      {
        service: 'MSN',
        username: 'no_paul_here@msn.com'
      }
    ],
    work:[
      {
        service: 'AIM',
        username: 'seriousAIM'
      }
    ]
  },
  organization: 'Appcelerator',
  phone:{
    mobile: ['07900 000001', '07900 000002'],
    work: ['+44 (0)118 925 6128', '+44 (0)118 000 0000']
  },
  url:{
    homepage: ['www.google.com'],
    work: ['www.titaniumsdk.com', 'www.example.com']
  }
});
Ti.API.info('Contact saved');

Ti.API.info('Saving contact...');
var workAddress1 = {
  'CountryCode': 'us',
  'Street':  '440 N. Bernardo Avenue',
  'City': 'Mountain View',
  'State': 'California',
  'Country': 'United States',
  'ZIP': '94043'
};

Ti.Contacts.createPerson({
  firstName:'Arthur',
  lastName:'Evans',
  address:{
    'work':[workAddress1]
  }
});
Ti.API.info('Contact saved');

Repopulate contact data if it was modified externally

Listen for the `reload` event to repopulate the contact data if it was modified externally, for example, in the iOS Contacts app.

var win = Ti.UI.createWindow();
var table = Ti.UI.createTableView();

// Repopulate contact data
function reloadContacts() {
    var contacts = Ti.Contacts.getAllPeople();
    var data = [];
    for (var i = 0; i < contacts.length; i++) {
        var title = contacts[i].fullName;
        if (!title || title.length === 0) {
            title = "(no name)";
        }
        var row = Ti.UI.createTableViewRow({
            title: title
        });
        data.push(row);
    }
    table.data = data;
}

Ti.Contacts.addEventListener('reload', function(e){
    alert('Reloading contacts. Your contacts were changed externally!');
    reloadContacts();
});

// initial call to populate contact data
reloadContacts();

win.add(table);
win.open();

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Titanium.Contacts ​

iOS Platform Notes ​

Properties #

apiName#

AUTHORIZATION_AUTHORIZED#

AUTHORIZATION_DENIED#

AUTHORIZATION_UNKNOWN#

bubbleParent#

CONTACTS_KIND_ORGANIZATION#

CONTACTS_KIND_PERSON#

CONTACTS_SORT_FIRST_NAME#

CONTACTS_SORT_LAST_NAME#

contactsAuthorization#

includeNote#

lifecycleContainer#

Methods #

addEventListener #

applyProperties #

createGroup #

createPerson #

fireEvent #

getAllGroups #

getAllPeople #

getGroupByIdentifier #

getPeopleWithName #

getPersonByIdentifier #

hasContactsPermissions #

removeEventListener #

removeGroup #

removePerson #

requestContactsPermissions #

save #

showContacts #

Events #

reload #

Examples #

Titanium.Contacts

iOS Platform Notes