WebSocket
ClassWebSocket 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
WebSocket provides an API for managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
Index
Properties
Methods
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
| Parameter | Type |
|---|---|
event | WebSocketCloseEvent |
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
| Parameter | Type |
|---|---|
event | WebSocketEvent |
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
| Parameter | Type |
|---|---|
event | WebSocketMessageEvent |
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
| Parameter | Type |
|---|---|
event | WebSocketEvent |
Returns
void
Since
Lens Scripting Version 290
Default Value
null
@snapOS
@cameraKit
readyState
readonlyreadyState: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
readonlyurl: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
| Parameter | Type |
|---|---|
type | string |
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()
staticgetTypeName():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
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
data | string | Uint8Array<ArrayBufferLike> |
Returns
void