PubNub has software development kits (SDKs) available for all of the popular programming languages. These SDKs help speed time to market when building customer experiences like chat, IoT and multiplayer gaming based on the PubNub Real-time Data Stream Network. However, sometimes it is not possible to install an SDK, or maybe you’re not a developer in the first place.
But you do want to understand what PubNub does and how it can help you and your team facilitate real-time features.
Luckily, PubNub has an Admin Dashboard that allows you to experiment with many of the capabilities that are present in the SDKs without installing anything. Couple that with PubNub’s generous 1 million free messages a month starter plan and you can learn enough to get you started.
In this tutorial, we will cover the following capabilities:
- Basic message passing as part of a customer chat
- Extending chat with reactions using PubNub’s flexible message objects
- Presence functionality – knowing who is in the chat room
- History – retrieving past messages
- A “before publish” PubNub serverless function to modify messages before delivery
- An “after publish” PubNub serverless function to deliver targeted marketing messages to the chat room
Getting Started with PubNub
Sign up with PubNub (it’s free and there is no credit card required).
After login, the first app screen will show:
Clicking on “My First App” will show the “Keyset” for this application. These are the keys that would normally be inserted into code to allow your application to interact with the PubNub service. We do not need these for now.
To begin sending and receiving messages, we need to be in the debug console. Find it in the lower left of the administration screen.
Adding Clients to a Channel
We will create two “clients,” which will represent two people in a chat room. To make this demo a bit more real, we will assume that we are building a chat app around cooking and that this is the bread baking room (aka “channel” in PubNub parlance). Set up the first client.
In the “add client” area, fill in the following details:
Default Channel: cooking.baking.bread
- This is the channel we will publish messages to and receive messages from. Channels are lightweight and developer created. There can be thousands of them. The name of a channel is a string with a few restrictions.
Client UUID: Jana
- The UUID is how PubNub identifies who published(sent) a message that passes through its network. Think of it as an address. Typically it is a UUID but that is not required.
Authorization key: Leave blank
- The Authorization key is used with PubNub’s authentication module to provide extra security and policies around who can send and receive messages. We will not be experimenting with that.
Press Add Client.
A notification that the client was created should show along with a new “Jana” panel.
Before we send any messages, we should create someone for Jana to chat with. Create another client with the following details:
Default Channel: cooking.baking.bread
Client UUID: Akara
Authorization key: Leave blank
Press Add Client.
Sending Messages to a Channel
At this point, you should have two clients on your screen, Akara and Jana. They are each subscribed to the “cooking.baking.bread” channel. This means that any message sent to that channel will be sent to both clients (and all other subscribed clients within your application).
In the ‘text’ area at the bottom of the Akara client, replace {"text" : "Enter Message Here"} with {"text" : "I love sourdough!"}.
Press Send.
When you press send, the text is sent as part of a message object to PubNub, which then sends it to all subscribers.
Very quickly (under 100 milliseconds), the message will be displayed on both consoles.
Not to be left out, Jana wants to share her love of Banana bread. In Jana’s console, change the text {"text" : "Enter Message Here"} with {"text" : "Banana Bread is the best."}.
Press Send.
Again, the message is sent to PubNub to be distributed to all subscribers.
Add Reactions to Messages
In the last section, Akara and Jana sent simple text messages to each other. Most immersive chat apps allow a user to respond to a message with a simple reaction (emoji). PubNub supports this and many other types of interactions with a flexible messaging framework. For this section, let’s add a reaction to one of the messages. To react to a message, we need to be able to address that specific item. To do that, we’ll add a message ID to our messages.
From our Akara and Jana console screens, send another message.
In the ‘text’ area at the bottom of the Akara client, replace {"text" : "I love sourdough!"} with {"text" : "I love sourdough!", "msgid": 1}. Notice that we’ve added a msgid property to our message object.
PubNub sends and receives JSON. A developer can put anything into the message object. “Text” is a common property but it is not required. The message that is published to the PubNub interface will then be wrapped in an “envelope” JSON object before being delivered. The admin interface we are using hides much of the envelope, but it is there, underneath.
Having sent the “I love sourdough” message with a msgid, let’s have Jana send a similar Banana Bread message with a msgid. Modify the text of Jana’s console to add a msgid {"text" : "Banana Bread is the best!", "msgid": 2}.
After sending both messages, the consoles should reflect them.
Since each message now has an identifier, we can react to those messages by referencing them in the reaction payload.
Jana is not a fan of sourdough, so she “sends” a blech face message. Modify the text of Jana’s console to {"reaction" : ":blech:", "referenceid": 1}. Surrounding a reaction with two “:” characters is a common way to indicate that an emoji is called for.
Both Akara and Jana receive it.
PubNub delivers this message as a JSON text object. However, an application would not normally show it as text. How and where to show a “reaction” would be up to the developer. It could be presented as part of the chat window or it could be a special image or emoticon. That is up to your interface. PubNub does not proscribe how your interface displays the messages. PubNub focuses on the difficult scaling infrastructure for real-time experiences, freeing you and your development team to build amazing customer interactions.
Adding Presence
In addition to standard message passing, PubNub provides the ability for each subscribed client to also send and receive Presence information, meaning, who is currently connected to the channel. To see Presence for our two clients, Jana and Akara, click the Presence button to the right, just above the consoles. You may have to scroll your screen down to show the button, sometimes it gets tucked under the name of the app.
When you click the button, you will likely see an error stating “Presence is not enabled on this key.”
Presence is an optional feature that needs to be enabled. We can do that as part of the keys section of the administrative interface.
Click the keys link on the left side of the admin interface.
Click on “Demo Keyset” (or similar) in your environment.
Enable the Presence button.
When you switch the Presence button, a verification popup will show. Type “ENABLE” and click the “Enable” button.
For the moment, you can leave the rest of the Presence options alone. These options allow for greater tuning of Presence, especially with large numbers of clients.
Don’t forget to save changes (lower right corner).
Now, open the debug console again (click the button in the lower-left corner). If the client consoles for Akara and Jana are not there, add them. Click Presence (button in the middle right corner) and another panel should show with an occupancy of 3. Note: The “Console_Admin” client is always there as part of the administration interface.
When a new client subscribes to a channel, all clients in the channel get a notification of the join. Similarly, when someone leaves, a notification is sent to all clients.
To test this, add another client. In the empty client on the right, modify the fields to:
Default Channel: cooking.baking.bread
Client UUID: Jackson
Authorization key: Leave blank
Press Add Client.
With the new Jackson client, there are now 4 clients connected.
The Presence functionality allows developers to check the number of people in a channel, such as a chat room or in a game.
Using History
History button next to the Presence button.
It is likely you will see an error “Storage and Playback is not enabled on this key.” History, like Presence, is an optional component that needs to be turned on. As we did with Presence, click on the “Keys” button on the left and click through to “Demo Keyset”. Scroll to “Storage & Playback” and slide the switch to “on”.
Leave the defaults for all of the sub-settings and click “Save changes” in the lower right.
Return to the debug console.
Akara, Jana and Jackson’s individual consoles should be recreated by the debug console. If not, create them.
Click the History button and you should see an empty History console.
In Akara’s console send the following message: {"text" : "Has anyone made Whole Wheat?"}.
After sending, the History console should show the new message:
PubNub allows developers to store History data in a replicated cloud store for easy retrieval and playback. Use it for reloading conversations when new clients connect or other places where History is needed.
Functions
Functions allow developers to execute business logic as part of a serverless environment. Functions listen to channels and will trigger when the right conditions are met. There are 4 types of functions: “Before Publish,” “After Publish,” “After Presence,” and “On Request.” We will focus on “before publish” and “after publish” types. More details on functions and the many ways you can use them can be found on our Functions page.
Similar to Presence and History, to use Functions, we need to enable them. Click the “Keys” option on the left, click through “Demo Keyset’ and enable “Functions.”
Don’t forget to save.
Add a “Before publish” Function
For an easy example, we are going to allow a user to ask the chat room to double a recipe. We will create a function that matches any message containing “1 tsp” and add a “doubled” property of “2 tsp.”
Click the “Functions” button on the left hand side, just below “Keys”. On the following “Modules” page, create a new module with the following properties:
Module name: Cooking
Description: Cooking related functions
Click “Create new module”
On the next “Cooking” module screen, click the “Create Function” button.
Click “Create function” and fill in the resulting pop-over with:
Function name: Doubler
Event type: Before Publish or Fire
Channel name: cooking.baking.bread
This screen is the main editor for functions. The default editor will give you some basic code to start.
We will remove the kvstore and xhr lines because we won’t use them. KV Store allows developers to store items in a distributed database and XHR allows a developer to reach out to another service from within Functions and bring data back into the system.
Change the code in the editor to the following:
export default (request) => {
console.log('request',request); // Log the request envelope passed
if (request.message.text === "1 tsp") {
request.message.doubled = "2 tsp";
}
return request.ok(); // Return a promise when you're done
}
We won’t review every line, but the active part looks at the “text” property of our “message” object (which is wrapped in a “request” object) and matches it against “1 tsp”. If it matches, it adds a property to the message called “doubled” and makes it equal to “2 tsp”. As a reminder, how an application displays this extra “doubled” property is up to the developer.
Save the modified code with the button on the left.
Finally, we need to start our module (in the upper right-hand corner):
We can test the doubler code works by sending test content. In the lower-left corner, find the “Test Payload” option and paste in:
{
"text": "1 tsp"
}
Then click Publish.
The output should show a doubled amount.
Switching back to the debug console (home button, then debug console button), send a “1 tsp” message as part of a “text” message and everyone should get a “doubled” property attached to the delivered message.
“Before publish” functions are useful for reviewing and changing content before it is delivered to everyone. Be careful though, delivery for that message is blocked until the function completes. If the function calls another web service and the API on the other end takes time to return, it can significantly slow down message delivery.
Add an “After Publish” Function
“After Publish” functions fire after a message has been delivered to all of the subscribers. Useful in logging contexts, it can also be used to add to the experience. In this case, we imagine that we scan the baking chat for people shopping for specific items. Then we present a coupon if one of our partners has a sale. This is not dependent on filtering items before delivery so we can safely wait until after the publish event.
Switch back to functions (left hand button) and then click the “cooking” module we created earlier.
Create a new function. Fill in the following:
Name: Couponing
Event: After publish for fire
Channel: cooking.baking.bread
Click create.
Again, there will be some basic code for a function, most of which we won’t need. Replace it with:
export default (request) => {
const pubnub = require('pubnub');
if (request.message.text.indexOf("flour") > -1 && request.message.agent != "coupon-specials") {
return pubnub.publish({
"channel": "cooking.baking.bread",
"message": {
"coupon": "15% off ",
"text": "The store has flour at 15% off",
"agent": "coupon-specials"
}
}).then((response) => {
return request.ok();
});
}
return request.ok(); // Return a promise when you're done
}
The work happens on line 3. First we see if someone mentions flour, then we make sure that the ‘agent’ is not our “coupon-specials” bot. An agent, in this case, is just what we will call our bot to distinguish it from a user. If both are true, we publish a message to the “cooking.baking.bread” channel with a coupon code. If we don’t check for the message agent, an infinite loop can occur. The functions system will prevent it, but an error will result.
Save the function, then restart the module (upper right).
Wait until the block is deployed:
And test. In Jana’s text area, change the text to {"text": "Where should I get flour?"} and “Send.” After that message is received, a second message should be received with our coupon offer.
“After publish” functions are useful for logging and adding functionality to connected users that are not dependent on a message being delivered. Use a mix of the XHR functionality to request information from external web services, the KV Store to save the information, and publish functionality to send something back to a channel.
Conclusion
We can learn much about how PubNub can help your team achieve real-time magic for your customers with the debug console. The console is also useful when you have built something and want to test sending and receiving.
Your next step is to download one of the many SDKs and build something amazing. We look forward to seeing what you build.