Application Setup

Before setup, review the key concepts of User ID and SDK initialization.

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.

User IDs

Set a User ID to connect to PubNub.

Use one User ID per user across devices, or one per client. If users connect from multiple devices at the same time, use the same User ID on each device. Presence uses the User ID to show online status.

For client-side SDKs, get the User ID from your server after the user signs in. See Users & Devices for user authentication patterns and multi‑device session management.

SDK integration and initialization

To use PubNub, install an SDK, initialize a PubNub object, and add event listeners.

Include or install

Each platform offers more than one way to add the PubNub SDK to your app. Choose the method that fits your environment.

// Using the PubNub CDN, add the SDK to your web application.

<script src="https://cdn.pubnub.com/sdk/javascript/pubnub.4.29.9.js"></script>

// If you're using the PubNub Node.js SDK, use the command `npm install pubnub`

To integrate PubNub into your Xcode project using Swift Package Manager, specify it in the dependencies list of your Package.swift file:

dependencies: [
  .package(url: "https://github.com/pubnub/swift.git", from: "3.1.0")
]

Or, in Xcode, navigate to File > Swift Packages > Add Package Dependency, then enter https://github.com/pubnub/swift.git for the package repository URL. You can use defaults for the remaining steps.

CocoaPods is the easiest way to install the PubNub Objective-C SDK in your iOS app. (Check the Objective-C SDK documentation for other installation options, and the latest SDK version.)

In the project's root folder, create a Podfile using pod init (requires CocoaPods 1.0.0 or above).
Open Podfile in an editor. Add pod "PubNub", "~> 4" to the target section, and replace MyObjcProject with your project name.
```
platform :ios, '9.0' # (or '10.0')

target 'MyObjcProject' do
  use_frameworks!
  pod "PubNub", "~> 4"
end
```
In the same directory as the Podfile, enter the command: pod install.
In Xcode, open the workspace (.xcworkspace) file, not the project (.xcodeproj) file.

You can include the PubNub SDK in your Android app using Gradle.

Insert the PubNub implementation dependency to your dependencies section in the build.gradle file of your project. Your list of existing dependencies may differ.

dependencies {
  // some existing dependencies
  implementation fileTree(dir: 'libs', include: ['*.jar'])

  // add PubNub Kotlin SDK here at the bottom
  implementation group: 'com.pubnub', name: 'pubnub-kotlin', version: '9.0.0'
  
  // Alternatively, you can use the PubNub Java SDK (named 'pubnub-gson'):
  // implementation group: 'com.pubnub', name: 'pubnub-gson', version: '9.0.0'
  // Please note that only one of the PubNub SDKs may be added.
}

Click Sync Now in the top right of the Android Studio file editor window.

In your project's manifests folder, add the following permissions to AndroidManifest.xml:

<manifest>
  ...existing content...

  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
</manifest>

The simplest way to install the PubNub Python SDK is with pip:

pip install pubnub

Initialize a PubNub object

Now set up a PubNub object with your publish and subscribe keys and a User ID. If you need keys, create an account in the Admin Portal. Use these keys in samples that show myPublishKey and mySubscribeKey. In code, parameter names can differ by SDK (for example, userId, user_id, or uuid). They map to the same User ID.

You don't need a new instance for every message. PubNub keeps TCP connections alive between calls (publish, subscribe, here-now).

<script type="text/javascript">
  var pubnub = new PubNub({
    publishKey: "myPublishKey",
    subscribeKey: "mySubscribeKey",
    userId: "myUniqueUserId"
});
<script>

from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub

pnconfig = PNConfiguration()
pnconfig.publish_key = "myPublishKey"
pnconfig.subscribe_key = "mySubscribeKey"
pnconfig.user_id = "myUniqueUserId"

pubnub = PubNub(pnconfig)

PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
// publishKey from Admin Portal (only required if publishing)
configBuilder.publishKey("PublishKey");
PubNub pubNub = PubNub.create(configBuilder.build());

val config = PNConfiguration(UserId("myUniqueUserId")).apply {
      publishKey = "myPublishKey"
      subscribeKey = "mySubscribeKey"
  }
  var pubnub = PubNub(config)

pnconfig := pubnub.NewConfig()
pnconfig.SubscribeKey = "MySubscribeKey"
pnconfig.PublishKey = "MyPublishKey"
pnconfig.SetUserId(UserId("myUniqueUserId"))
pn := pubnub.NewPubNub(pnconfig)

pubnub_t *ctx = pubnub_alloc();
if (NULL == ctx) {
    puts("Couldn't allocate a Pubnub context");
    return -1;
}
pubnub_init(ctx, "MyPublishKey", "MySubscribeKey");
pubnub_set_user_id(ctx, "myUniqueUser_id");

using PubNubAPI;

PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.UserId = "myUniqueUserId";
pubnub = new PubNub(pnConfiguration);

import PubNubSDK

let config = PubNubConfiguration(
  publishKey: "demo",
  subscribeKey: "demo",
  userId: "myUniqueUserId"
)

let pubnub = PubNub(configuration: config)

#import <PubNub/PubNub.h>

PNConfiguration *pnconfig = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
                                             subscribeKey:@"mySubscribeKey"];
pnconfig.uuid = "theClientUUID";
PubNub *pubnub = [PubNub clientWithConfiguration:pnconfig];

using PubnubApi;

PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.UserId = "myUniqueUserId";
pubnub = new PubNub(pnConfiguration);

final myKeyset = Keyset(
  subscribeKey: 'mySubscribeKey',
  publishKey: 'myPublishKey',
  userId: UserId('yourUniqueUserId')
  );

use PubNub\PNConfiguration;
use PubNub\PubNub;

$pnconf = new PNConfiguration();

$pnconf->setSubscribeKey("my-key");
$pnconf->setPublishKey("my-key");
$pnconf->setUserId("myUniqueUserId");
$pubnub = new PubNub($pnconf);

pubnub = Pubnub.new(
    subscribe_key: :demo,
    publish_key:   :demo,
    user_id: 'myUniqueUserId'
)

At this point, you can start calling PubNub operations using the pubnub object.

Initialize with secret key

If you plan to use features such as Access Manager, deleting messages from history, or Functions, you must initialize PubNub with a secret key.

Use the secret key only on secure servers. Never expose it to client devices.

const pubnub = new PubNub({
   subscribeKey: 'mySubscribeKey',
   publishKey: 'myPublishKey',
   userId: "myUniqueUserId",
   secretKey: 'mySecretKey'
});

pn_config = PNConfiguration()
pn_config.publish_key = "my_publish_key"
pn_config.subscribe_key = "my_subscribe_key"
pn_config.user_id = "my_unique_user_id"
pn_config.secret_key = "my_secret_key"

pubnub = PubNub(pn_config)

PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
// publishKey from Admin Portal (only required if publishing)
configBuilder.publishKey("PublishKey");
configBuilder.secretKey("mySecretKey");
PubNub pubNub = PubNub.create(configBuilder.build());

val config = PNConfiguration(UserId("myUniqueUserId")).apply {
    subscribeKey = "mySubscribeKey"
    publishKey = "myPublishKey"
    secretKey = "mySecretKey"
    secure = true
}
val pubnub = PubNub.create(config)

pnconfig := pubnub.NewConfig()
pnconfig.SubscribeKey = "MySubscribeKey"
pnconfig.PublishKey = "MyPublishKey"
pnconfig.SecretKey = "MySecretKey"
pnconfig.SetUserId(UserId("myUniqueUserId"))
pn := pubnub.NewPubNub(pnconfig)

pubnub_init(ctx, "mySubscribeKey", "myPublishKey");
pubnub_set_secret_key(ctx, "mySecretKey");
pubnub_set_user_id(ctx, "myUniqueUser_id");

using PubNubAPI;

PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.SecretKey = "my_secretkey";
pnConfiguration.UserId = "myUniqueUserId";
pubnub = new PubNub(pnConfiguration);

using PubNubAPI;

PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.SecretKey = "my_secretkey";
pnConfiguration.UserId = "myUniqueUserId";
pubnub = new PubNub(pnConfiguration);

final myKeyset = Keyset(
  subscribeKey: 'mySubscribeKey',
  publishKey: 'myPublishKey',
  secretKey: 'mySecretKey',
  userId: UserId('yourUniqueUserId')
  );

use PubNub\PNConfiguration;
$pnConfiguration = new PNConfiguration();
$pnConfiguration->setSubscribeKey("MySubscribeKey");
$pnConfiguration->setPublishKey("MyPublishKey");
$pnConfiguration->setSecretKey("MySecretKey");
$pnConfiguration->setUserId("myUniqueUserId");

pubnub = Pubnub.new(
    subscribe_key: 'my_subscribe_key',
    publish_key: 'my_publish_key',
    secret_key: 'my_secret_key',
    user_id: 'myUniqueUserId'
)

For message deletion, see your SDK documentation.

Architectural decisions

For a simple app, start with the architecture decisions page. For advanced apps that aggregate messages on the server, see the server message aggregation guide.

Use channels to route messages. Review channel naming conventions.
Building a social app? See friend lists and status feeds.

User ID / UUID

User IDs​

SDK integration and initialization​

Include or install​

Initialize a PubNub object​

Initialize with secret key​

Architectural decisions​