Starting with iOS 8.0 and Titanium SDK 5.0, you can use the Handoff feature to transfer a user activity from one device to another. Handoff lets you start using an application, such as editing a document, on one device, then transfer to another device to continue working on it. Both devices will need to share the same iCloud account and Wi-Fi connection as well as be Bluetooth enabled.
Note that you can only test handoff on device. You cannot test handoff on the iOS simulator.
To use handoff, both devices must:
- Be logged into the same iCloud account
- Be on the same Wi-Fi network
- Have Bluetooth enabled
- Have Handoff enabled
For detailed instructions, see Apple Support: Use Continuity to connect your iPhone, iPad, iPod touch, and Mac.
To test if Handoff is working, open Safari on one device and navigate to a specific web page. On the other device, go to the locked screen. You should see a Safari icon in the bottom-left corner. Tap on the Safari icon and swipe up. Safari should open to the same web page.
Share an Activity
To share an Activity, create an UserActivity object and set it as the current activity. You will also need to register the activity in the plist section of the
tiapp.xml file to use it.
To create an Activity, use the Titanium.App.iOS.createUserActivity() method. Pass the method a dictionary with following properties defined. The
activityType property is the only required property.
activityType: developer-defined string used as the activity type for the user activity. The activity type must be registered in the plist section of the
tiapp.xmlfile to use it.
eligibleForHandOff: set to
trueto allow the activity to be handed off to another device. Default is true. Requires iOS 9.0 or later.
eligibleForPublicIndexing: set to
trueto allow the activity to be indexed publicly allowing it to be search by all users. Must also set the
webpageURLproperties. Default is false. Requires iOS 9.0 or later.
eligibleForSearch: set to
trueto allow the activity to be added to the on-device index. Default is false. Requires iOS 9.0 or later.
expirationDate: date that the activity expires in the format:
yyyy-MM-ddTHH:mm:ss.SSS+0000. If not set, the OS will determine the expiration time.
keywords: array of strings that a user can use to find the activity in Spotlight. You can also use the UserActivity object's
addContentAttributeSet()method to add indexable content. Both APIs require iOS 9.0 or later.
requiredUserInfoKey: array of keys that need to be sent in the
userInfoobject. Requires iOS 9.0 or later.
title: user-visible title for the activity, such as a document name or webpage URL.
userInfo: object of key-value pairs to send with the activity
webpageURL: if a suitable application is not found on the device, loads the specified web page and continues the activity in the browser. Only supports the
https://protocols. Any other protocol will throw an error.
Once you are ready to share the activity, use the
supported property to check if the user activity is supported by the application, then invoke its
becomeCurrent() method to indicate that the activity is in use by the current device.
Before using the activity, you will need to register each activity type in the
plist section of the
tiapp.xml file. Under the
<dict> element in the
<ios><plist> elements, add the
NSUserActivityTypes key with the value set to an array of strings, where each string is the
activityType property that you want the application to support.
Monitor the Activity
Listen for the
useractivitywascontinued event to determine when the user activity was handed off to another device. The event will be passed the
webpageURL properties that were set on the user activity.
Update the Activity
Every time something happens that requires the activity's state to be updated before it could be handed off, set the UserActivity object's
needsSave property to
true. Listen for the
useractivitywillsave event to actually update the activity state or content, such as saving changes to an API. This event is triggered at the discretion of iOS and when you call
becomCurrent(). The event will be passed the current
webpageURL properties. After the event is fired, iOS will reset the
needsSave property to false.
Continue the Activity
To continue the activity on another paired device, listen for the
event. The handoff event will be passed the
webpageURL properties that were set on the user activity. Use the passed information to continue the activity.
Test the Sample
To test the code above, make sure you have both iOS devices setup as described in the "Device Setup" section. Copy and paste both
app.js snippets to one file and add the
NSUserActivityTypes key to the
tiapp.xml. Run the project on two iOS devices.
Before launching the application, have the lock screen on for the first device, then on the second device, launch the application. On the lock screen of the first device, the application icon should appear in the bottom-left corner.
Tap the icon and drag up to open the application on the first device. You should see an alert dialog with the message: "Tag! You're it!"