Skip to main content

WebSocket

Class

WebSocket provides an API for managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: fully supported
  • Camera Kit Mobile: fully supported
  • SnapchatNot supported — Available on SPECS and Camera Kit only
  • SPECSFully supported
  • Camera Kit WebFully supported
  • Camera Kit MobileFully supported

Platform details

  • Snapchat — Not supported — Available on SPECS and Camera Kit only.

  • SPECS — Fully supported.

  • Camera Kit Web — Fully supported.

  • Camera Kit Mobile — Fully supported.

WebSocket provides an API for managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.

Index

Example

// Create WebSocket connection.
let socket = script.remoteServiceModule.createWebSocket("wss://<some-url>");
socket.binaryType = "blob";

// Listen for the open event
socket.onopen = (event) => {
// Socket has opened, send a message back to the server
socket.send("Message 1");

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

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

print("Received binary message, printing as text: " + text);
} else {
// Text frame
let text = event.data;
print("Received text message: " + text);
}
});

socket.onclose = (event) => {
if (event.wasClean) {
print("Socket closed cleanly");
} else {
print("Socket closed with error, code: " + event.code);
}
};

socket.onerror = (event) => {
print("Socket error");
};

Extends

Properties

binaryType

binaryType: string

SPECSCamera Kit

Controls how binary data is received over the connection. Currently only blob is supported. The arraybuffer type is not yet supported.

// Create WebSocket connection.
webSocket = script.remoteServiceModule.createWebSocket("wss://<some-url>");
socket.binaryType = "blob";

// Listen for messages
socket.addEventListener("message", (event) => {
if (event.data instanceof Blob) {
// Binary frame, can be retrieved as either Uint8Array or string
let bytes = await event.data.bytes();
let text = await event.data.text();
} else {
// Text frame
let text = event.data;
}
});

Default Value

"blob"
@snapOS
@cameraKit

onclose

onclose: (event) => void

SPECSCamera Kit

Set a listener for the close event. The event passed is WebSocketCloseEvent. Equivalent to addEventListener("close", ...). This listener will be run in addition to any listeners added via addEventListener.

websocket.onclose = (event) => {
print("The connection has been closed.");
};

Parameters

ParameterType
eventWebSocketCloseEvent

Returns

void

Since

Lens Scripting Version 290

Default Value

null
@snapOS
@cameraKit

onerror

onerror: (event) => void

SPECSCamera Kit

Set a listener for the error event. The event passed is WebSocketErrorEvent. Equivalent to addEventListener("error", ...). This listener will be run in addition to any listeners added via addEventListener.

websocket.onerror = (event) => {
print("The connection has been closed due to an error: " + error);
};

Parameters

ParameterType
eventWebSocketEvent

Returns

void

Since

Lens Scripting Version 290

Default Value

null
@snapOS
@cameraKit

onmessage

onmessage: (event) => void

SPECSCamera Kit

Set a listener for the message event. The event passed is WebSocketMessageEvent. Equivalent to addEventListener("message", ...). This listener will be run in addition to any listeners added via addEventListener.

websocket.onmessage = async (event) => {
if (event.data instanceof Blob) {
// Binary frame, can be retrieved as either Uint8Array or string
let bytes = await event.data.bytes();
let text = await event.data.text();

print("Received binary message, printing as text: " + text);
} else {
// Text frame
let text = event.data;
print("Received text message: " + text);
}
};

Parameters

ParameterType
eventWebSocketMessageEvent

Returns

void

Since

Lens Scripting Version 290

Default Value

null
@snapOS
@cameraKit

onopen

onopen: (event) => void

SPECSCamera Kit

Set a listener for the open event. The event passed is WebSocketEvent. Equivalent to addEventListener("open", ...). This listener will be run in addition to any listeners added via addEventListener.

websocket.onopen = (event) => {
print("The connection has been opened successfully.");
};

Parameters

ParameterType
eventWebSocketEvent

Returns

void

Since

Lens Scripting Version 290

Default Value

null
@snapOS
@cameraKit

readyState

readonly readyState: number

SPECSCamera Kit

Returns the current state of the WebSocket connection.

CONNECTING (0) Socket has been created. The connection is not yet open.

OPEN (1) The connection is open and ready to communicate.

CLOSING (2) The connection is in the process of closing.

CLOSED (3) The connection is closed or couldn't be opened.


url

readonly url: string

SPECSCamera Kit

Returns the url to which the WebSocket is connecting/connected.

Methods

addEventListener()

addEventListener(type, listener): void

SPECSCamera Kit

Adds a listener for a WebSocket event. Supported event types are:

close Fired when a connection with a WebSocket is closed. Also available via the onclose property.

error Fired when a connection with a WebSocket has been closed because of an error, such as when some data couldn't be sent. Also available via the onerror property.

message Fired when data is received through a WebSocket. Also available via the onmessage property.

open Fired when a connection with a WebSocket is opened. Also available via the onopen property.

Parameters

ParameterType
typestring
listener(event) => void

Returns

void


close()

close(): void

SPECSCamera Kit

Closes the WebSocket connection or connection attempt, if any. If the connection is already CLOSED, this method does nothing.

Returns

void


getTypeName()

static getTypeName(): TypeName<WebSocket>

SPECSCamera Kit

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<WebSocket>

Overrides

ScriptObject.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

ScriptObject.getTypeName


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

ScriptObject.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

ScriptObject.isSame


send()

send(data): void

SPECSCamera Kit

Enqueues the given data to be transmitted to the server over the WebSocket connection. If the data can't be sent (for example, because it needs to be buffered but the buffer is full), the socket is closed automatically.

Text or binary data can be sent via this method. To send text data pass a string into the send function. To send binary, pass a Uint8Array.

Text example:

webSocket.send("Hello World");

Binary example:

// This sequence is `Hello World` in Uint8
const uint8Array = new Uint8Array([
72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100
]);
webSocket.send(uint8Array);

Parameters

ParameterType
datastring | Uint8Array<ArrayBufferLike>

Returns

void