Skip to main content

WebSocket

Connect a SPECS Lens to real-time data streams over the internet with the WebSocket API, for live updates and two-way communication.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

Overview

SPECS offers the standard WebSocket API, so a Lens can connect to real-time streams on the internet. The API follows the MDN WebSocket reference.

createWebSocket is a method of InternetModule. Older Lenses called createWebSocket on RemoteServiceModule, where it's now deprecated. On SPECS 27, call it on InternetModule.

Get started with the WebSocket API on SPECS

WebSocket prerequisites

You need Lens Studio 5.25 and a SPECS 27 device.

Set up a Lens for WebSocket connections

To use the WebSocket API, add an InternetModule asset to your project and assign it to the script input, as in the examples on this page.

The WebSocket API only works in the Preview panel when the Lens runs as SPECS: set the panel's device menu to SPECS 27 (see Preview Lenses for SPECS).

Connect to a WebSocket server from a SPECS Lens

InternetModule exposes the WebSocket API. To connect to a WebSocket server, call createWebSocket with a ws or wss URL. createWebSocket also takes an optional list of protocols and a WebSocketOptions object, created with createWebSocketOptions, whose headers are sent with the opening handshake (for example, an Authorization header).

Insecure connections (ws) require Experimental APIs. A Lens that uses them is fine for testing but can't be published. A Lens that uses secure connections (wss) can be published.

Use the returned WebSocket object to manage the connection: watch for a successful connection with the onopen property, handle incoming messages with the onmessage property, and send messages with the send method. The following example does all three:

@component
export class WebSocketExample extends BaseScriptComponent {
@input
internetModule: InternetModule;

private socket!: WebSocket;
// Method called when the script is awake
onAwake() {
this.socket = this.internetModule.createWebSocket('wss://<some-url>');

this.socket.binaryType = 'blob';

// Listen for the open event
this.socket.onopen = (event: WebSocketEvent) => {
print('WebSocket Connected!');

// Socket has opened, send a text message
const msg = 'Message 1';
print('Sending: ' + msg);
this.socket.send(msg);

// Try sending a binary message
// (the bytes below spell 'Message 2')
const message: number[] = [77, 101, 115, 115, 97, 103, 101, 32, 50];
const bytes = new Uint8Array(message);
print('Sending binary message: Message 2');
this.socket.send(bytes);
};

// Listen for messages
this.socket.onmessage = async (event: WebSocketMessageEvent) => {
if (event.data instanceof Blob) {
// Binary frame, can be retrieved as either Uint8Array or string
const bytes = await event.data.bytes();
const text = await event.data.text();

print('Received binary message, printing as text: ' + text);
} else {
// Text frame
const text: string = event.data;
print('Received text message: ' + text);
}
};
this.socket.onclose = (event: WebSocketCloseEvent) => {
if (event.wasClean) {
print('Socket closed cleanly');
} else {
print('Socket closed with error, code: ' + event.code);
}
};

this.socket.onerror = (event: WebSocketEvent) => {
print('Socket error');
};
}
}

Known limitations of the WebSocket API on SPECS

The WebSocket API on SPECS supports the methods in the standard, with the following exceptions:

  • The Blob type doesn't support ArrayBuffer or Stream yet.

  • WebSocket.binaryType doesn't support arraybuffer; only blob is supported.

  • The extensions, protocol, and bufferedAmount properties aren't supported. You can request protocols through createWebSocket, but you can't read which one the server chose.