Application Setup
There are two important concepts that require your attention before you start setting up your application.
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
Setting a User ID is required to establish a connection to PubNub.
You can use one User ID to represent a user on all their devices, or use one User ID per client. If you allow a user to connect from multiple devices simultaneously, use the same User ID for each device, as PubNub features such as Presence, which determine's a user's online status, rely on User IDs.
For client-side SDKs, the client should obtain the User ID from the server after the user successfully logs in to your system. Please read Users & Devices for more details.
Access Control
Access Manager controls clients' access to PubNub resources, such as channels, channel groups, and User IDs, 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
// 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. Addpod "PubNub", "~> 4"
to thetarget
section, and replaceMyObjcProject
with your project name.platform :ios, '9.0' # (or '10.0')
target 'MyObjcProject' do
use_frameworks!
pod "PubNub", "~> 4"
endIn 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 Android SDK using Gradle.
Insert the PubNub
implementation group
dependency at the end of thedependencies
section inbuild.gradle (Module: app)
under the Gradle Scripts folder of your project. Your list of existing dependencies may differ.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.+'
}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>
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
:
pip install pubnub
Initialize a PubNub object
Now, initialize (instantiate) a PubNub object using your own publish and subscribe keys and a User ID. 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.
- JavaScript
- Python
- Java
- Kotlin
- Go
- C
- Unity
- Swift
- Objective-C
- Android
- C#
- Dart
- PHP
- Ruby
<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)
final UserId userId = new UserId("myUniqueUserId");
PNConfiguration pnConfig = new PNConfiguration(userId);
pnconfig.setPublishKey("myPublishKey");
pnconfig.setSubscribeKey("mySubscribeKey");
PubNub pubnub = new PubNub(pnConfig);
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 PubNub
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];
import com.pubnub.api;
final UserId userId = new UserId("myUniqueUserId");
PNConfiguration pnConfig = new PNConfiguration(userId);
pnconfig.setPublishKey("myPublishKey");
pnconfig.setSubscribeKey("mySubscribeKey");
PubNub pubnub = new PubNub(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 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
- Unity
- C#
- Dart
- PHP
- Ruby
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)
final UserId userId = new UserId("myUniqueUserId");
PNConfiguration pnConfig = new PNConfiguration(userId);
pn_config.setPublishKey("myPublishKey");
pn_config.setSubscribeKey("mySubscribeKey");
pn_config.setSecretKey("mySecretKey");
PubNub pubnub = new PubNub(pn_config);
val config = PNConfiguration(UserId("myUniqueUserId")).apply {
subscribeKey = "mySubscribeKey"
publishKey = "myPublishKey"
secretKey = "mySecretKey"
secure = true
}
val pubnub = PubNub(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 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.