Developer Communities Manager, PubNub
IN THIS ARTICLE

    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 Realtime 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 realtime 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:
    Image of link to My First App in Administration interface

    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.
    Publish, Subscribe and Secret Keyset for this application

    To begin sending and receiving messages, we need to be in the debug console. Find it in the lower left of the administration screen.
    Link to the debug console in PubNub administration interface

    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

    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.
      Add client with Jana details filled in

    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).
    Side by side messaging screens in debug console

    In the ‘text’ area at the bottom of the Akara client, replace {"text" : "Enter Message Here"} with {"text" : "I love sourdough!"}.
    Image of text input showing “{'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.

    Note: The admin panel uses the PubNub Javascript SDK under the hood.

    Very quickly (under 100 milliseconds), the message will be displayed on both consoles.
    Side by side consoles showing the published text, “I love sourdough!” has arrived

    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."}.
    Image of text input showing {"text": "Banana bread is the best."}

    Press Send.

    Again, the message is sent to PubNub to be distributed to all subscribers.
    Side by side consoles showing published text "Banana Bread is the best" has arrived

    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.
     Image of text input showing {"text": "I love sourdough!", "msgid": 1}

    PubNub message objects
    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}.
    Image of text input showing {"text": "Banana bread is the best", "msgid": 2}

    After sending both messages, the consoles should reflect them.
    Two debug consoles showing received messages with message IDs

    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.
    Image of text input showing {"reaction": ":blech:", "referenceid": 1}

    Both Akara and Jana receive it.
    Two debug consoles showing received messages with reactions

    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 realtime experiences, freeing you and your development team to build amazing customer interactions.

    Adding User 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.
    Location of the “show presence” button in the administration interface

    When you click the button, you will likely see an error stating “Presence is not enabled on this key.”
    Error message: 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.
    Keys link in administration interface.

    Click on “Demo Keyset” (or similar) in your environment.
    Demo Keyset image

    Enable the Presence button.
    Presence button area

    When you switch the Presence button, a verification popup will show. Type “ENABLE” and click the “Enable” button.
    Enable button popover

    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).
    Save changes button

    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.
    Occupancy panel showing 3 clients

    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
    Adding Jackson as a new client

    Press Add Client.

    With the new Jackson client, there are now 4 clients connected.
    Occupancy panel showing 4 clients

    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.
    History button in the upper right corner of the admin screen

    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”.
    Storage and Playback settings

    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?"}.
     {“text” : “Has anyone made Whole Wheat?”} with a send button

    After sending, the History console should show the new message:
    History panel showing message: “Has anyone made Whole Wheat?”

    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.

    PubNub Functions

    PubNub 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 “PubNub Functions.”
    PubNub 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
    Create new module screen with “Cooking” filled

    Click “Create new module”

    Modules are collections of functions attached to a specific PubNub Application & Keyset.

    On the next “Cooking” module screen, click the “Create Function” button.
    Create function screen

    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
    Create new before publish function screen

    This screen is the main editor for functions. The default editor will give you some basic code to start.
    Starter code for a new function

    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 PubNub 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.
    Doubled code in the editor

    Save the modified code with the button on the left.
    Save function button

    Finally, we need to start our module (in the upper right-hand corner):
    Start module button

    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.
    Doubler console output

    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.
    3 consoles showing received 'doubled' 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.
    View of cooking module

    Create a new function. Fill in the following:
    Name: Couponing
    Event: After publish for fire
    Channel: cooking.baking.bread
    New function screen with “couponing” filled in

    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).
    Restart button

    Wait until the block is deployed:
    Block: Module is now globally 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.
    Coupon output

    “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 realtime 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.

    Try PubNub today!

    Build realtime applications that perform reliably and securely, at global scale.
    Try Our APIs
    Try PubNub today!
    More From PubNub

    Footer Html for Blog Page