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.
// 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>=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.
const pubnub = new PubNub({
subscribeKey: 'mySubscribeKey',
publishKey: 'myPublishKey',
uuid: 'myUniqueUUID',
});
<script type="text/javascript">
var pubnub = new PubNub({
publishKey: "myPublishKey",
subscribeKey: "mySubscribeKey",
uuid: "theClientUUID"
});
<script>
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";
import PubNub
var pnconfig = PubNubConfiguration(
publishKey: "myPublishKey",
subscribeKey: "mySubscribeKey"
)
pnconfig.uuid = "theClientUUID"
let pubnub = PubNub(configuration: pnconfig)
#import <PubNub/PubNub.h>
PNConfiguration *pnconfig = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
subscribeKey:@"mySubscribeKey"];
pnconfig.uuid = "theClientUUID";
PubNub *pubnub = [PubNub clientWithConfiguration:pnconfig];
import com.pubnub.api;
PNConfiguration pnconfig = new PNConfiguration();
pnconfig.setPublishKey("myPublishKey");
pnconfig.setSubscribeKey("mySubscribeKey");
pnconfig.setUuid("theClientUUID");
PubNub pubnub = new PubNub(pnconfig);
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!