mirror of
https://github.com/google/pebble.git
synced 2025-03-19 18:41:21 +00:00
428 lines
18 KiB
JavaScript
428 lines
18 KiB
JavaScript
/**
|
|
* Copyright 2025 Google LLC
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
/**
|
|
* @namespace Pebble
|
|
*
|
|
* @desc The Pebble namespace is where all of the Pebble specific methods and
|
|
* properties exist. This class contains methods belonging to PebbleKit JS and
|
|
* allows bi-directional communication with a C or JavaScript watchapp, as well as managing
|
|
* the user's timeline subscriptions, creating AppGlance slices and obtaining
|
|
* information about the currently connected watch.
|
|
*/
|
|
var Pebble = new Object;
|
|
|
|
|
|
/**
|
|
* @desc Adds a listener for PebbleKit JS events, such as when an ``AppMessage`` is
|
|
* received or the configuration view is opened or closed.
|
|
*
|
|
* #### Event Type Options
|
|
*
|
|
* Possible values:
|
|
*
|
|
* * `ready` - The watchapp has been launched and the PebbleKit JS component
|
|
* is now ready to receive events.
|
|
* * `appmessage` - The watch sent an ``AppMessage`` to PebbleKit JS. The
|
|
* AppMessage ``Dictionary`` is contained in the payload property (i.e:
|
|
* `event.payload`). The payload consists of key-value pairs, where the keys
|
|
* are strings containing integers (e.g: "0"), or aliases for keys defined
|
|
* in package.json (e.g: "KEY_EXAMPLE"). Values should be integers, strings
|
|
* or byte arrays (arrays of characters). This event is not available to
|
|
* {@link /docs/rockyjs/ Rocky.js} applications, and attempting to register it will throw an exception.
|
|
* * `showConfiguration` - The user has requested the app's configuration
|
|
* webview to be displayed. This can occur either upon the app's initial
|
|
* install or when the user taps 'Settings' in the 'My Pebble' view within
|
|
* the phone app.
|
|
* * `webviewclosed` - The configuration webview was closed by the user. If
|
|
* the webview had a response, it will be contained in the response property
|
|
* (i.e: `event.response`). This response can be used to feed back user
|
|
* preferences to the watchapp.
|
|
* * `message` - Provide a {@link #PostMessageCallback PostMessageCallback}
|
|
* as the callback. The message event is emitted every time PebbleKit JS
|
|
* receives a {@link #postMessage postMessage} from the {@link /docs/rockyjs/ Rocky.js}
|
|
* application. The payload contains a simple JavaScript object. (i.e. `event.data`).
|
|
* This event type can only be used with {@link /docs/rockyjs/ Rocky.js} applications.
|
|
* * `postmessageconnected` - Provide a {@link #PostMessageConnectedCallback PostMessageConnectedCallback}
|
|
* as the callback. The event may be emitted immediately upon subscription,
|
|
* if the subsystem is already connected. It is also emitted when connectivity is established.
|
|
* This event type can only be used with {@link /docs/rockyjs/ Rocky.js} applications.
|
|
* * `postmessagedisconnected` - Provide a {@link #PostMessageDisconnectedCallback PostMessageDisconnectedCallback}
|
|
* as the callback. The event may be emitted immediately upon subscription,
|
|
* if the subsystem is already disconnected. It is also emitted when connectivity is lost.
|
|
* This event type can only be used with {@link /docs/rockyjs/ Rocky.js} applications.
|
|
* * `postmessageerror` - Provide a {@link #PostMessageErrorCallback PostMessageErrorCallback}
|
|
* as the callback. The event is emitted when a transmission error occurrs.
|
|
* Your message has not been delivered. The type of error is not provided.
|
|
* This event type can only be used with {@link /docs/rockyjs/ Rocky.js} applications.
|
|
*
|
|
* @param {String} type - The type of the event, from the list described above.
|
|
* @param {EventCallback} callback - The developer defined {@link #EventCallback EventCallback}
|
|
* to receive any events of the type specified that occur.
|
|
*/
|
|
Pebble.addEventListener = function(type, callback) { };
|
|
|
|
/**
|
|
* @desc Attaches an event handler to the specified events. Synonymous with
|
|
[Pebble.addEventListener()](#addEventListener). Only applicable to
|
|
{@link /docs/rockyjs/ Rocky.js} applications.
|
|
*
|
|
* `Pebble.on(type, callback);`
|
|
*
|
|
* @param {String} type - The type of the event, from the list described above.
|
|
* @param {EventCallback} callback - The developer defined {@link #EventCallback EventCallback}
|
|
* to receive any events of the type specified that occur.
|
|
*/
|
|
Pebble.on = function(type, callback) { };
|
|
|
|
/**
|
|
* @desc Remove an existing event listener previously registered with
|
|
* [Pebble.addEventListener()](#addEventListener) or [Pebble.on()](#on).
|
|
*
|
|
* @param {String} type - The type of the event listener to be removed. See
|
|
* [Pebble.addEventListener()](#addEventListener) for a list of available event types.
|
|
* @param {Function} callback - The existing developer-defined function that was
|
|
* previously registered.
|
|
*/
|
|
Pebble.removeEventListener = function(type, callback) { };
|
|
|
|
/**
|
|
* @desc Remove an existing event handler from the specified events. Synonymous
|
|
* with [Pebble.removeEventListener()](#removeEventListener). Only applicable to
|
|
* {@link /docs/rockyjs/ Rocky.js} applications.
|
|
*
|
|
* `Pebble.off(type, callback);`
|
|
*
|
|
* @param {String} type - The type of the event listener to be removed. See
|
|
* [Pebble.addEventListener()](#addEventListener) for a list of available types.
|
|
* @param {Function} callback - The existing developer-defined function that was
|
|
* previously registered.
|
|
*/
|
|
Pebble.off = function(type, callback) { };
|
|
|
|
/**
|
|
* @desc Show a simple modal notification on the connected watch.
|
|
*
|
|
* @param {String} title - The title of the notification
|
|
* @param {String} body - The main content of the notification
|
|
*/
|
|
Pebble.showSimpleNotificationOnPebble = function(title, body) { };
|
|
|
|
/**
|
|
* @desc Send an AppMessage to the app running on the watch. Messages should be
|
|
* in the form of JSON objects containing key-value pairs. See
|
|
* Pebble.sendAppMessage() for valid key and value data types.
|
|
* `Pebble.sendAppMessage = function(data, onSuccess, onFailure) { };`
|
|
* Please note that `sendAppMessage` is `undefined` in
|
|
* {@link /docs/rockyjs/ Rocky.js} applications, see {@link #postMessage postMessage} instead.
|
|
*
|
|
* @returns {Number} The transaction id for this message
|
|
*
|
|
* @param {Object} data - A JSON object containing key-value pairs to send to
|
|
* the watch. Values in arrays that are greater then 255 will be mod 255
|
|
* before sending.
|
|
* @param {AppMessageAckCallback} onSuccess - A developer-defined {@link #AppMessageAckCallback AppMessageAckCallback}
|
|
* callback to run if the watch acknowledges (ACK) this message.
|
|
* @param {AppMessageOnFailure} onFailure - A developer-defined {@link #AppMessageNackCallback AppMessageNackCallback}
|
|
* callback to run if the watch does NOT acknowledge (NACK) this message.
|
|
*/
|
|
Pebble.sendAppMessage = function(data, onSuccess, onFailure) { };
|
|
|
|
/**
|
|
* @desc Sends a message to the {@link /docs/rockyjs/ Rocky.js} component. Please be aware
|
|
* that messages should be kept concise. Each message is queued, so
|
|
* `postMessage()` can be called multiple times immediately. If there is a momentary loss of connectivity, queued
|
|
* messages may still be delivered, or automatically removed from the queue
|
|
* after a few seconds of failed connectivity. Any transmission failures, or
|
|
* out of memory errors will be raised via the `postmessageerror` event.
|
|
*
|
|
* `Pebble.postMessage({temperature: 30, conditions: 'Sunny'});`
|
|
*
|
|
* @param {Object} data - A {@link #PostMessageCallback PostMessageCallback} containing
|
|
* the data to deliver to the watch.
|
|
* This will be received in the `data` field of the `type` delivered to
|
|
* the `on('message', ...)` handler.
|
|
*/
|
|
Pebble.postMessage = function(data) { };
|
|
|
|
/**
|
|
* @desc Get the user's timeline token for this app. This is a string and is
|
|
* unique per user per app. Note: In order for timeline tokens to be
|
|
* available, the app must be submitted to the Pebble appstore, but does not
|
|
* need to be public. Read more in the
|
|
* {@link /guides/pebble-timeline/timeline-js/ timeline guides}.
|
|
*
|
|
* @param {TimelineTokenCallback} onSuccess - A developer-defined {@link #TimelineTokenCallback TimelineTokenCallback}
|
|
* callback to handle a successful attempt to get the timeline token.
|
|
* @param {Function} onFailure - A developer-defined callback to handle a
|
|
* failed attempt to get the timeline token.
|
|
*/
|
|
Pebble.getTimelineToken = function(onSuccess, onFailure) { };
|
|
|
|
/**
|
|
* @desc Subscribe the user to a timeline topic for your app. This can be used
|
|
* to filter the different pins a user could receive according to their
|
|
* preferences, as well as maintain groups of users.
|
|
*
|
|
* @param {String} topic - The desired topic to be subscribed to. Users will
|
|
* receive all pins pushed to this topic.
|
|
* @param {Function} onSuccess - A developer-defined callback to handle a
|
|
* successful subscription attempt.
|
|
* @param {Function} onFailure - A developer-defined callback to handle a
|
|
* failed subscription attempt.
|
|
*/
|
|
Pebble.timelineSubscribe = function(topic, onSuccess, onFailure) { };
|
|
|
|
/**
|
|
* @desc Unsubscribe the user from a timeline topic for your app. Once
|
|
* unsubscribed, the user will no longer receive any pins pushed to this
|
|
* topic.
|
|
*
|
|
* @param {String} topic - The desired topic to be unsubscribed from.
|
|
* @param {Function} onSuccess - A developer-defined callback to handle a
|
|
* successful unsubscription attempt.
|
|
* @param {Function} onFailure - A developer-defined callback to handle a
|
|
* failed unsubscription attempt.
|
|
*/
|
|
Pebble.timelineUnsubscribe = function(topic, onSuccess, onFailure) { };
|
|
|
|
/**
|
|
* @desc Obtain a list of topics that the user is currently subscribed to. The
|
|
* length of the list should be checked to determine whether the user is
|
|
* subscribed to at least one topic.
|
|
*
|
|
* `Pebble.timelineSubscriptions(function(topics) { console.log(topics); }, function() { console.log('error'); } );`
|
|
*
|
|
* @param {TimelineTopicsCallback} onSuccess - The developer-defined function to process the
|
|
* retuned list of topic strings.
|
|
* @param {Function} onFailure - The developer-defined function to gracefully
|
|
* handle any errors in obtaining the user's subscriptions.
|
|
*/
|
|
Pebble.timelineSubscriptions = function(onSuccess, onFailure) { };
|
|
|
|
|
|
/**
|
|
* @desc Obtain an object containing information on the currently connected
|
|
* Pebble smartwatch.
|
|
*
|
|
* **Note:** This function is only available when using the Pebble Time
|
|
* smartphone app. Check out our guide on {@link /guides/communication/using-pebblekit-js Getting Watch Information}
|
|
* for details on how to use this function.
|
|
*
|
|
* @returns {WatchInfo} A {@link #WatchInfo WatchInfo} object detailing the
|
|
* currently connected Pebble watch.
|
|
*/
|
|
Pebble.getActiveWatchInfo = function() { };
|
|
|
|
/**
|
|
* @desc Returns a unique account token that is associated with the Pebble
|
|
* account of the current user.
|
|
*
|
|
* **Note:** The behavior of this changed slightly in SDK 3.0. Read the
|
|
* {@link /guides/migration/migration-guide-3/ Migration Guide} to learn the
|
|
* details and how to adapt older tokens.
|
|
*
|
|
* @returns {String} A string that is guaranteed to be identical across devices
|
|
* if the user owns several Pebble or several mobile devices. 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, this function will return an empty string ('').
|
|
*/
|
|
|
|
Pebble.getAccountToken = function() { };
|
|
|
|
/**
|
|
* @desc Returns a a unique token that can be used to identify a Pebble device.
|
|
*
|
|
* @returns {String} A string that is is guaranteed to be identical for each
|
|
* Pebble device for the same app across different mobile devices. The token
|
|
* is unique to your app and cannot be used to track Pebble devices across
|
|
* applications.
|
|
*/
|
|
Pebble.getWatchToken = function() { };
|
|
|
|
|
|
/**
|
|
* @desc Triggers a reload of the app glance which first clears any existing
|
|
* slices and then adds the provided slices.
|
|
*
|
|
* @param {AppGlanceSlice} appGlanceSlices - {@link #AppGlanceSlice AppGlanceSlice}
|
|
* JSON objects to add to the app glance.
|
|
* @param {AppGlanceReloadSuccessCallback} onSuccess - The developer-defined
|
|
* callback which is called if the reload operation succeeds.
|
|
* @param {AppGlanceReloadFailureCallback} onFailure - The developer-defined
|
|
* callback which is called if the reload operation fails.
|
|
*/
|
|
Pebble.appGlanceReload = function(appGlanceSlices, onSuccess, onFailure) { };
|
|
|
|
/**
|
|
* @desc When an app is marked as configurable, the PebbleKit JS component must
|
|
* implement `Pebble.openURL()` in the `showConfiguration` event handler. The
|
|
* Pebble mobile app will launch the supplied URL to allow the user to configure
|
|
* the watchapp or watchface. See the
|
|
* {@link /guides/user-interfaces/app-configuration-static/ App Configuration guide}.
|
|
*
|
|
* @param {String} url - The URL of the static configuration page.
|
|
*/
|
|
Pebble.openURL = function(url) { };
|
|
|
|
/**
|
|
* @typedef {Function} AppGlanceReloadSuccessCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when AppGlanceReload is successful.
|
|
* @param {AppGlanceSlice} AppGlanceSlices - An {@link #AppGlanceSlice AppGlanceSlice} object
|
|
* containing the app glance slices.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} AppGlanceReloadFailureCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when AppGlanceReload has failed.
|
|
* @param {AppGlanceSlice} AppGlanceSlices - An {@link #AppGlanceSlice AppGlanceSlice} object
|
|
* containing the app glance slices.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} AppMessageAckCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when an AppMessage is acknowledged by the watch.
|
|
* @param {Object} data - An object containing the callback data. This contains
|
|
* the `transactionId` which is the transaction ID of the message.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} AppMessageNackCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when an AppMessage is not acknowledged by the watch.
|
|
* @param {Object} data - An object containing the callback data. This contains
|
|
* the `transactionId` which is the transaction ID of the message
|
|
* @param {String} error - The error message
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} EventCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when an event of any type previously registered occurs. The
|
|
* parameters are different depending on the type of event, shown in
|
|
* brackets for each parameter listed here.
|
|
* @param {Object} event - An object containing the event information, including:
|
|
* * `type` - The type of event fired, from the list in the description of [Pebble.addEventListener()](#addEventListener).
|
|
* * `payload` - The dictionary sent over ``AppMessage`` consisting of
|
|
* key-value pairs. *This field only exists for `appmessage` events.*
|
|
* * `response` - The contents of the URL navigated to when the
|
|
* configuration page was closed, after the anchor. This may be encoded,
|
|
* which will require use of decodeURIComponent() before reading as an
|
|
* object. *This field only exists for for `webviewclosed` events.*
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} TimelineTokenCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when the user's timeline token is available.
|
|
* @param {String} token - The user's token.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} TimelineTopicsCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Called when the user's list of subscriptions is available for processing by the developer.
|
|
* @param {[String]} List of topic strings that the user is subscribed to
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} PostMessageCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc The callback function signature to be used with the `message`
|
|
* {@link #on event}.
|
|
*
|
|
* @param {Object} event - An object containing information about the event:
|
|
* * `type` - The type of event which was triggered.
|
|
* * `data` - The data sent within the message.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} PostMessageErrorCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc The callback function signature to be used with the `postmessageerror`
|
|
* {@link #on event}.
|
|
*
|
|
* @param {Object} event - An object containing information about the event:
|
|
* * `type` - The type of event which was triggered.
|
|
* * `data` - The data failed to send within the message.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} PostMessageConnectedCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc The callback function signature to be used with the `postmessageconnected`
|
|
* {@link #on event}.
|
|
*
|
|
* @param {Object} event - An object containing information about the event:
|
|
* * `type` - The type of event which was triggered.
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Function} PostMessageDisconnectedCallback
|
|
* @memberof Pebble
|
|
*
|
|
* @desc The callback function signature to be used with the `postmessagedisconnected`
|
|
* {@link #on event}.
|
|
*
|
|
* @param {Object} event - An object containing information about the event:
|
|
* * `type` - The type of event which was triggered.
|
|
*/
|
|
|
|
|
|
/**
|
|
* @typedef {Object} WatchInfo
|
|
* @memberof Pebble
|
|
*
|
|
* @desc Provides information about the connected Pebble smartwatch.
|
|
*
|
|
* @property {String} platform - The hardware platform, such as `basalt` or `emery`.
|
|
* @property {String} model - The watch model, such as `pebble_black`
|
|
* @property {String} language - The user's currently selected language on
|
|
* this watch.
|
|
* @property {Object} firmware - An object containing information about the
|
|
* watch's firmware version, including:
|
|
* * `major` - The major version
|
|
* * `minor` - The minor version
|
|
* * `patch` - The patch version
|
|
* * `suffix` - Any additional version information, such as `beta3`
|
|
*/
|
|
|
|
/**
|
|
* @typedef {Object} AppGlanceSlice
|
|
* @memberof Pebble
|
|
*
|
|
* @desc The structure of an app glance.
|
|
*
|
|
* @property {String} expirationTime - Optional ISO date-time string of when
|
|
the entry should expire and no longer be shown in the app glance.
|
|
* @property {Object} layout - An object containing:
|
|
* * `icon` - URI string of the icon to display in the app glance, e.g. system://images/ALARM_CLOCK.
|
|
* * `subtitleTemplateString` - Template string that will be displayed in the subtitle of the app glance.
|
|
*/
|