# Titanium.App.iOS.UserActivity
The UserActivity module is used to enable device Handoff and to create User Activities.
# 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
Name of the activity type.
Apple recommends using a reverse DNS scheme to name activities in the format: com.
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
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
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
Set to true if this user activity should be eligible to be handed off to another device
Default: true
# eligibleForPrediction CREATION ONLY
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
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
Set to true if the user activity should be added to the on-device index.
Default: false
# expirationDate
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
An array of string keywords representing words or phrases that might help the user to find the activity in the application history.
# needsSave
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
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
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
DEPRECATED SINCE 5.1.0
Use isSupported instead.
Determines if user activities are supported (true
) or not (false
) by the device.
# title
An optional, user-visible title for this activity such as a document name or web page title.
# userInfo
The userInfo dictionary contains application-specific state needed to continue an activity on another device.
# webpageURL
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
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
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
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
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
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
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
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
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
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
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 |
Returns
- Type
- void
# resignCurrent
Marks the activity as currently not in use and ineligible to be continued.
Returns
- Type
- void
# Events
# useractivitywillsave DEPRECATED
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
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
Fired when the user activity get deleted using the deleteAllSavedUserActivities or deleteSavedUserActivitiesForPersistentIdentifiers methods.