@pusher/pusher-websocket-react-native
v1.3.1
Published
Pusher Channels Client for React Native
Downloads
26,269
Readme
Pusher React Native Websocket Client
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
- Android through pusher-websocket-java
- iOS through pusher-websocket-swift
Deployment targets
- iOS 13.0 and above
- Android 7 and above. Android 6 will require desugaring.
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.
- https://github.com/pusher/pusher-websocket-react-native/tree/master/example
Table of Contents
- Pusher React Native Websocket Client
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: APP_KEY,
cluster: APP_CLUSTER,
// authEndpoint: '<YOUR ENDPOINT URI>',
onConnectionStateChange,
onError,
onEvent,
onSubscriptionSucceeded,
onSubscriptionError,
onDecryptionFailure,
onMemberAdded,
onMemberRemoved,
onSubscriptionCount,
});
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 | ✅ | ✅ | | authorizerTimeoutInSeconds | ⬜️ | ✅ |
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 APP_KEY
and APP_CLUSTER
from the the App page on the App Keys section in your 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
.
authorizerTimeoutInSeconds (double)
If onAuthorizer callback is not called in Javascript before this time period (in seconds), the authorization for the channel will timeout on the native side. Default value: 10 seconds. iOS only.
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.
onSubscriptionCount
function onSubscriptionCount(subscriptionCount:number) {
console.log(`onSubscriptionSucceeded: ${subscriptionCount}`);
}
is an event that can be manually enabled on the server to count the number of connections that are currently subscribed to a particular channel. They work with all channel types, except presence channels. See Counting live users at scale with subscription_count events for more information.
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<PusherAuthorizerResult> {
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 connectionCONNECTED
- Connection successfully establishedDISCONNECTING
- 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();
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.