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.

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

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.

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.

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 →