You are reading 12.7.1. See this page in 13.4.1.
Titanium.App.iOS.UserActivity
Extends Titanium.Proxy
The UserActivity module is used to enable device Handoff and to create User Activities.
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 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 16
activityType
StringName 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](api:Global.String)com.fooinc.musicalpedia.playtrack</string>
</array>
</dict>
</plist>
</ios>
</ti:app>
Inherited from Titanium.Proxy
The name of the API that this proxy corresponds to.
Inherited from Titanium.Proxy
Indicates if the proxy will bubble an event to its parent.
Default: true
eligibleForHandoff
BooleanSet to true if this user activity should be eligible to be handed off to another device
Default: true
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
BooleanSet 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
BooleanSet to true if the user activity should be added to the on-device index.
Default: false
expirationDate
StringAbsolute 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
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
BooleanSet to true everytime you have updated the user activity and need the changes to be saved before handing it off to another device.
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
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.
Deprecated since 5.1.0
Use Titanium.App.iOS.UserActivity.isSupported instead.
Determines if user activities are supported (true) or not (false) by the device.
title
StringAn optional, user-visible title for this activity such as a document name or web page title.
The userInfo dictionary contains application-specific state needed to continue an activity on another device.
webpageURL
StringWhen 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 11
Adds a Titanium.App.iOS.SearchableItemAttributeSet to the user activity.
| Parameters | Type | Description |
|---|---|---|
| contentAttributeSet | Titanium.App.iOS.SearchableItemAttributeSet | SearchableItemAttributeSet object that contains the set of properties you want to display for a searchable activity. |
Inherited from Titanium.Proxy
Adds the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. 4 fields
|
applyProperties
since 3.0.0Inherited from Titanium.Proxy
Applies the properties to the proxy.
| Parameters | Type | Description |
|---|---|---|
| props | Dictionary | A dictionary of properties to apply. |
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.
deleteAllSavedUserActivities
since 7.4.0Deletes all user activities created by your app.
The Titanium.App.iOS.UserActivity.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).
Deletes user activities created by your app that have the specified persistent identifiers.
The Titanium.App.iOS.UserActivity.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 | Type | Description |
|---|---|---|
| persistentIdentifiers | Array<String> | Array of persistent identifiers of user activity. |
Inherited from Titanium.Proxy
Fires a synthesized event to any registered listeners.
| Parameters | 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. |
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.
Determines if user activities are supported (true) or not (false) by the device.
Returns true if the device supports user activity.
Inherited from Titanium.Proxy
Removes the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to 4 fields
|
Marks the activity as currently not in use and ineligible to be continued.
Events 3
useractivitydeleted
since 7.4.0Fired when the user activity get deleted using the Titanium.App.iOS.UserActivity.deleteAllSavedUserActivities or Titanium.App.iOS.UserActivity.deleteSavedUserActivitiesForPersistentIdentifiers methods.
Fired when the user activity was continued on another device.
| Event properties | 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. |
useractivitywillsave
deprecatedDeprecated 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.
| Event properties | 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. |