Now Particularly Misnamed

    @pusher/pusher-websocket-react-native
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    Pusher React Native Websocket Client

    Twitter GitHub license npm version

    This is the Pusher Channels React Native client.

    For tutorials and more in-depth information about Pusher Channels, visit our official docs.

    Supported Mobile platforms

    Deployment targets

    • iOS 13.0 and above
    • Android 6.0 and above

    Example Application

    By cloning this repository you can check the React Native example application, a minimal application to connect to a channel and send events.

    Table of Contents

    Installation

    To integrate the plugin in your React Native App, you need to add the plugin to your package.json:

    npm install @pusher/pusher-websocket-react-native

    or

    yarn add @pusher/pusher-websocket-react-native

    iOS specific installation

    The Pusher Channels React Native plugin adds the pusher-websocket-swift cocoapod to your project. You probably need to run a

    $ pod install

    in the ios directory.

    Android specific installation

    Gradle should automatically include the pusher-websocket-java dependency.

    Initialization

    The Pusher class is a singleton that can be instantiated with getInstance(). Then you need to initialize the client with several configuration options. Here is a quick example with several callbacks options:

    import {
      Pusher,
      PusherMember,
      PusherChannel,
      PusherEvent,
    } from '@pusher/pusher-websocket-react-native';
    
    const pusher = Pusher.getInstance();
    
    try {
      await pusher.init({
        apiKey,
        cluster,
        // authEndpoint: '<YOUR ENDPOINT URI>',
        onConnectionStateChange,
        onError,
        onEvent,
        onSubscriptionSucceeded,
        onSubscriptionError,
        onDecryptionFailure,
        onMemberAdded,
        onMemberRemoved,
      });
    
      await pusher.subscribe({ channelName });
      await pusher.connect();
    } catch (e) {
      console.log(`ERROR: ${e}`);
    }

    After calling init(...) you can connect to the Pusher servers. You can subscribe to channels before calling connect().

    Configuration

    There are a few configuration parameters which can be set for the Pusher client. The following table describes available parameters for each platform:

    parameter Android iOS
    activityTimeout
    apiKey
    authEndpoint
    cluster
    maxReconnectGapInSeconds
    maxReconnectionAttempts
    pongTimeout
    proxy ⬜️
    useTLS

    activityTimeout (double)

    If no messages are received after this time period (in seconds), the ping message is sent to check if the connection is still working. The server supplies the default value, low values result in unnecessary traffic.

    apiKey (string)

    You can get your API_KEY and API_CLUSTER from the Pusher Channels dashboard.

    authEndpoint (string)

    The authEndpoint provides a URL that the Pusher client will call to authorize users for a presence channel. Learn how to implement an authorization service

    cluster (string)

    Specifies the cluster that pusher-js should connect to. Here's the full list of Pusher clusters. If you do not specify a cluster, mt1 will be used by default.

    useTLS (bool)

    Whether or not you would like to use TLS encrypted transport or not, default is true.

    Event Callback parameters

    The following functions are callbacks that can be passed to the init() method. All are optional.

    onEvent

    function onEvent(PusherEvent event) {
      console.log(`onEvent: ${event}`);
    }

    Called when an event is received by the client. The global event handler will trigger events from any channel.

    onSubscriptionSucceeded

    function onSubscriptionSucceeded(channelName:string, data:any) {
      console.log(`onSubscriptionSucceeded: ${channelName} data: ${data}`);
    }

    Use this if you want to be informed when a channel has successfully been subscribed to. This is useful if you want to perform actions that are only relevant after a subscription has succeeded. For example, querying the members for presence channel.

    onSubscriptionError

    function onSubscriptionError(channelName: string, message:string, e:any) {
      console.log(`onSubscriptionError: ${message} channelName: ${channelName} Exception: ${e}`);
    }

    Use this if you want to be informed of a failed subscription attempt. You can use this to re-attempt the subscription or make a call to a service you use to track errors.

    onDecryptionFailure

    function onDecryptionFailure(event:string, string reason:string) {
      console.log(`onDecryptionFailure: ${event} reason: ${reason}`);
    }

    Used with private channels only. Use this if you want to be notified if any messages fail to decrypt.

    onMemberAdded

    function onMemberAdded(channelName:string, member:PusherMember) {
      console.log(`onMemberAdded: ${channelName} member: ${member}`);
    }

    Called when a member is added to the presence channel.

    onMemberRemoved

    function onMemberRemoved(channelName:string, member:PusherMember) {
      console.log(`onMemberRemoved: ${channelName} member: ${member}`);
    }

    Called when a member is removed from the presence channel.

    onAuthorizer

    When passing the onAuthorizer() callback to the init() method, this callback is called to request auth information. Learn how to generate the correct auth signatures

    async function onAuthorizer(channelName:string, socketId:string):Promise<any> {
      return {
        auth: "foo:bar",
        channel_data: '{"user_id": 1}',
        shared_secret: "foobar"
      };
    }

    onConnectionStateChange

    function onConnectionStateChange(currentState:string, previousState:string) {
      console.log(`Connection: ${currentState}`);
    }

    Use this if you want to use connection state changes to perform different actions/UI updates. The connection can have different states, as follows:

    • CONNECTING - Currently attempting to establish a connection
    • CONNECTED - Connection successfully established
    • DISCONNECTING - Connection is about to be disconnected.
    • DISCONNECTED - Connection has been disconnected with no attempts to automatically reconnect.
    • RECONNECTING - Atempting to re-establish the connection.

    onError

    function onError(message:string, code:int, e:any) {
      console.log(`onError: $message code: ${code} exception: ${e}`);
    }

    Use this if you want to be informed about errors received from Pusher Channels. For example, Application is over connection quota. For more details, refer to Pusher error codes.

    Connection handling

    Connecting

    To connect to the Pusher network, call the connect() method.

    await pusher.connect();

    Disconnecting

    To disconnect from the Pusher network, just call the disconnect() method.

    await pusher.disconnect();

    Reconnection

    There are three main ways why a connection could be disconnected:

    • The client explicitly calls disconnect and a close frame is sent over the websocket connection.
    • The client experiences some form of network degradation which leads to a heartbeat (ping/pong) message being missed and thus the client disconnects.
    • The Pusher server closes the websocket connection; typically this will only occur during a restart of the Pusher socket servers and almost immediatelly it will reconnect.

    In the case of the first type of disconnection, the library will (as you would hope) not attempt to reconnect.

    Subscribing

    Public channels

    The default method for subscribing to a channel involves invoking the subscribe method of your client object:

    const myChannel = await pusher.subscribe({channelName: "my-channel"});

    Private channels

    Private channels are created in exactly the same way as public channels, except that they reside in the 'private-' namespace. This means prefixing the channel name:

    const myPrivateChannel = await pusher.subscribe({channelName: "private-my-channel"})

    To subscribe to a private channel, the client needs to be authenticated. Refer to the Configuration section for the authenticated channel example.

    Private encrypted channels

    Similar to Private channels, you can also subscribe to a private encrypted channel. This library now fully supports end-to-end encryption. This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them.

    Like with private channels, you must provide an authentication endpoint. That endpoint must be using a server client that supports end-to-end encryption. There is a demonstration endpoint to look at using nodejs.

    The shared secret used to decrypt events is loaded from the same auth endpoint request that is used to authorize your subscription. There is also a mechanism for reloading the shared secret if your encryption master key changes. If an event is encountered that cannot be decrypted, a request is made to your auth endpoint to attempt to load the new shared secret. If that request fails or if the returned secret still cannot decrypt the event then that event will be skipped, the onDecryptionFailure callback function will be called, and the next received event will be processed.

    Limitations

    • Client events are not supported on encrypted channels
    const privateEncryptedChannel = await pusher.subscribe({channelName: "private-encrypted-my-channel"})

    There is also an optional callback in the connection delegate when you can listen for any failed decryption events:

    void onDecryptionFailure(event:string, reason:string)

    Presence channels

    Presence channels are channels whose names are prefixed by presence-.

    The resulting channel object has a member: members that contains the active members of the channel.

    const myPresenceChannel = await pusher.subscribe({channelName: "presence-my-channel"})

    You can also provide functions that will be called when members are either added to or removed from the channel. These are available as parameters to init() globally, or to subscribe() per channel.

    void onMemberAdded(channelName:string, member:PusherMember) {
      console.log(`onMemberAdded: ${channelName} user: ${member}`);
    }
    void onMemberRemoved(channelName:string, member:PusherMember) {
      console.log(`onMemberRemoved: ${channelName} user: ${member}`);
    }

    Note: The members property of PusherChannel objects will only be set once subscription to the channel has succeeded.

    The easiest way to find out when a channel has been successfully subscribed to is to bind to the callback named onSubscriptionSucceeded on the channel you're interested in. It would look something like this:

    const pusher = Pusher.getInstance();
    const channels = {};
    await pusher.init(
      apiKey: API_KEY,
      cluster: API_CLUSTER,
      authEndPoint: "https://your-server.com/pusher/auth"
    );
    const myChannel = await pusher.subscribe(
      channelName:'presence-my-channel',
      onSubscriptionSucceeded: (channelName, data) => {
        console.log(`Subscribed to ${channelName}`);
        console.log(`I can now access me: ${myChannel.me}`)
        console.log(`And here are the channel members: ${myChannel.members}`)
      },
      onMemberAdded: (member) => {
        console.log(`Member added: ${member}`);
      },
      onMemberRemoved: (member) => {
        console.log(`Member removed: ${member}`);
      },
      onEvent: (event) => {
        console.log(`Event received: ${event}`);
      },
    );

    Note that both private and presence channels require the user to be authenticated to subscribe to the channel. This authentication can either happen inside the library if you configured your Pusher object with your app's secret, or an authentication request is made to an authentication endpoint that you provide, again when initializing your Pusher object.

    We recommend that you use an authentication endpoint over including your app's secret in your app in the vast majority of use cases. If you are completely certain that there's no risk to you including your app's secret in your app. For example, if your app is just for internal use at your company, then it can make things easier than setting up an authentication endpoint.

    Unsubscribing

    To unsubscribe from a channel, call the unsubscribe() method:

    await pusher.unsubscribe({channelName:"my-channel"});

    Binding to events

    Events can be bound to at two levels; globally and per channel. There is an example of this below.

    Per-channel events

    These are bound to a specific channel. You can reuse event names in different parts of your client application.

    const pusher = Pusher.getInstance();
    await pusher.init(
      apiKey: API_KEY,
      cluster: API_CLUSTER
    );
    const myChannel = await pusher.subscribe(
      channelName: "my-channel",
      onEvent: (event) => {
        console.log(`Got channel event: ${event}`);
      }
    );
    await pusher.connect();

    Global events

    You can attach behavior to these events regardless of the channel the event is broadcast to.

    const pusher = Pusher.getInstance();
    await pusher.init(
      apiKey: API_KEY,
      cluster: API_CLUSTER,
      onEvent: (event) {
        console.log(`Got event: ${event}`);
      }
    );
    const myChannel = await pusher.subscribe(
      channelName: "my-channel"
    );

    PusherEvent

    The callbacks you bind receive a PusherEvent:

    class PusherEvent {
      channelName:string; // Name of the channel.
      eventName:string; // Name of the event.
      data:any; // Data, usually JSON string. See [parsing event data](#parsing-event-data).
      userId:string; // UserId of the sending event, only for client events on presence channels.
    }

    Parsing event data

    The data property of PusherEvent contains the string representation of the data that you passed when you triggered the event. If you passed an object then that object will have been serialized to JSON. You can parse that JSON as appropriate.

    Receiving errors

    Errors received from Pusher Channels can be accessed via the onError callback.

    void onError(message:string, code:int, e:any) {
      console.log(`onError: ${message} code: ${code} exception: ${e}`);
    }

    Triggering events

    Once a private or presence subscription has been authorized (see authenticating users) and the subscription has succeeded, it is possible to trigger events on those channels. You can do this per channel, or on the global Pusher instance.

    await myChannel.trigger({eventName: "client-my-event", data: {"myName": "Bob"}});

    Or on the global pusher instance:

    await pusher.trigger({channelName: "my-channel", eventName: "client-my-event", data: {"myName": "Bob"}});

    Events triggered by clients are called client events. Because they are being triggered from a client which may not be trusted, there are a number of enforced rules when using them. Some of these rules include:

    • Event names must have a client- prefix
    • Rate limits
    • You can only trigger an event when the subscription has succeeded

    For more details, refer to client events.

    Get a channel by name

    To get the PusherChannel instance from the Pusher instance you can use the getChannel(<channelName>) method:

    const channel = pusher.getChannel("presence-channel");

    Socket information

    To get information from the current socket call the getSocketId() method:

    const socketId = await pusher.getSocketId();

    Communication

    • If you have found a bug, please open an issue.
    • If you have a feature request, open an issue.
    • If you want to contribute, submit a pull request.

    Credits

    Pusher is owned and maintained by Pusher.

    License

    Pusher is released under the MIT license. Refer to LICENSE for more details.

    Install

    npm i @pusher/pusher-websocket-react-native

    DownloadsWeekly Downloads

    88

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    1.27 MB

    Total Files

    176

    Last publish

    Collaborators

    • meenaalfons
    • pusherapp
    • pusher-admin
    • dborania_pusher