JavaScriptWebWebNode.jsPhoneGapReactReduxTitaniumVueBest Practices Playbook using JavaScript V4

PubNub is a globally distributed Data Stream Network. We provide many Points of Presence around the planet for client devices to connect locally. This level of connectivity offering is unusual and provides above and beyond the industry standards of resilient operations and performance capabilities.

When a client devices opens a TCP connection to PubNub, that connection policy is unlimited. This means that the connection will remain open forever until the client closes the connection or the server enters a maintenance state. If a client disconnects unintentionally, PubNub remembers the undelivered data for a short duration.

When the client's network has been restored, PubNub will automatically bundle and gzip-compress all the messages into a single payload, allowing the client to catch-up after being offline.

This doc explains the wrong way and right way to use PubNub. As you read through this document, you will discover the most common mistakes a customer makes with PubNub.

Sending messages on PubNub is easy. Call the PubNub Publish API. This is the starting point of your development adventure.

Inefficient Client Server Passthrough Publish

Client brokers message to Server. This is inefficient. Your client should be using the Publish command to net the full benefits of PubNub. By using PubNub incorrectly the client will have multi-second latencies. The client doesn't have redundancy. Nearby users do not get sub 50ms round-trip performance. This is the inefficient way to use PubNub. Keep reading to gain full performance of PubNub.

Optimal Client Publish

The client publishes and subscribes to PubNub directly. The client receives global average latency of 100ms. Nearby users get sub 50ms latency. During connectivity duress, the client will be routed to the next accessible route. The client uses an Auth Key with granted access to Publish on a data channel.

Optimal Client Publish + Synchronous Server Logic

When you need to have your server involved for business logic reasons or data copy reasons. This pattern shows you the best approach for integrating server-side logic with PubNub.

Optimal Client Publish + Asynchronous Server Logic

Often you'll find the need to run business logic on your JSON messages, but without slowing the message delivery down. You can do this by creating an onAfter event handler. This handler type will allow you to execute server logic on a copy of your JSON message asynchronously while the original JSON message is on it's way to be delivered to the mobile phone.

Optimal Client Publish + HTTP Call to 3rd Party API Server

You can integrate 3rd party APIs easily. Enable PubNub Functions onBefore or onAfter event handlers on your data channels and use the JavaScript code snippets to execute an HTTP call to the external API.

The payload returned from the API server can be used to augment and modify the original JSON message inline. Or you can save the original message to the 3rd party API using an onAfter event handler.

Optimal Server Sent Events

Server sent events are possible using PubNub. You can notify your users the completion status of a long-running task. Remember that if the event is client initiated, the client must publish directly to PubNub. Sending events from your server should only be for asynchronous tasks like a timer/cron, system level event or long running task status.

Inefficient Proxy Connection

You may be considering a proxy in-the-middle solution. However this breaks down quickly when encryption and TCP connection duration policies conflict. Poor performance and the loss of reliability for the mobile app's connectivity.

Optimal TCP Connection to Nearest Point of Presence

In order to receive messages using PubNub you must subscribe to a data channel. This is done by calling the subscribe API using the PubNub SDK. When you invoke subscribe, the mobile app will open a TCP connection to the nearest PubNub data center. The connection is left open forever. When the mobile app is closed, the connection is cleared.

You may want to copy messages to your own database for indexing or backup purposes.

Inefficient Forking Messages Doubles Mobile Traffic

Sending data directly to your server from the client is the inefficient way to copy data from PubNub. The optimal way is to publish or fire your message directly to your local PubNub POP. PubNub provides multiple points of presence allowing your client device fast reliable connectivity.

Optimal Nearest Point of Presence Event Handler

Using PubNub Functions allows you to run lightweight JavaScript code block directly inside the local PubNub POP (Point of Presence). You can issue an HTTP Call directly inside the JavaScript Snippet which POSTs the message body to your server.

You can use onBefore or onAfter event handlers to save the message to your database. This means you essentially can issue an HTTP call directly inside the local PubNub POP. This is done with a small JavaScript code block which allows you to issue a subordinate asynchronous http request directly to your API Server. Your server will receive the http payload and save the data as needed in your database.

Optimal Offline Backup with Storage and Playback

PubNub includes Multi-datacenter Replicated Storage. Your messages are configurable to be indexed and stored across multiple PubNub points of presence. This allows you to fetch the history for a data channel on a periodic interval. You can download every message from your app via the storage and playback paging API. After you've fetched your messages, you can save them to your database and process the messages as you need.

When providing the mobile phone app with API keys ( PublishKey / SubscribeKey / AuthKey / CipherKey / etc ) you should never hard-code the keys directly in the app. The mobile app should authenticate itself by calling a secure endpoint with access credentials.

After successful authentication, the endpoint will return access tokens for only the necessary data channels. PubNub includes authentication endpoints that you can use in this situation if you don't have your own.

You can program a PubNub Functions Endpoint to authenticate the user and pass the all the needed access keys including the AuthKey. Your business policies may also require key rotation periods and short session IDs. PubNub includes

Optimal Client Authenticates with your App Server returning Access Keys

In order to authenticate and provide access to PubNub's network for your users, you need to provide them API keys. The client is able to perform the permitted activities such as Read/Write/Admin/Manage.

The key exchange can occur after authentication. There are many authentication endpoints including your own. PubNub PubNub Functions Endpoints offers this as well shown in the next example.

Optimal Client Authenticates with PubNub Functions Endpoint giving Access Keys

Using PubNub Functions Endpoints, you can run your lightweight JavaScript code on your local PubNub POP. This allows you to provide API keys to your client device programmatically.

Inefficient Client App has Hard-coded API Access Keys

When you hard code your API keys for access to PubNub, you'll put yourself in a security risk situation. You will no longer have access to Key Rotation capabilities. There is a way out of this, however it's not pretty. You'll be stuck in a multi-deploy multi-week work cycle in a process called Key Migration.

This is much more involved and it's better to avoid hard coding in general. If you don't have a web server, you can use PubNub Functions Endpoints to store your access keys. The endpoint is accessible from your client device via HTTP REST. The endpoint when called via HTTP will return access credentials to the client device including a Publish Key, Subscribe Key and an Auth Key generated via PubNub Grant method.

Inefficient Granting with Unlimited TTL

It is not recommended to offer an unlimited TTL when creating an Auth Key for your users. Auth keys should be treated as temporary access tokens, similar to a session ID. There may be debugging/testing purposes where you may want to grant a one-time Unlimited TTL Auth Key. However Unlimited TTLs should not be given to your users.

Inefficient Client App has Secret Key Embedded

Never expose your Secret Key to ANYONE. Always keep your keys secret. Ideally you should keep your secrets in an encrypted vault system. Upon CI/CD deployment phase, the keys will be copied securely to your server code. Alternatively the keys vault may have a fetch endpoint which is accessible inside your VPC.