Skip to content
Titanium SDK
Version12.6.1

You are reading 12.6.1. See this page in 13.4.1.

Titanium.App.iOS.UserActivity

proxyiPhoneiPadmacOSsince 5.0.0

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

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](api:Global.String)com.fooinc.musicalpedia.playtrack</string>
        </array>
      </dict>
    </plist>
  </ios>
</ti:app>

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

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

Default: true

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

Default: true

eligibleForPrediction

Booleansince 7.4.0

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

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

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

Default: false

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

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

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

Stringsince 7.4.0

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.

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.

title

String

An 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.

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 11

Inherited from Titanium.Proxy

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

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to invoke when the event is fired.

4 fields
bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

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.

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
ParametersTypeDescription
persistentIdentifiersArray<String>

Array of persistent identifiers of user activity.

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
ParametersTypeDescription
nameString

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 Boolean

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
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

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

4 fields
bubbles Boolean

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

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

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

Events 3

Fired when the user activity was continued on another device.

Event properties
Event propertiesTypeDescription
activityTypeString

The activityType of the User Activity triggering the event.

titleString

The title of the User Activity if defined.

webpageURLString

The webpageURL of the User Activity if defined.

userInfoDictionary

Dictionary object containing the userInfo data of the User Activity.

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.

Event properties
Event propertiesTypeDescription
activityTypeString

The activityType of the User Activity triggering the event.

titleString

The title of the User Activity if defined.

webpageURLString

The webpageURL of the User Activity if defined.

userInfoDictionary

Dictionary object containing the userInfo data of the User Activity.