# Titanium.App.iOS.UserActivity

The UserActivity module is used to enable device Handoff and to create User Activities.

Availability
5.0.0
9.2.0

# Overview

A UserActivity object requires the activityType property to be specified at creation time. Additional properties can be set either at creation or set individually after creation.

Handoff will not work in the simulator. You must build and run on a compatible device.

Handoff functionality depends on a few things:

  • You must be logged into the same iCloud account on each device you wish to use Handoff.
  • Handoff broadcasts activities via Bluetooth LE signals, so both the broadcasting and receiving devices must have Bluetooth LE 4.0 support.
  • Connect all devices to the same Wi-Fi network.

Make sure you have two devices that are logged onto the same iCloud account.

Since iOS 12, you can also configure the UserActivity API for handling Siri Shortcuts. See the below API's and example or refer to the Apple Siri Shortcuts Docs (opens new window) for details.

# Examples

# Creating a new User Activity

The following example demonstrates how to create a new UserActivity and mark the activity as the current activity Handoff should be using when switching between devices.

It is important to note that all activityTypes must be defined in your tiapp.xml before this feature can be supported. It is important to check the supported property on your UserActivity to ensure the activity created is supported on your device.

# app.js

var activity =  Ti.App.iOS.createUserActivity({
activityType: 'com.setdirection.home',
    title: 'activity 1',
    userInfo: {
        msg: 'hello world'
    }
});

if (!activity.isSupported()) {
    alert('User Activities are not supported on this device!');
} else {
    activity.becomeCurrent();

    Ti.App.iOS.addEventListener('continueactivity', function (e) {
        if (e.activityType === 'com.setdirection.home' && e.userInfo.msg) {
            alert(e.userInfo.msg);
        }
    });
}

# tiapp.xml

<ti:app>
  <ios>
    <plist>
      <dict>
        <key>NSUserActivityTypes</key>
        <array>
          <string>com.setdirection.home</string>
        </array>
      </dict>
    </plist>
  </ios>
</ti:app>

# iOS 12+ Siri Shortcuts

The following example shows how to add and delete a UserActivity for Siri Shortcuts on iOS 12 and later.

# app.js

var win = Ti.UI.createWindow({
    backgroundColor: '#fff'
});

var btn = Ti.UI.createButton({
    top: 200,
    title: 'Delete UserActivity'
});

var itemAttr = Ti.App.iOS.createSearchableItemAttributeSet({
    itemContentType: Ti.App.iOS.UTTYPE_IMAGE,
    title: 'Titanium Siri Shortcut Tutorial',
    contentDescription: 'Tech Example \nOn: ' + (new Date().toLocaleString()),
});

var activity = Ti.App.iOS.createUserActivity({
    activityType: 'com.appcelerator.titanium',
    title: 'Siri shortcut activity',
    userInfo: {
        msg: 'hello world'
    },
    eligibleForSearch: true,
    eligibleForPrediction: true,
    persistentIdentifier: 'titanium_siri_identifier'
});

activity.addContentAttributeSet(itemAttr);

if (!activity.isSupported()) {
    alert('User Activities are not supported on this device!');
} else {
    activity.becomeCurrent();

    Ti.App.iOS.addEventListener('continueactivity', function (e) {
        Ti.API.info('continueactivity called');
        if (e.activityType === 'com.appcelerator.titanium' && e.userInfo.msg) {
            alert(e.userInfo.msg);
        }
    });
}

activity.addEventListener('useractivitydeleted', function (e) {
    Ti.API.info('useractivitydeleted called');
    alert('user activity deleted');
});

btn.addEventListener('click', function () {
    activity.deleteSavedUserActivitiesForPersistentIdentifiers(['titanium_siri_identifier']);
});

win.add(btn);
win.open();

# Properties

# activityType

Availability
5.0.0
9.2.0
activityType :String

Name of the activity type.

Apple recommends using a reverse DNS scheme to name activities in the format: com...<activity_type>.

The activity type must also be registered in the ios plist section of the tiapp.xml file. Add the NSUserActivityTypes key and set its value to an array of activity type strings.

# tiapp.xml

<ti:app>
  <ios>
    <plist>
      <dict>
        <key>NSUserActivityTypes</key>
        <array>
          <string>com.fooinc.musicalpedia.playtrack</string>
        </array>
      </dict>
    </plist>
  </ios>
</ti:app>

# apiName READONLY

Availability
5.0.0
9.2.0
apiName :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, Titanium.UI.Button returns Ti.UI.Button.


# bubbleParent

Availability
5.0.0
9.2.0
bubbleParent :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.

Default: true


# eligibleForHandoff CREATION ONLY

Availability
5.0.0
9.2.0
eligibleForHandoff :Boolean

Set to true if this user activity should be eligible to be handed off to another device

Default: true


# eligibleForPrediction CREATION ONLY

Availability
7.4.0
9.2.0
eligibleForPrediction :Boolean

A Boolean value that determines whether Siri can suggest the user activity as a shortcut to the user.

To donate a user activity to Siri Shortcuts, set eligibleForPrediction to true and make the user activity current. To make the user activity current, call the becomeCurrent method of activity. For more information, see https://developer.apple.com/documentation/sirikit/donating_shortcuts?language=objc.

Default: false


# eligibleForPublicIndexing CREATION ONLY

Availability
5.0.0
9.2.0
eligibleForPublicIndexing :Boolean

Set to true if the user activity can be publicly accessed by all iOS users.

Set to true if this user activity should be eligible for indexing for any user of the application, on any device, or false if the activity contains private or sensitive information or which would not be useful to other users if indexed. You must also set either the requiredUserActivityKeys or webpageURL property.

Default: false


# eligibleForSearch CREATION ONLY

Availability
5.0.0
9.2.0
eligibleForSearch :Boolean

Set to true if the user activity should be added to the on-device index.

Default: false


# expirationDate

Availability
5.0.0
9.2.0
expirationDate :String

Absolute date after which the activity is no longer eligible to be indexed or handed off.

The date will be a string in the following format: "yyyy-MM-dd'T'HH:mm:ss.SSS'+0000'" For example, 2015-12-25T23:30:55.978+0000

Default: Determined by iOS


# keywords

Availability
5.0.0
9.2.0
keywords :Array<String>

An array of string keywords representing words or phrases that might help the user to find the activity in the application history.


# needsSave

Availability
5.0.0
9.2.0
needsSave :Boolean

Set to true everytime you have updated the user activity and need the changes to be saved before handing it off to another device.


# persistentIdentifier CREATION ONLY

Availability
7.4.0
9.2.0
persistentIdentifier :String

A value used to identify the user activity.

Set this property to a unique value that identifies the user activity so you can later delete it with Ti.App.iOS.UserActivity.deleteSavedUserActivitiesForPersistentIdentifiers method.


# requiredUserInfoKeys

Availability
5.0.0
9.2.0
requiredUserInfoKeys :Array<String>

An array of String keys from the userInfo property which represent the minimal information about the user activity that should be stored for later restoration.


# supported DEPRECATED

Availability
5.0.0
9.2.0
supported :Boolean

DEPRECATED SINCE 5.1.0

Use isSupported instead.

Determines if user activities are supported (true) or not (false) by the device.


# title

Availability
5.0.0
9.2.0
title :String

An optional, user-visible title for this activity such as a document name or web page title.


# userInfo

Availability
5.0.0
9.2.0
userInfo :Dictionary

The userInfo dictionary contains application-specific state needed to continue an activity on another device.


# webpageURL

Availability
5.0.0
9.2.0
webpageURL :String

When no suitable application is installed on a resuming device and the webpageURL property is set, the user activity will instead be continued in a web browser by loading the specified URL.

Only supports the http:// and https:// protocols. Any other protocol will throw an error.

# Methods

# addContentAttributeSet

Availability
5.0.0
9.2.0
addContentAttributeSet(contentAttributeSet) void

Adds a Titanium.App.iOS.SearchableItemAttributeSet to the user activity.

Parameters

Name Type Description
contentAttributeSet Titanium.App.iOS.SearchableItemAttributeSet

SearchableItemAttributeSet object that contains the set of properties you want to display for a searchable activity.

Returns

Type
void

# addEventListener

Availability
5.0.0
9.2.0
addEventListener(name, callback) void

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

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
5.0.0
9.2.0
applyProperties(props) void

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 Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# becomeCurrent

Availability
5.0.0
9.2.0
becomeCurrent() void

Marks the activity as currently in use by the user.

For example, you should mark the activity associated with the active window as current. A newly created activity is eligible for continuation on another device after the first time it becomes current.

Returns

Type
void

# deleteAllSavedUserActivities

Availability
7.4.0
9.2.0
deleteAllSavedUserActivities() void

Deletes all user activities created by your app.

The useractivitydeleted event is fired after deteting the user activities. Listen and wait for this event to fired to ensure that the system deletes the activities (or marks them for deletion).

Returns

Type
void

# deleteSavedUserActivitiesForPersistentIdentifiers

Availability
7.4.0
9.2.0
deleteSavedUserActivitiesForPersistentIdentifiers(persistentIdentifiers) void

Deletes user activities created by your app that have the specified persistent identifiers.

The useractivitydeleted event is fired after deteting the user activities. Listen and wait for this event to fired to ensure that the system deletes the activities (or marks them for deletion).

Parameters

Name Type Description
persistentIdentifiers Array<String>

Array of persistent identifiers of user activity.

Returns

Type
void

# fireEvent

Availability
5.0.0
9.2.0
fireEvent(name[, event]) void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# invalidate

Availability
5.0.0
9.2.0
invalidate() void

Invalidates an activity when it is no longer eligible for continuation.

For example, when the window associated with an activity is closed, you should invalidate the activity. An invalid activity cannot become current.

Returns

Type
void

# isSupported

Availability
5.0.0
9.2.0
isSupported() Boolean

Determines if user activities are supported (true) or not (false) by the device.

Returns

Returns true if the device supports user activity.

Type
Boolean

# removeEventListener

Availability
5.0.0
9.2.0
removeEventListener(name, callback) void

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 Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# resignCurrent

Availability
5.0.0
9.2.0
resignCurrent() void

Marks the activity as currently not in use and ineligible to be continued.

Returns

Type
void

# Events

# useractivitywillsave DEPRECATED

Availability
5.0.0
9.2.0

DEPRECATED SINCE 5.2.0

Set the property needsSave to true everytime you update current activity state instead.

Fired if the activity context needs to be saved before being continued on another device.

To fire the event, set the UserActiviy object's needsSave property to true.

The receiver should update the activity with current activity state.

After the event is fired, iOS will reset the needsSave property to false.

Properties

Name Type Description
activityType String

The activityType of the User Activity triggering the event.

title String

The title of the User Activity if defined.

webpageURL String

The webpageURL of the User Activity if defined.

userInfo Dictionary

Dictionary object containing the userInfo data of the User Activity.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.


# useractivitywascontinued

Availability
5.0.0
9.2.0

Fired when the user activity was continued on another device.

Properties

Name Type Description
activityType String

The activityType of the User Activity triggering the event.

title String

The title of the User Activity if defined.

webpageURL String

The webpageURL of the User Activity if defined.

userInfo Dictionary

Dictionary object containing the userInfo data of the User Activity.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.


# useractivitydeleted

Availability
7.4.0
9.2.0

Fired when the user activity get deleted using the deleteAllSavedUserActivities or deleteSavedUserActivitiesForPersistentIdentifiers methods.