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.

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

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.

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

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',
   userId: "myUniqueUserId",
   secretKey: 'mySecretKey'
});

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.

Last updated on
On this page