# Titanium.WatchSession

Used to enable data and file transfers between a watchOS and iOS application.

Availability

5.0.0

Extends

# Overview

WatchSession enables data and file transfers between a WatchKit application and a Titanium application using the iOS Watch Connectivity framework introduced in iOS 9 and watchOS 2.

# Properties

# activationState READONLY

Availability

5.4.0

activationState :Number

Returns the current activation state of the watch.

This API can be assigned the following constants:

# apiName READONLY

Availability

5.0.0

apiName :String

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

Availability

5.0.0

bubbleParent :Boolean

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

# hasContentPending READONLY

Availability

6.0.0

hasContentPending :Boolean

Returns true if there is more content for the session to deliver.

# isActivated READONLY

Availability

5.4.0

isActivated :Boolean

Returns true if the watch is currently activated.

# isComplicationEnabled READONLY

Availability

5.0.0

isComplicationEnabled :Boolean

Returns true if complication is enabled on the installed watch app.

# isPaired READONLY

Availability

5.0.0

isPaired :Boolean

Returns true if the device is paired with a watch.

# isReachable READONLY

Availability

5.0.0

isReachable :Boolean

Returns true if the watch is currently reachable.

# isSupported READONLY

Availability

5.0.0

isSupported :Boolean

Returns true if the device supports watch connectivity.

# isWatchAppInstalled READONLY

Availability

5.0.0

isWatchAppInstalled :Boolean

Returns true if the accompanying watch app is installed.

# recentApplicationContext READONLY

Availability

5.0.0

recentApplicationContext :Dictionary

The most recent application context sent to the watch app.

# remainingComplicationUserInfoTransfers READONLY

Availability

6.0.0

remainingComplicationUserInfoTransfers :Number

The number of calls remaining to transferCurrentComplication before the system starts transferring the complicationUserInfo as regular userInfos.

Default: 0

# Methods

# activateSession

Availability

5.0.0

activateSession() → void

Activates the watch session

Activates the watch session to make the app ready to receive messages from the watch app.

Returns

Type: void

# addEventListener

Availability

5.0.0

addEventListener(name, callback) → void

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

Availability

5.0.0

applyProperties(props) → void

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

# cancelAllFileTransfers

Availability

5.0.0

cancelAllFileTransfers() → void

Cancels all incomplete file transfers to the apple watch.

Returns

Type: void

# cancelAllTransfers

Availability

5.0.0

cancelAllTransfers() → void

Cancels all incomplete transfers to the apple watch.

Cancels all incomplete transfers to the apple watch, including user info, complication and file.

Returns

Type: void

# cancelAllUserInfoTransfers

Availability

5.0.0

cancelAllUserInfoTransfers() → void

Cancels all incomplete user info and complication transfers to the apple watch.

Returns

Type: void

# fireEvent

Availability

5.0.0

fireEvent(name[, event]) → void

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

# removeEventListener

Availability

5.0.0

removeEventListener(name, callback) → void

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 `addEventListener`.

Returns

Type: void

# sendMessage

Availability

5.0.0

sendMessage(message[, reply]) → void

Sends a message to the apple watch.

Sends a message to the installed watchapp on the apple watch in the foreground.

Parameters

Name	Type	Description
`message`	Dictionary	Message to send to apple watch. This property is required and the key of the dictionary needs to be a String.
`reply`	Callback<MessageReply>	Function to be called upon receiving a reply from the watch app. Since Release 5.1.0 This function is used to process the direct reply from the watch app after sending one.

Returns

Type: void

# transferCurrentComplication

Availability

5.0.0

transferCurrentComplication(params) → void

Transfers complication data to the watch application.

Transfers complication data to the installed watch app. This is only for watch apps with complications enabled.

Parameters

Name	Type	Description
`params`	Dictionary	Complication to be transferred to watch app.

Returns

Type: void

# transferFile

Availability

5.0.0

transferFile(params) → void

Transfers a file to the apple watch.

Transfers a file to the installed watchapp on the apple watch in the background. Subsequent transfers are queued.

Parameters

Name	Type	Description
`params`	Dictionary	Pass an object with the following key-value pairs: `fileURL` (String) (required): Local filesystem path of file to send to the watch app. `metaData` (Dictionary) (optional): Additional information about the file to send to the watch app.

Returns

Type: void

# transferUserInfo

Availability

5.0.0

transferUserInfo(params) → void

Transfers an user info to the apple watch.

Transfers an user info object to the installed watchapp on the apple watch in the background. Subsequent transfers are queued.

Parameters

Name	Type	Description
`params`	Dictionary	userInfo to be transferred to apple watch.

Returns

Type: void

# updateApplicationContext

Availability

5.0.0

updateApplicationContext(params) → void

Sends an app context update to the apple watch.

Sends an app context update to the apple watch. If watchapp is in background during transfer, watchapp will fire the receiveapplicationcontext event immediately when it becomes active. Only one app context is stored at any one time. Subsequent updates will simply replace the earlier one sent.

Parameters

Name	Type	Description
`params`	Dictionary	App context to be updated in apple watch.

Returns

Type: void

# Events

# receivemessage

Availability

5.0.0

App received message from apple watch in foreground. Will be called on startup if the incoming message caused the receiver to launch.

Properties

Name	Type	Description
message	Dictionary	The message content
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.

# receiveapplicationcontext

Availability

5.0.0

App received app context from apple watch. Will be called on startup if an applicationContext is available.

Properties

Name	Type	Description
applicationContext	Dictionary	The application Context
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.

# receiveuserinfo

Availability

5.0.0

App received user info from apple watch in background. Will be called on startup if the user info finished transferring when the receiver was not running.

Properties

Name	Type	Description
userInfo	Dictionary	The user info content
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.

# receivefile

Availability

5.0.0

App received file from apple watch in background.

Properties

Name	Type	Description
data	Titanium.Blob	The downloaded data as a Titanium.Blob object.
metaData	Dictionary	Information about the file.
success	Boolean	If the transfer was successful.
errorCode	Number	Error code if transfer failed.
message	String	Error message if any.
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.

# watchstatechanged

Availability

5.0.0

The watch state has changed.

Properties

Name	Type	Description
isPaired	Boolean	If the device is paired with the apple watch.
isReachable	Boolean	If apple watch is currently reachable.
isWatchAppInstalled	Boolean	If the watch app is installed in the apple watch.
isComplicationEnabled	Boolean	If the complication is enabled in the apple watch.
isActivated	Boolean	If the apple watch is currently activated. Only available on iOS 9.3 and later. See isActivated for more infos.
activationState	Number	Returns the current activation state of the watch. Only available on iOS 9.3 and later. See activationState for more infos.
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.

# reachabilitychanged

Availability

5.0.0

The watch reachability state has changed.

Properties

Name	Type	Description
isPaired	Boolean	If the device is paired with the apple watch.
isReachable	Boolean	If apple watch is currently reachable.
isWatchAppInstalled	Boolean	If the watch app is installed in the apple watch.
isComplicationEnabled	Boolean	If the complication is enabled in the apple watch.
isActivated	Boolean	If the apple watch is currently activated. Only available on iOS 9.3 and later. See isActivated for more infos.
activationState	Number	Returns the current activation state of the watch. Only available on iOS 9.3 and later. See activationState for more infos.
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.

# finishuserinfotransfer

Availability

5.0.0

Fired when the application completed user info transfer to the watch app.

Properties

Name	Type	Description
userInfo	Dictionary	The downloaded data as a Titanium.Blob object.
success	Boolean	If the transfer was successful.
errorCode	Number	Error code if transfer failed.
message	String	Error message if any.
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.

# finishfiletransfer

Availability

5.0.0

App completed file transfer to watch app.

Properties

Name	Type	Description
fileURL	String	URL of the file transferred.
metaData	Dictionary	meta data of the file transferred.
success	Boolean	If the transfer was successful.
errorCode	Number	Error code if transfer failed.
message	String	Error message if any.
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.

# inactive

Availability

5.4.0

Called when the session can no longer be used to modify or add any new transfers and, all interactive messages will be cancelled, but events for background transfers can still fire. This will happen when the selected watch is being changed.

Properties

Name	Type	Description
isPaired	Boolean	If the device is paired with the apple watch.
isReachable	Boolean	If apple watch is currently reachable.
isWatchAppInstalled	Boolean	If the watch app is installed in the apple watch.
isComplicationEnabled	Boolean	If the complication is enabled in the apple watch.
isActivated	Boolean	If the apple watch is currently activated. Only available on iOS 9.3 and later. See isActivated for more infos.
activationState	Number	Returns the current activation state of the watch. Only available on iOS 9.3 and later. See activationState for more infos.
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.

# deactivate

Availability

5.4.0

Called when all events for the previously selected watch has occurred. The session can be re-activated for the now selected watch using activateSession.

Properties

Name	Type	Description
isPaired	Boolean	If the device is paired with the apple watch.
isReachable	Boolean	If apple watch is currently reachable.
isWatchAppInstalled	Boolean	If the watch app is installed in the apple watch.
isComplicationEnabled	Boolean	If the complication is enabled in the apple watch.
isActivated	Boolean	If the apple watch is currently activated. Only available on iOS 9.3 and later. See isActivated for more infos.
hasContentPending	Boolean	If the apple watch has currently content pending. Only available on iOS 10.0 and later. See hasContentPending for more infos.
remainingComplicationUserInfoTransfers	Boolean	If the apple watch has complication userInfo transfers left. Only available on iOS 10.0 and later. See remainingComplicationUserInfoTransfers for more infos.
activationState	Number	Returns the current activation state of the watch. Only available on iOS 9.3 and later. See activationState for more infos.
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.

# activationCompleted

Availability

5.4.0

Called when the session has completed activation. If session state is ACTIVATION_STATE_NOT_ACTIVATED there will be an error with more details.

Properties

Name	Type	Description
isPaired	Boolean	If the device is paired with the apple watch.
isReachable	Boolean	If apple watch is currently reachable.
isWatchAppInstalled	Boolean	If the watch app is installed in the apple watch.
isComplicationEnabled	Boolean	If the complication is enabled in the apple watch.
isActivated	Boolean	If the apple watch is currently activated. Only available on iOS 9.3 and later. See isActivated for more infos.
activationState	Number	Returns the current activation state of the watch. Only available on iOS 9.3 and later. See activationState for more infos.
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.

# Constants

# ACTIVATION_STATE_ACTIVATED

Availability

5.4.0

ACTIVATION_STATE_ACTIVATED :Number

The watch is currently activated.

# ACTIVATION_STATE_INACTIVE

Availability

5.4.0

ACTIVATION_STATE_INACTIVE :Number

The watch is currently inactive.

# ACTIVATION_STATE_NOT_ACTIVATED

Availability

5.4.0

ACTIVATION_STATE_NOT_ACTIVATED :Number

The watch is currently not activated.