# Titanium.WatchSession

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

Availability
5.0.0

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


# 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

# cancelAllFileTransfers

Availability
5.0.0
cancelAllFileTransfers() void

Cancels all incomplete file transfers to the apple watch.

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.

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

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.