PubNub Logo Docs
Support Contact Sales Login Try Our APIs

›Setup

Collapse all
Dark mode

Home

  • Home

First steps

  • Set up your account
  • Get the SDK
  • Initialize PubNub
  • Identify users and devices
  • Send messages
  • Receive messages
  • Retrieve old messages
  • Check user presence
  • Add custom metadata
  • Manage access
  • Add serverless business logic
  • Send push notifications

Setup

  • PubNub account
  • Application
  • Users & devices
  • Connection management
  • Data security
  • Data persistence
  • API limits

Chat

  • In-App Chat

SDKs

  • SDKs

Messages

  • Publish
  • Receive
  • Actions
  • Payload type conventions

Channels

  • Basics
  • Subscription
  • Naming conventions

User presence

  • Basics
  • Events
  • State
  • Webhooks

Metadata

  • Channel
  • User
  • Membership

Message Persistence

  • Message Persistence

File sharing

  • File sharing

Access management

  • Manage access

Push notifications

  • Basics
  • iOS
  • Android
  • Troubleshooting

Best practices

  • Architectural choices
  • Message aggregation
  • Friend list & status feed
  • Troubleshooting
  • Migration guides

Serverless processing

    EVENTS & ACTIONS

    • Basics
    • Configure Events & Actions

    FUNCTIONS

    • Basics
    • Development guidelines
    • Functions API
    • Custom integrations

Debug Console
Network Status

Application Setup

There are two important concepts that require your attention before you start setting up your application.

UUIDs

Setting a UUID is required to establish a connection to PubNub.

You can use one UUID to represent a user on all their devices, or use one UUID per client. If you allow a user to connect from multiple devices simultaneously, use the same UUID for each device, as PubNub features such as Presence, which determine's a user's online status, rely on UUIDs.

For client-side SDKs, the client should obtain the user's UUID from the server after the user successfully logs in to your system. Please read User Identity & UUID Management for more details.

Access Control

Access Manager controls clients' access to PubNub resources, such as channels, channel groups, and UUIDs, through time-limited authorization tokens. PubNub provides you with a secret key meant to be used by your servers for any admin and secure interactions with PubNub. Refer to Access Control for more info.

Application Setup

Before you can use PubNub in your app, you'll need to install (or include) a PubNub SDK in your app, initialize (instantiate) a PubNub object, and add listeners for all the events that happen on the PubNub network.

Include or install

Each platform and language has different, and sometimes several, ways of getting the PubNub SDK into your app.

JavaScript
Swift
Objective-C
Android
C#
Python

Go to SDK

// 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:

Go to SDK

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.)

  1. In the project's root folder, create a Podfile using pod init (requires CocoaPods 1.0.0 or above).

  2. Open Podfile in an editor. Add pod "PubNub", "~> 4" to the target section, and replace MyObjcProject with your project name.

    Go to SDK

    platform :ios, '9.0' # (or '10.0')

    target 'MyObjcProject' do
    use_frameworks!
    pod "PubNub", "~> 4"
    end
  3. In the same directory as the Podfile, enter the command: pod install.

  4. In Xcode, open the workspace (.xcworkspace) file, not the project (.xcodeproj) file.

You can include the PubNub Android SDK using Gradle.

  1. Insert the PubNub implementation group dependency at the end of the dependencies section in build.gradle (Module: app) under the Gradle Scripts folder of your project. Your list of existing dependencies may differ.

    Go to SDK

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

    // add PubNub Android-Java SDK here at the bottom
    implementation group: 'com.pubnub', name: 'pubnub-gson', version: '4.+'
    }
  2. Click Sync Now in the top right of the Android Studio file editor window.

  3. 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>

You can also use Maven, or download the latest version of the Android SDK JAR file from the Android SDK documentation to add to your IDE or build process.

For the latest version, refer to the C# SDK documentation.

To install the many flavors of the C# SDK, refer to the following links for different package managers:

C# 3.5/4.0/4.5/4.61: https://www.nuget.org/packages/Pubnub/4.6.0.0

Universal Windows: https://www.nuget.org/packages/PubnubUWP/4.6.0.0

Xamarin.Android, Xamarin.iOS, and .NET Core/.NET Standard: https://www.nuget.org/packages/PubnubPCL/4.6.0.0

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

Go to SDK

pip install 'pubnub>=4.6.0'

Initialize a PubNub object

Now, initialize (instantiate) a PubNub object using your own publish and subscribe keys. If you don't yet have a PubNub account, go to the Admin Portal to create your free account and API keys. You'll use them in this and all other sample code that uses the myPublishKey and mySubscribeKey placeholders.

You don't have to create a new instance of the PubNub object for each message you send. When you instantiate PubNub, it creates TCP connections in a way that don't get garbage collected between uses such as publish, subscribe, here-now, etc.

Node.js
JavaScript
Python
Java
Kotlin
Go
C-Core
Unity
Swift
Objective-C
Android
C#
Dart
PHP
Ruby
const pubnub = new PubNub({
subscribeKey: 'mySubscribeKey',
publishKey: 'myPublishKey',
uuid: 'myUniqueUUID',
});

Go to SDK

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

Go to SDK

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

pnconfig = PNConfiguration()
pnconfig.publish_key = "myPublishKey"
pnconfig.subscribe_key = "mySubscribeKey"
pnconfig.uuid = "theClientUUID"

pubnub = PubNub(pnconfig)
PNConfiguration pn_config = new PNConfiguration();
pn_config.setPublishKey("myPublishKey");
pn_config.setSubscribeKey("mySubscribeKey");
pn_config.setUUID("myUniqueUUID");

PubNub pubnub = new PubNub(pn_config);
val pnConfiguration = PNConfiguration().apply {
subscribeKey = "mySubscribeKey"
publishKey = "myPublishKey"
secure = true
uuid = "myUniqueUUID"
}
val pubnub = PubNub(pnConfiguration)
pnconfig := pubnub.NewConfig()
pnconfig.SubscribeKey = "MySubscribeKey"
pnconfig.PublishKey = "MyPublishKey"
pnconfig.UUID = "MyUniqueUuid"
pn := pubnub.NewPubNub(pnconfig)
pubnub_init(ctx, "mySubscribeKey", "myPublishKey");
pubnub_set_uuid(ctx, "myUniqueUUID");
using PubNubAPI;
PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.UUID = "myUniqueUUID";

Go to SDK

import PubNub

var pnconfig = PubNubConfiguration(
publishKey: "myPublishKey",
subscribeKey: "mySubscribeKey"
)

pnconfig.uuid = "theClientUUID"
let pubnub = PubNub(configuration: pnconfig)

Go to SDK

#import <PubNub/PubNub.h>

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

Go to SDK

import com.pubnub.api;

PNConfiguration pnconfig = new PNConfiguration();
pnconfig.setPublishKey("myPublishKey");
pnconfig.setSubscribeKey("mySubscribeKey");
pnconfig.setUuid("theClientUUID");

PubNub pubnub = new PubNub(pnconfig);

Go to SDK

using PubnubApi;

PNConfiguration pnconfig = new PNConfiguration();
pnconfig.PublishKey = "myPublishKey";
pnconfig.SubscribeKey = "mySubscribeKey";
pnconfig.Uuid = "theClientUUID";

Pubnub pubnub = new Pubnub(pnconfig);
final myKeyset = Keyset(
subscribeKey: 'mySubscribeKey',
publishKey: 'myPublishKey',
uuid: UUID('myUniqueUUID')
);
use PubNub\PNConfiguration;
$pnConfiguration = new PNConfiguration();
$pnConfiguration->setSubscribeKey("MySubscribeKey");
$pnConfiguration->setPublishKey("MyPublishKey");
$pnConfiguration->setUuid("MyUniqueUuid");
pubnub = Pubnub.new(
subscribe_key: 'my_subscribe_key',
publish_key: 'my_publish_key',
uuid: 'my_unique_uuid'
)

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

Initialize with secret key

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

You should only use the secret key within a secure server and never expose it to client devices. If the secret key is ever compromised, it can be an extreme security risk to your application.

Node.js
Python
Java
Kotlin
Go
C-Core
Unity
C#
Dart
PHP
Ruby
const pubnub = new PubNub({
subscribeKey: 'mySubscribeKey',
publishKey: 'myPublishKey',
uuid: 'myUniqueUUID',
secretKey: 'mySecretKey'
});
pn_config = PNConfiguration()
pn_config.publish_key = "my_publish_key"
pn_config.subscribe_key = "my_subscribe_key"
pn_config.uuid = "my_unique_uuid"
pn_config.secret_key = "my_secret_key"

pubnub = PubNub(pn_config)
PNConfiguration pn_config = new PNConfiguration();
pn_config.setPublishKey("myPublishKey");
pn_config.setSubscribeKey("mySubscribeKey");
pn_config.setUUID("myUniqueUUID");
pn_config.setSecretKey("mySecretKey");

PubNub pubnub = new PubNub(pn_config);
val pnConfiguration = PNConfiguration().apply {
subscribeKey = "mySubscribeKey"
publishKey = "myPublishKey"
secretKey = "mySecretKey"
secure = true
uuid = "myUniqueUUID"
}
val pubnub = PubNub(pnConfiguration)
pnconfig := pubnub.NewConfig()
pnconfig.SubscribeKey = "MySubscribeKey"
pnconfig.PublishKey = "MyPublishKey"
pnconfig.SecretKey = "MySecretKey"
pnconfig.UUID = "MyUniqueUuid"
pn := pubnub.NewPubNub(pnconfig)
pubnub_init(ctx, "mySubscribeKey", "myPublishKey");
pubnub_set_secret_key(ctx, "mySecretKey");
pubnub_set_uuid(ctx, "myUniqueUUID");
using PubNubAPI;
PNConfiguration pnConfiguration = new PNConfiguration();
pnConfiguration.SubscribeKey = "my_subkey";
pnConfiguration.PublishKey = "my_pubkey";
pnConfiguration.SecretKey = "my_secretkey";
pnConfiguration.UUID = "myUniqueUUID";
PNConfiguration pnconfig = new PNConfiguration();
pnconfig.SubscribeKey = "mySubscribeKey";
pnconfig.PublishKey = "myPublishKey";
pnconfig.SecretKey = "mySecretKey";
pnconfig.Uuid = "myUniqueUuid";
Pubnub pubnub = new Pubnub(pnconfig);
final myKeyset = Keyset(
subscribeKey: 'mySubscribeKey',
publishKey: 'myPublishKey',
secretKey: 'mySecretKey',
uuid: UUID('myUniqueUUID')
);
use PubNub\PNConfiguration;
$pnConfiguration = new PNConfiguration();
$pnConfiguration->setSubscribeKey("MySubscribeKey");
$pnConfiguration->setPublishKey("MyPublishKey");
$pnConfiguration->setSecretKey("MySecretKey");
$pnConfiguration->setUuid("MyUniqueUuid");
pubnub = Pubnub.new(
subscribe_key: 'my_subscribe_key',
publish_key: 'my_publish_key',
secret_key: 'my_secret_key',
uuid: 'my_unique_uuid'
)

For more information on deleting messages from history, refer to the particular SDK documentation.

Architectural Decisions

For a straightforward use case, go through the architecture decisions page. For advanced use cases where you may want to aggregate messages on the server, refer to the server message aggregation guide. As your app will definitely use channels, familiarize yourself with channel naming conventions. If you're building a social app, make sure to go through building friend lists and status feeds.

Next Steps

Now that you have your account, go publish some messages!

← PubNub accountUsers & devices →
  • UUIDs
  • Access Control
  • Application Setup
    • Include or install
    • Initialize a PubNub object
  • Architectural Decisions
  • Next Steps
© PubNub Inc. - Privacy Policy