Architectural Choices

PubNub provides resilient, real‑time messaging with very low latency. Choose patterns based on your use case to get the best results.

This guide highlights effective patterns and common anti‑patterns, with ways to correct them.

Send messages

To send messages, call the Publish API.

Client-Server passthrough publish

In this pattern, the client brokers messages through your server. It adds latency and creates a single point of failure. Nearby clients also miss sub‑30 ms round‑trip performance. Publish directly from the client to take full advantage of PubNub.

Optimal client publish

The client publishes and subscribes directly. Global average latency is about 30 ms. Nearby clients often see sub‑30 ms. During poor connectivity, routing automatically fails over to the next accessible path. Use an authorization token that grants Publish on the 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

You may need to run business logic on JSON messages without adding latency. Create an onAfter event handler. It executes server logic on a copy of the message asynchronously while the original message is delivered to the device.

Optimal client publish + HTTP call to third-party API server

You can integrate third‑party APIs easily. Enable Functions onBefore or onAfter handlers on your data channels and call the external API from JavaScript.

Use the API response to augment the message inline, or save the original message to the third‑party system using an onAfter handler.

Optimal server sent Events

Server‑sent events are supported. Notify users when a long‑running task completes. If the event is client‑initiated, the client should publish directly. Send events from your server only for asynchronous tasks such as timers/cron, system events, or long‑running task status.

Receive messages

Proxy connection

A proxy‑in‑the‑middle can conflict with encryption and TCP connection duration policies. This can reduce performance and reliability for mobile connectivity.

Optimal TCP connection to nearest point of presence

Subscribe to a data channel to receive messages. Call the Subscribe API using the PubNub SDK. The mobile app opens a TCP connection to the nearest data center and keeps the connection open. When the app closes, the connection is cleared.

Message data copy

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

Client-side forking doubles mobile traffic

Sending data directly from the client to your server is inefficient for copying data. Instead, publish to your local PubNub point of presence (PoP). Multiple PoPs provide fast, reliable connectivity.

Optimal event handler

Use Functions to run lightweight JavaScript on the PubNub platform. Issue HTTP calls from JavaScript to POST the message body to your server. Use onAfter handlers to save messages to your database.

Optimal offline backup with Message Persistence

PubNub includes multi-datacenter replicated message persistence. Your messages are configurable to be indexed and stored across multiple PubNub PoPs. 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 Message Persistence paging API. After you have fetched your messages, you can save them to your database and process the messages as you need.

Security

Key exchange & rotation

When providing the phone app with API keys (publish key, subscribe key, cipher key) you should never hard-code those keys directly in your production app. You should enable Access Manager to add security to your PubNub environment.

Using Access Manager, your mobile app needs to authenticate itself by calling a secure endpoint with access credentials. To get them, the server needs to first make a grant call to PubNub and request a time-limited token with embedded permissions for the app. The app needs to include the received token in any subsequent request made to PubNub to access various resources (channels, channel groups, or User ID metadata) and perform operations at the access level defined in the token. For more details, read about the authentication flow in Access Manager.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Optimal client authenticates with your App server returning API keys

To authenticate and provide access to PubNub's network for your users, you need to provide them with PubNub's API keys and an access token. The client is able to perform the permitted activities, such as Read/Write/Admin/Manage, on PubNub resources depending on the permissions specified in the token.

This key and token exchange can happen after authentication. There are many ways to authenticate your clients, including having an API endpoint at your server. Functions endpoints offer this as well, as shown in the next example.

Optimal client authenticates with Functions endpoint giving API keys

Using Functions endpoints, you can run your own lightweight JavaScript code on PubNub. This allows you to provide API keys to your client device programmatically. However, your client-side code or your server will need to call PubNub's grant API to get a token that your app can use to interact with PubNub resources.

Client app with hard-coded API keys

When you hard code your API keys for access to PubNub, you'll put yourself in a security risk situation. You'll no longer have access to Key Rotation capabilities. It's not easy to implement your own Key Rotation. You'll be stuck in a multi-deploy multi-week work cycle in a process of 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 Functions endpoints to store your API keys. The endpoint is accessible from your client device via HTTP POST. The endpoint will return access credentials to the client device including a Publish Key and a Subscribe Key. It can also return an access token if the endpoint is secured.

Client app with an embedded secret key

The secret key should only be used within a secure server and never exposed to client devices. If the secret key is ever compromised, it can be an extreme security risk to your PubNub account keys. If you suspect your secret key has been compromised, you have the ability to regenerate a new secret key for the existing PubNub keys set.

Regenerating the secret key

Contact PubNub Support for guidance before you regenerate a secret key for a production keyset. A Solution Architect will help you choose the best approach for your use case and requirements.

More design patterns

• Design Patterns for Server Message Aggregation
• Design Patterns for Friend Lists and Status Feeds