Merge pull request #6942 from benbahrenburg/TIMOB-19016-1

TIMOB-19016 : Handoff for iOS8 & iOS9

apidoc/Titanium/App/iOS/UserActivity.yml

@@ -0,0 +1,183 @@
+---
+name: Titanium.App.iOS.UserActivity
+description: |
+    The UserActivity module is used to enable device Handoff and to create User Activites first introduced in iOS8 and the CoreSpotLight feature 
+    introduced in iOS9.  UserActivity requires the activityType to be specified at creation time.  Additional properties can be
+    created 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 few things:
+        * You must be logged in to 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.
+        * Devices should have been already paired through iCloud. Make sure you login using the same iCloud account.
+
+    Make sure you have two Handoff compatible devices running iOS 8 or later that are logged onto the same iCloud account.
+
+extends: Titanium.Proxy
+platforms: [iphone,ipad]
+since: "4.3.0"
+createable: true
+properties:
+  - name: activityType
+    summary: The activityType the user activity was created with.
+    type: String
+    availability: creation
+    osver: {ios: {min: "8.0"}}
+    platforms: [iphone,ipad]
+  - name: title
+    summary: An optional, user-visible title for this activity such as a document name or web page title.
+    type: String
+    osver: {ios: {min: "8.0"}}
+    platforms: [iphone,ipad] 
+  - name: userInfo
+    summary: The userInfo dictionary contains application-specific state needed to continue an activity on another device.
+    type: Dictionary
+    osver: {ios: {min: "8.0"}}
+    platforms: [iphone,ipad] 
+  - name: webpageURL
+    summary: When no suitable application is installed on a resuming device and the webPageURL is set the user activity will instead be continued in a web browser by loading this resource.
+    type: String
+    osver: {ios: {min: "8.0"}}
+    platforms: [iphone,ipad]
+  - name: needsSave
+    summary: If set to true then this user activity will receive a useractivitywillsave event before being sent for continuation on another device.
+    type: Boolean
+    osver: {ios: {min: "8.0"}}
+    platforms: [iphone,ipad]    
+  - name: keyWords
+    summary: An array of String keywords representing words or phrases that might help the user to find this activity in the application history.
+    type: Array<String>
+    osver: {ios: {min: "9.0"}}
+    platforms: [iphone,ipad] 
+  - name: requiredUserInfoKeys
+    summary: An array of String keys from the userInfo property which represent the minimal information about this user activity that should be stored for later restoration.
+    type: Array<String>
+    osver: {ios: {min: "9.0"}}
+    platforms: [iphone,ipad]     
+  - name: eligibleForPublicIndexing
+    summary: A local URL to a JavaScript file containing the code to run in the background.
+    type: Boolean
+    osver: {ios: {min: "9.0"}}
+    platforms: [iphone,ipad] 
+  - name: eligibleForSearch
+    summary: Set to true if this user activity should be eligible for indexing for any user of this application
+    description: |
+        Set to true if this user activity should be eligible for indexing for any user of this 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.  The activity must also have requiredUserActivityKeys or a webpageURL
+    type: Boolean
+    osver: {ios: {min: "9.0"}}
+    platforms: [iphone,ipad]
+  - name: eligibleForHandoff
+    summary: Set to true if this user activity should be eligible to be handed off to another device
+    type: Boolean
+    osver: {ios: {min: "9.0"}}
+    platforms: [iphone,ipad] 
+  - name: expirationDate
+    summary: Absolute date after which this activity is no longer eligible to be indexed or handed off.
+    description: |
+        Absolute date after which this activity is no longer eligible to be indexed or handed off.
+
+        When setting this property the Date format accepted is: "_yyyy_-_MM_-_dd_**T**_HH_**:**_mm_**:**_ss_**.**_SSS_**+0000**"
+
+        When reading this property Date values will be returned as String in the format: "_yyyy_-_MM_-_dd_**T**_HH_**:**_mm_**:**_ss_**.**_SSS_**+0000**"
+
+    type: String
+    osver: {ios: {min: "9.0"}}
+    platforms: [iphone,ipad] 
+methods:
+  - name: becomeCurrent
+    summary: |
+        Marks the receiver as the activity currently in use by the user.
+    description: |
+        Marks the receiver as the activity currently in use by the user, for example, the activity associated with the active window. 
+        A newly created activity is eligible for continuation on another device after the first time it becomes current.
+    platforms: [iphone, ipad]
+    osver: {ios: {min: "8.0"}}
+  - name: invalidate
+    summary: |
+        Invalidate an activity when it's no longer eligible for continuation.
+    description: |
+        Invalidate an activity when it's no longer eligible for continuation, for example, when the window 
+        associated with an activity is closed. An invalid activity cannot become current.
+    platforms: [iphone, ipad]
+    osver: {ios: {min: "8.0"}}   
+  - name: resignCurrent
+    summary: |
+        If this activity is the current activity, it should stop being so and set the current activity to nothing.
+    platforms: [iphone, ipad]
+    osver: {ios: {min: "9.0"}}
+events:
+  - name: useractivitywillsave
+    summary: |
+    	The user activity will be saved (to be continued or persisted). The receiver should update the activity with current activity state.
+    properties:
+      - name: activityType
+        summary: the activityType of the User Activity triggering the event
+        type: String
+        platforms: [iphone, ipad]
+
+      - name: title
+        summary: The title of the User Activity if defined
+        type: String
+        platforms: [iphone, ipad]
+
+      - name: webpageURL
+        summary: The webpageURL of the User Activity if defined
+        type: String
+        platforms: [iphone, ipad]
+
+      - name: userInfo
+        summary: Dictionary object containing the userInfo data of the User Activity.
+        type: Dictionary 
+        platforms: [iphone, ipad]   
+  - name: useractivitywascontinued
+    summary: |
+    	The user activity was continued on another device.
+    properties:
+      - name: activityType
+        summary: the activityType of the User Activity triggering the event
+        type: String
+        platforms: [iphone, ipad]
+
+      - name: title
+        summary: The title of the User Activity if defined
+        type: String
+        platforms: [iphone, ipad]
+
+      - name: webpageURL
+        summary: The webpageURL of the User Activity if defined
+        type: String
+        platforms: [iphone, ipad]
+
+      - name: userInfo
+        summary: Dictionary object containing the userInfo data of the User Activity.
+        type: Dictionary 
+        platforms: [iphone, ipad]                    
+examples:
+  - title: Creating a new UserActivity Example
+    example: |
+        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.supported){
+				alert('activity not supported');
+				return;
+			}
+			activity.becomeCurrent();
+
+

iphone/Classes/TiAppiOSProxy.m

@@ -15,7 +15,7 @@
 #import "TiAppiOSNotificationActionProxy.h"
 #import "TiAppiOSNotificationCategoryProxy.h"
 #import "TiAppiOSUserDefaultsProxy.h"
-
+#import "TiAppiOSUserActivityProxy.h"
 
 @implementation TiAppiOSProxy
 
@@ -139,6 +139,17 @@ -(void)_listenerRemoved:(NSString*)type count:(int)count
 
 #pragma mark Public
 
+-(id)createUserActivity:(id)args
+{
+    NSString* activityType;
+    ENSURE_SINGLE_ARG(args,NSDictionary);
+    ENSURE_ARG_FOR_KEY(activityType, args, @"activityType", NSString);
+
+    TiAppiOSUserActivityProxy *userActivityProxy = [[[TiAppiOSUserActivityProxy alloc] initWithOptions:args] autorelease];
+
+    return userActivityProxy;
+}
+
 -(id)createUserDefaults:(id)args
 {
     NSString *suiteName;

iphone/Classes/TiAppiOSUserActivityProxy.h

@@ -0,0 +1,21 @@
+/**
+ * Appcelerator Titanium Mobile
+ * Copyright (c) 2009-2015 by Appcelerator, Inc. All Rights Reserved.
+ * Licensed under the terms of the Apache Public License
+ * Please see the LICENSE included with this distribution for details.
+ */
+#import "TiProxy.h"
+
+#ifdef USE_TI_APPIOS
+
+@interface TiAppiOSUserActivityProxy : TiProxy<NSUserActivityDelegate> {
+    @private
+    BOOL _isValid;
+    BOOL _supported;
+}
+-(id)initWithOptions:(NSDictionary*)props;
+@property(nonatomic,retain) NSUserActivity *userActivity;
+
+@end
+
+#endif