pebble/devsite/source/_guides/communication/using-pebblekit-js.md

title	description	guide_group	order	platform_choice
PebbleKit JS	How to use PebbleKit JS to communicate with the connected phone's JS environment.	communication	4	true

PebbleKit JS allows a JavaScript component (run in a sandbox inside the official Pebble mobile app) to be added to any watchapp or watchface in order to extend the functionality of the app beyond what can be accomplished on the watch itself.

Extra features available to an app using PebbleKit JS include:

• Access to extended storage with localStorage.

• Internet access using XMLHttpRequest.

• Location data using geolocation.

• The ability to show a configuration page to allow users to customize how the app behaves. This is discussed in detail in {% guide_link user-interfaces/app-configuration %}.

Setting Up

^LC^ PebbleKit JS can be set up by creating the index.js file in the project's src/pkjs/ directory. Code in this file will be executed when the associated watchapp is launched, and will stop once that app exits.

^CP^ PebbleKit JS can be set up by clicking 'Add New' in the Source Files section of the sidebar. Choose the 'JavaScript file' type and choose a file name before clicking 'Create'. Code in this file will be executed when the associated watchapp is launched, and will stop once that app exits.

The basic JS code required to begin using PebbleKit JS is shown below. An event listener is created to listen for the ready event - fired when the watchapp has been launched and the JS environment is ready to receive messages. This callback must return within a short space of time (a few seconds) or else it will timeout and be killed by the phone.

Pebble.addEventListener('ready', function() {
  // PebbleKit JS is ready!
  console.log('PebbleKit JS ready!');
});

{% markdown %} **Important**

A watchapp or watchface must wait for the ready event before attempting to send messages to the connected phone. See Advanced Communication to learn how to do this. {% endmarkdown %}

Defining Keys

^LC^ Before any messages can be sent or received, the keys to be used to store the data items in the dictionary must be declared. The watchapp side uses exclusively integer keys, whereas the JavaScript side may use the same integers or named string keys declared in package.json. Any string key not declared beforehand will not be transmitted to/from Pebble.

^CP^ Before any messages can be sent or received, the keys to be used to store the data items in the dictionary must be declared. The watchapp side uses exclusively integer keys, whereas the JavaScript side may use the same integers or named string keys declared in the 'PebbleKit JS Message Keys' section of 'Settings'. Any string key not declared beforehand will not be transmitted to/from Pebble.

Note: This requirement is true of PebbleKit JS only, and not PebbleKit Android or iOS.

^LC^ Keys are declared in the project's package.json file in the messageKeys object, which is inside the pebble object. Example keys are shown as equivalents to the ones used in the hypothetical weather app example in {% guide_link communication/sending-and-receiving-data#choosing-key-values %}.

{% highlight {} %} "messageKeys": [ "Temperature", "WindSpeed", "WindDirection", "RequestData", "LocationName" ] {% endhighlight %}

^CP^ Keys are declared individually in the 'PebbleKit JS Message Keys' section of the 'Settings' page. Enter the 'Key Name' of each key that will be used by the app.

The names chosen here will be injected into your C code prefixed with MESSAGE_KEY_, like MESSAGE_KEY_Temperature. As such, they must be legal C identifiers.

If you want to emulate an array by attaching multiple "keys" to a name, you can specify the size of the array by adding it in square brackets: for instance, "LapTimes[10]" would create a key called LapTimes and leave nine empty keys after it which can be accessed by arithmetic, e.g. MESSAGE_KEY_LapTimes + 3.

Sending Messages from JS

Messages are sent to the C watchapp or watchface using Pebble.sendAppMessage(), which accepts a standard JavaScript object containing the keys and values to be transmitted. The keys used must be identical to the ones declared earlier.

An example is shown below:

// Assemble data object
var dict = {
  'Temperature': 29,
  'LocationName': 'London, UK'
};

// Send the object
Pebble.sendAppMessage(dict, function() {
  console.log('Message sent successfully: ' + JSON.stringify(dict));
}, function(e) {
  console.log('Message failed: ' + JSON.stringify(e));
});

It is also possible to read the numeric values of the keys by requireing message_keys, which is necessary to use the array feature. For instance:

// Require the keys' numeric values.
var keys = require('message_keys');

// Build a dictionary.
var dict = {}
dict[keys.LapTimes] = 42
dict[keys.LapTimes+1] = 51

// Send the object
Pebble.sendAppMessage(dict, function() {
  console.log('Message sent successfully: ' + JSON.stringify(dict));
}, function(e) {
  console.log('Message failed: ' + JSON.stringify(e));
});

Type Conversion

Depending on the type of the item in the object to be sent, the C app will be able to read the value (from the Tuple.value union) according to the table below:

JS Type	Union member
String	cstring
Number	int32
Array	data
Boolean	int16

Receiving Messages in JS

When a message is received from the C watchapp or watchface, the appmessage event is fired in the PebbleKit JS app. To receive these messages, register the appropriate event listener:

// Get AppMessage events
Pebble.addEventListener('appmessage', function(e) {
  // Get the dictionary from the message
  var dict = e.payload;

  console.log('Got message: ' + JSON.stringify(dict));
});

Data can be read from the dictionary by reading the value if it is present. A suggested best practice involves first checking for the presence of each key within the callback using an if() statement.

if(dict['RequestData']) {
  // The RequestData key is present, read the value
  var value = dict['RequestData'];
}

Using LocalStorage

In addition to the storage available on the watch itself through the Storage API, apps can take advantage of the larger storage on the connected phone through the use of the HTML 5 localStorage API. Data stored here will persist across app launches, and so can be used to persist latest data, app settings, and other data.

PebbleKit JS localStorage is:

• Associated with the application UUID and cannot be shared between apps.

• Persisted when the user uninstalls and then reinstalls an app.

• Persisted when the user upgrades an app.

To store a value:

var color = '#FF0066';

// Store some data
localStorage.setItem('backgroundColor', color);

To read the data back:

var color = localStorage.getItem('backgroundColor');

Note: Keys used with localStorage should be Strings.

Using XMLHttpRequest

A PebbleKit JS-equipped app can access the internet and communicate with web services or download data using the standard XMLHttpRequest object.

To communicate with the web, create an XMLHttpRequest object and send it, specifying the HTTP method and URL to be used, as well as a callback for when it is successfully completed:

var method = 'GET';
var url = 'http://example.com';

// Create the request
var request = new XMLHttpRequest();

// Specify the callback for when the request is completed
request.onload = function() {
  // The request was successfully completed!
  console.log('Got response: ' + this.responseText);
};

// Send the request
request.open(method, url);
request.send();

If the response is expected to be in the JSON format, data items can be easily read after the responseText is converted into a JSON object:

request.onload = function() {
  try {
    // Transform in to JSON
    var json = JSON.parse(this.responseText);

    // Read data
    var temperature = json.main.temp;
  } catch(err) {
    console.log('Error parsing JSON response!');
  }
};

Using Geolocation

PebbleKit JS provides access to the location services provided by the phone through the navigator.geolocation object.

^CP^ Declare that the app will be using the geolocation API by checking the 'Uses Location' checkbox in the 'Settings' screen.

^LC^ Declare that the app will be using the geolocation API by adding the string location in the capabilities array in package.json:

{% highlight {} %} "capabilities": [ "location" ] {% endhighlight %}

Below is an example showing how to get a single position value from the geolocation API using the getCurrentPosition() method:

function success(pos) {
  console.log('lat= ' + pos.coords.latitude + ' lon= ' + pos.coords.longitude);
}

function error(err) {
  console.log('location error (' + err.code + '): ' + err.message);
}

/* ... */

// Choose options about the data returned
var options = {
  enableHighAccuracy: true,
  maximumAge: 10000,
  timeout: 10000
};

// Request current position
navigator.geolocation.getCurrentPosition(success, error, options);

Location permission is given by the user to the Pebble application for all Pebble apps. The app should gracefully handle the PERMISSION DENIED error and fallback to a default value or manual configuration when the user has denied location access to Pebble apps.

function error(err) {
  if(err.code == err.PERMISSION_DENIED) {
    console.log('Location access was denied by the user.');  
  } else {
    console.log('location error (' + err.code + '): ' + err.message);
  }
}

The geolocation API also provides a mechanism to receive callbacks when the user's position changes to avoid the need to manually poll at regular intervals. This is achieved by using watchPosition() in a manner similar to the example below:

// An ID to store to later clear the watch
var watchId;

function success(pos) {
  console.log('Location changed!');
  console.log('lat= ' + pos.coords.latitude + ' lon= ' + pos.coords.longitude);
}

function error(err) {
  console.log('location error (' + err.code + '): ' + err.message);
}

/* ... */

var options = {
  enableHighAccuracy: true,
  maximumAge: 0,
  timeout: 5000
};

// Get location updates
watchId = navigator.geolocation.watchPosition(success, error, options);

To cancel the update callbacks, use the watchId variable received when the watch was registered with the clearWatch() method:

// Clear the watch and stop receiving updates
navigator.geolocation.clearWatch(watchId);

Account Token

PebbleKit JS provides a unique account token that is associated with the Pebble account of the current user, accessible using Pebble.getAccountToken():

// Get the account token
console.log('Pebble Account Token: ' + Pebble.getAccountToken());

The token is a string with the following properties:

• From the developer's perspective, the account token of a user is identical across platforms and across all the developer's watchapps.

• If the user is not logged in, the token will be an empty string ('').

Watch Token

PebbleKit JS also provides a unique token that can be used to identify a Pebble device. It works in a similar way to Pebble.getAccountToken():

// Get the watch token
console.log('Pebble Watch Token: ' + Pebble.getWatchToken());

The token is a string that is unique to the app and cannot be used to track Pebble devices across applications.

{% markdown %} **Important**

The watch token is dependent on the watch's serial number, and therefore should not be used to store sensitive user information in case the watch changes ownership. If the app wishes to track a specific user and watch, use a combination of the watch and account token. {% endmarkdown %}

Showing a Notification

A PebbleKit JS app can send a notification to the watch. This uses the standard system notification layout with customizable title and body fields:

var title = 'Update Available';
var body = 'Version 1.5 of this app is now available from the appstore!';

// Show the notification
Pebble.showSimpleNotificationOnPebble(title, body);

Note: PebbleKit Android/iOS applications cannot directly invoke a notification, and should instead leverage the respective platform notification APIs. These will be passed on to Pebble unless the user has turned them off in the mobile app.

Getting Watch Information

Use Pebble.getActiveWatchInfo() to return an object of data about the connected Pebble.

{% markdown %} This API is currently only available for SDK 3.0 and above. Do not assume that this function exists, so test that it is available before attempting to use it using the code shown below. {% endmarkdown %}

var watch = Pebble.getActiveWatchInfo ? Pebble.getActiveWatchInfo() : null;

if(watch) {
  // Information is available!

} else {
  // Not available, handle gracefully
  
}

Note: If there is no active watch available, null will be returned.

The table below details the fields of the returned object and the information available.

Field	Type	Description	Values
platform	String	Hardware platform name.	aplite, basalt, chalk.
model	String	Watch model name including color.	pebble_black, pebble_grey, pebble_white, pebble_red, pebble_orange, pebble_blue, pebble_green, pebble_pink, pebble_steel_silver, pebble_steel_black, pebble_time_red, pebble_time_white, pebble_time_black, pebble_time_steel_black, pebble_time_steel_silver, pebble_time_steel_gold, pebble_time_round_silver_14mm, pebble_time_round_black_14mm, pebble_time_round_rose_gold_14mm, pebble_time_round_silver_20mm, pebble_time_round_black_20mm, qemu_platform_aplite, qemu_platform_basalt, qemu_platform_chalk.
language	String	Language currently selected on the watch.	E.g.: en_GB. See the {% guide_link tools-and-resources/internationalization#locales-supported-by-pebble %} for more information.
firmware	Object	The firmware version running on the watch.	See below for sub-fields.
firmware.major	Number	Major firmware version.	E.g.: 2
firmware.minor	Number	Minor firmware version.	E.g.: 8
firmware.patch	Number	Patch firmware version.	E.g.: 1
firmware.suffix	String	Any additional firmware versioning.	E.g.: beta3