Networking

Alloy apps can communicate with the internet by proxying network requests through PebbleKit JS (PKJS) running on the phone.

Understanding Watch vs Phone Code

Alloy apps have two JavaScript environments:

Code examples in this guide are labeled with 📱 PKJS or ⌚ Watch to indicate where they run.

Setting Up the Network Proxy

To use fetch() or WebSocket on the watch, install the @moddable/pebbleproxy package:

$ pebble package install @moddable/pebbleproxy

Then set up your src/pkjs/index.js:

📱 PKJS (src/pkjs/index.js):

const moddableProxy = require("@moddable/pebbleproxy");
Pebble.addEventListener('ready', moddableProxy.readyReceived);
Pebble.addEventListener('appmessage', moddableProxy.appMessageReceived);

If your app also needs to handle its own events, call the proxy functions from your handlers:

const moddableProxy = require("@moddable/pebbleproxy");

Pebble.addEventListener('ready', function(e) {
    moddableProxy.readyReceived(e);
    // Handle your own ready event here
});

Pebble.addEventListener('appmessage', function(e) {
    if (moddableProxy.appMessageReceived(e))
        return;

    // Handle your own app messages here
});

HTTP Requests with fetch()

Once the proxy is set up, use fetch() in your watch code:

⌚ Watch (src/embeddedjs/main.js):

async function fetchData() {
    const url = new URL("http://api.open-meteo.com/v1/forecast");
    url.search = new URLSearchParams({
        latitude: 37.7749,
        longitude: -122.4194,
        current: "temperature_2m"
    });

    const response = await fetch(url);
    const data = await response.json();
    console.log("Temperature: " + data.current.temperature_2m);
}

Important Notes

• Wait for the proxy - network requests only work after the proxy signals it is ready. Listen for watch.addEventListener("connected", ...) before calling fetch() or opening a WebSocket

Response Methods

WebSockets

WebSockets are also handled by the @moddable/pebbleproxy package - no additional proxy setup needed.

⌚ Watch (src/embeddedjs/main.js):

const ws = new WebSocket("ws://websockets.chilkat.io/wsChilkatEcho.ashx");
ws.binaryType = "arraybuffer";

ws.addEventListener("open", event => {
    console.log("WebSocket connected");
    ws.send("Hello from Pebble!");
    ws.send(Uint8Array.of(0, 1, 2, 3, 4, 5));
});

ws.addEventListener("message", event => {
    let data = event.data;
    if (data instanceof ArrayBuffer) {
        console.log("Received binary data");
        data = new Uint8Array(data);
    } else {
        console.log("Received: " + data);
        if (data === "Goodbye") ws.close(1000, "Done");
    }
});

ws.addEventListener("close", event => {
    console.log("Closed: " + event.code + " " + event.reason);
});

Connection Status

Check if the phone is connected from watch code:

⌚ Watch (src/embeddedjs/main.js):

function logConnected() {
    console.log("App connected: " + watch.connected.app);
    console.log("PebbleKitJS connected: " + watch.connected.pebblekit);
}

watch.addEventListener('connected', logConnected);
logConnected();

Network requests only work once the proxy is ready. Wait until watch.connected.pebblekit is true before calling fetch() or opening a WebSocket.

Best Practices

1. Install @moddable/pebbleproxy - required for fetch() and WebSocket
2. Wait for the proxy - network requests only work after the proxy is ready; listen for the connected event or check watch.connected.pebblekit
3. Handle errors - network requests can fail
4. Minimize data - request only what you need
5. Cache responses - use localStorage to reduce requests

Advanced Networking

For more control over HTTP and WebSocket connections, Alloy also provides low-level ECMA-419 networking APIs:

• HTTPClient - streaming HTTP client with fine-grained header control
• WebSocketClient - low-level WebSocket with callback-based API, provides streaming support

These are also handled by @moddable/pebbleproxy. See the Advanced Networking guide for details.

Examples

The Pebble Examples repository includes networking examples:

• hellofetch - HTTP requests using the fetch() API
• hellowebsocket - WebSocket connections using the WebSocket API