PubNub — What It Is, Real-Time SDK and How It Works in Applications

What is PubNub?

PubNub is a global real-time data network, founded in 2010. It provides an API for publishing and subscribing to messages, as well as additional services: history storage, presence management, serverless functions (PubNub Functions), and data stream analytics.

PubNub's architecture is based on a distributed network of points of presence (POPs) located in 15+ geographic regions. Each point contains caching brokers that route messages between publishers and subscribers with minimal latency. PubNub does not use a single central broker — each region operates independently and synchronizes through the global network.

According to the official PubNub website (2025), the platform serves over 70,000 applications in 200+ countries. Key clients include Logitech (IoT device management), GoPro (real-time video streaming), eBay (auction synchronization), and Snapchat (chat and notifications).

Key Principles of PubNub

PubNub is built on three principles: speed (latency under 10 ms in the 95th percentile within a single region), reliability (at-least-once delivery guarantee with automatic retry), and scalability (horizontal expansion without limit on the number of channels). The platform does not store messages in long-term storage — history is available through a separately connected Storage & Playback service.

How PubNub Works

PubNub's operation model is based on the classic publish-subscribe pattern. The publisher client sends a message specifying the channel via the PubNub REST API with a publish key. PubNub delivers the message to all subscribers of that channel through their active WebSocket connections. Subscribers receive the message through a callback handler registered in the PubNub SDK.

The transport layer of PubNub uses WebSocket as the primary protocol, with a fallback to HTTP long-polling for environments with constraints. The SDK automatically manages the connection: establishes, maintains heartbeat (every 15–60 seconds depending on the network), and reconnects on disconnection.

Each message in PubNub contains metadata: sender UUID, timestamp, sequence number (timetoken), and flags (store, replicate, eatAfterRead). Timetoken is a unique PubNub identifier based on time that guarantees global message order within a channel. According to PubNub documentation (2025), timetoken has a resolution of 10 nanoseconds.

Message Flow

When a client publishes a message, it passes through the Stream Controller — PubNub's routing module. The Stream Controller checks access rights (PAM), applies transformation rules (PubNub Functions), determines target regions, and sends the message to all subscribers. If a subscriber is offline, the message is buffered for 30 seconds (by default) while waiting for connection recovery.

PubNub Keys: publish, subscribe, secret

PubNub's key system separates access rights into three levels: publish key (publishing only), subscribe key (subscribing only), and secret key (administration). Each application receives a set of three keys upon registration, but the secret key is never transmitted to the client — it is used only on the server side.

The publish key is used to send messages to channels. The subscribe key is used to subscribe to channels and receive messages. The secret key is used for access management via PubNub Access Manager (PAM), creating temporary audience tokens, and key management. The secret key is kept secure on the server and is never revealed to clients.

PubNub supports several authentication modes: by IP address (for servers), by secret key (for administrative operations), and by temporary tokens (for clients). Temporary tokens are issued through PAM with restrictions on expiration time, channels, and permissions (read, write, manage).

PubNub Channels

PubNub channels are named message routes. A channel name is a string up to 92 characters long, supporting Latin letters, digits, hyphens, and underscores. Channels are created dynamically upon first publication or subscription. PubNub supports channel patterns using the * character in subscribe requests — this allows subscribing to a group of channels (e.g., user-*).

Channel Groups is a mechanism for grouping channels for bulk subscription. Instead of subscribing to 50 individual channels, the client subscribes to one group, and all messages from channels within that group are automatically delivered to the client. Channel Groups support nesting, but the depth should not exceed 3 levels.

According to PubNub technical documentation (2025), the maximum number of subscribers per channel is 50,000. For higher loads, it is recommended to use channels with prefixes and shard the audience (e.g., chat-room-001, chat-room-002). Channel Groups can also be organized by geographical or thematic principles.

How to Use PubNub in a Project

PubNub integration requires registration, creating an application in the admin panel, and obtaining a set of keys. PubNub libraries are available for JavaScript, Swift, Kotlin, Java, Dart (Flutter), C#, Python, Ruby, Go, and many other languages. Let's look at an example in JavaScript for browser and Node.js.

According to PubNub documentation (2025), the pubnub-js library supports both CommonJS and ES Module imports. For the browser, it is recommended to use the npm build followed by bundling via webpack or Vite.

Subscribing to a Channel

import PubNub from 'pubnub';

const pubnub = new PubNub({
    publishKey: 'PUBLISH_KEY',
    subscribeKey: 'SUBSCRIBE_KEY',
    userId: 'user-100'
});

pubnub.subscribe({
    channels: ['chat-general']
});

pubnub.addListener({
    message: (event) => {
        console.log('New message:', event.message);
    },
    presence: (event) => {
        console.log('Presence:', event.uuid, event.action);
    }
});

pubnub.publish({
    channel: 'chat-general',
    message: { text: 'Hello everyone!', sender: 'user-100' }
});

Getting Message History

pubnub.fetchMessages(
    { channels: ['chat-general'], count: 50 },
    (status, response) => {
        if (status.error) {
            console.error('Error fetching history', status);
            return;
        }
        const messages = response.channels['chat-general'];
        messages.forEach((msg) => {
            console.log(msg.message, msg.timetoken);
        });
    }
);

PubNub Functions and Stream Controller

PubNub Functions is a serverless platform for processing messages on the PubNub side. Functions are written in JavaScript and executed in a secure isolated environment (V8 isolate). They can transform, filter, buffer, and redirect messages before they are delivered to subscribers.

Stream Controller is a built-in routing mechanism that manages message flow based on rules. Rules determine which messages are delivered, which are discarded, and which are sent to PubNub Functions for processing. Stream Controller supports conditional routing by message content, channel type, or metadata.

According to the PubNub blog (2024), PubNub Functions reduce server infrastructure costs for message processing by 40–60% by offloading filtering and transformation logic to PubNub edge nodes rather than running on your own server. Functions have access to HTTP requests, Key-Value storage, and other functions within the same space.

PubNub in Mobile Applications

PubNub SDK for mobile platforms is available for iOS (Swift), Android (Kotlin/Java), Flutter (Dart), and React Native (JavaScript). Mobile SDKs support the full range of features: pub/sub, presence, history, PAM, and PubNub Functions. For push notifications, PubNub integrates with APNs and FCM through a special mobile push gateway mechanism.

Optimization for mobile devices includes adaptive heartbeat, batch message processing, and support for background modes. The PubNub SDK for iOS uses the Background Task API to maintain the connection when the app is minimized (up to 30 seconds of standard background time). For longer background operation, push notifications are required.

Mobile Push Gateway is a mechanism for sending push notifications via PubNub. When a message is published to a channel, PubNub automatically determines which subscribers are offline and sends them a push notification via APNs (iOS) or FCM (Android). Configuration is done once in the admin panel — after that, all messages from the channel are automatically duplicated to the push channel. According to PubNub documentation (2025), the gateway processes up to 10,000 push notifications per second.