2.0.3 • Public • Published

    npm npm npm

    NativeScript WebSockets

    This is a cross-platform WebSocket library for IOS and Android. It supports:

    • Android using Java-Websockets
    • iOS v12 and less using a modified PocketSocket library.
    • iOS V13 and higher using Apple's websocket api (Thanks to legion151 for a lot of the work)

    Please note, According to some stats (https://www.david-smith.org/iosversionstats/ as of mid-2021) iOS < 13 support is still about 7% of the iOS market.


    My code is (c)2015-2021, Master Technology. All my code is LICENSED under the MIT License. The Android Library is also MIT, the iOS libraries used Apache 2.0; which you may view them by reading the "LICENSE" file.

    I also do contract work; so if you have a module you want built for NativeScript (or any other software projects) feel free to contact me nathan@master.technology.

    If you want professional and support plugins; checkout the all new https://proplugins.org


    First run tns --version

    v1.4 thru NS 5.0

    Run tns plugin add nativescript-websockets in your ROOT directory of your project.

    V6.0 or later (Last Tested on NS 8)

    Run ns plugin add @master.technology/websockets in your ROOT directory of your project.


    • The sending of Protocols support is not fully implemented on both platforms. Do not depend on this; it only partially works.


    Pay attention and don't forget to use NgZone.run() -- if you don't use it in some cases; your UI may not update when you get data updates. This is NOT a limitation of this library; but just how Angular works for its change detection system.


    There is two possible interfaces for you to use; the Simple WebSocket interface that emulates the browser based WebSockets and a more advanced WebSocket interface where you have more control.

    Browser based Interface

    var mySocket = new WebSocket("ws://echo.websocket.org", [ /* "protocol","another protocol" */]);
    mySocket.addEventListener('open', function (evt) { console.log("We are Open"); evt.target.send("Hello"); });
    mySocket.addEventListener('message', function(evt) { console.log("We got a message: ", evt.data); evt.target.close(); });
    mySocket.addEventListener('close', function(evt) { console.log("The Socket was Closed:", evt.code, evt.reason); });
    mySocket.addEventListener('error', function(evt) { console.log("The socket had an error", evt.error); });

    Advanced Interface

    var WS = require('@master.technology/websockets');
    var mySocket = new WS("ws://echo.websocket.org",{protocols: [/* 'chat', 'video' */], timeout: 6000, allowCellular: true, headers: { 'Authorization': 'Basic ...' }});
    mySocket.on('open', function(socket) { console.log("Hey I'm open"); socket.send("Hello"); });
    mySocket.on('message', function(socket, message) { console.log("Got a message", message); });
    mySocket.on('close', function(socket, code, reason) { console.log("Socket was closed because: ", reason, " code: ", code); });
    mySocket.on('error', function(socket, error) { console.log("Socket had an error", error);});
    // When all done with the socket, if you want to clear its memory do

    Browser Based WebSockets

    The browser based WebSockets are virtually identical to what you would get if you were using a Browser; they are automatically opened when you create it; all four events have "event" objects with different values. You are not allowed to re-open a closed socket and you have no control over any additional features.

    Create and OPENS a new BROWSER based WebSocket

    new WebSocket(url, [protocols]);

    • URL - (String) - Web Socket URL to open
    • Protocols - OPTIONAL (Array of String) - valid list protocols. Please see limitations note.

    Attaches an event to the WebSocket

    .attachEventListener(EventName, function)

    .on(EventName, function)

    • EventName - (String) can be "open", "close", "message" and "error"
    • function - (Function) the function that will be called when the event occurs

    Advanced WebSockets

    The Advanced WebSockets allow you a lot more control over setting up and creating; in addition if they are closed; you can re-open it without having to reset your events.

    Create a new Advanced WebSocket

    var WS = require('nativescript-websockets'); var ws = new WS(url, options);

    • URL - Url to Open
    • Options
      • protocols - (Array of string) - Valid protocols. (See Limitation note)
      • timeout - timeout (Defaults to 60,0000ms on IOS amd 10,000ms on Android, setting this to 0 disables timeouts)
      • allowCellular (ios only, defaults to True) - can disable the WebSocket from going over the cellular network
      • sslSocketFactory (android only, defaults to null) - you can pass in your ssl socket factory you want to use.
      • connectionLostTimeout (android only, defaults to 60s) - Detect lost connection using ping/pong, forcing a socket disconnect. See Lost connection detection for more information.

    Attaches an event to the WebSocket

    .attachEventListener(EventName, function, passedThis)

    .on(EventName, function, passedThis)

    • EventName - (String) can be "open", "close", "message" and "error"
    • Function - (Function) the function that will be called when the event occurs
    • passedThis - the "this" you want the Function to have

    Opens the WebSocket


    Notes: in the Advanced WebSocket you can re-open a closed WebSocket...

    Common Functions between Advanced and Browser WebSockets

    Clears the memory used by the websocket


    Do to the way GC works, we have to keep a hard reference so that your websocket doesn't disappear mid-use. We automatically call this function on close of browser based websockets. On advanced sockets because you can reopen them again, you are responsible to call this when you are totally done with the socket.

    Closes the open Socket

    .close(code, reason)

    • code - OPTIONAL (Number) - code
    • reason - OPTIONAL (String) - reason

    Sends a Text or Binary Message


    • message - String or Array/ArrayBuffer - Text string or Binary Message to send

    Retrieves the current State


    • 0 - Connection
    • 1 - Open
    • 2 - Closing
    • 3 - Closed

    The URL you opened


    Returns the protocol negotiated


    Please see notes on limitations.

    Returns true if on IOS


    Return true if on Android


    Remove an Event Listener

    .removeEventListener (EventName, function)

    .off(EventName, function)

    • EventName - (String) - Name of Event (open, close, message, error)
    • function - (optional Function) - If you don't pass any function to this; this will remove ALL event listeners for that event, otherwise it will just remove that one event listener.

    Check to see if it is open


    Returns true if the connection is open

    Check to see if it is closed


    Returns true if the connection is closed

    Check to see if it is connecting


    Returns true if the connection is connecting

    Check to see if the connection is closing


    Returns true if it is in the process of closing...


    npm i @master.technology/websockets

    DownloadsWeekly Downloads





    MIT & Apache 2.0

    Unpacked Size

    252 kB

    Total Files


    Last publish


    • nathanaela