Automated polling

PubNub enables real-time analytics and automated customer-behavior-driven decisioning for live sports applications, creating dynamic experiences that adapt instantly to fan engagement and how they interact with your application.

By the end of this document, you will:

• Understand how to trigger dynamic polls based on user reactions and engagement
• Discover how to track real-time analytics and make automated content decisions

How PubNub helps

PubNub provides a robust infrastructure for implementing manual and automated real-time polling systems.

Role in the solution	PubNub feature (click to learn more!)
Track user engagement in real time	Pub/Sub
Trigger polls and surveys based on user engagement	PubNub Illuminate

Use case overview

The Live Events demo shows how you can respond to user behavior in real-time. By targeting specific milestones in your app, you automate actions to enhance the user experience and monetize engagement by unlocking additional features for active users or offering incentives before they disengage.

The demo will take action based on the following user behavior:

• Triggers: The demo uses emoji reactions (😡, 🎉) as triggers, but you could also trigger actions based on chat mentions, poll participation, or any custom user behavior you want to track.

• Processing: The demo aggregates emoji reactions over a 60-second window, but you could also process events immediately (like responding to a mention) or implement custom processing logic based on your needs.

• Actions: When triggers are processed, the demo shows automated actions like displaying a custom poll ("Which team is playing the dirtiest?"), but you could also trigger emoji upgrades, dynamic ads, or any custom response you define.

See it in action

Notice in the clip below how the 🔥 emoji changes to 😎 and the "Time to unwind?" ad appears when the user gets increasingly frustrated.

Basic setup for automated polling

The Live Events demo uses PubNub Illuminate to trigger emoji upgrades, polls, and dynamic ads based on user behavior.

PubNub Illuminate is designed to enhance real-time applications by providing advanced analytics and automated decision-making capabilities without changing the application code.

It allows product managers to create dynamic user experiences by reacting to user engagement and behavior in real-time. With Illuminate, you can trigger actions such as polls, surveys, and targeted advertisements based on user interactions, ensuring that content is always relevant and engaging.

Before you can leverage the powerful features of PubNub Illuminate for real-time analytics and automated decision-making, ensure the following prerequisites are met:

Prerequisite	Description
PubNub account	You must have an active PubNub account. If you don't have one, you can sign up on the Admin Portal.
Any PubNub SDK	Your app must use a PubNub SDK. This is essential for connecting your app to the PubNub network and utilizing Illuminate's capabilities.
Illuminate subscription	Ensure that your PubNub pricing plan includes Illuminate. For more information, refer to PubNub Pricing.

SDK configuration

You can use any PubNub SDK to implement this solution. For optimal performance and security:

• Use unique user IDs for each user, but reuse it for different client devices ( mobile, tablet, via browser) of the same user.
• Keep your publish and subscribe keys secure.
• Consider using environment variables for sensitive data.

For more information on available configuration options, refer to the Configuration documentation of the SDK you're using. The Live Events demo app uses the JavaScript SDK via the JavaScript Chat SDK, which provides chat-specific methods as well as the core JavaScript SDK operations, but that's not important to illustrate how automated decisioning works.

Automated poll triggering

In the Live Events demo, automated polling is triggered by real-time user engagement. For example, when a surge of emoji reactions or specific user behaviors is detected, the system can automatically launch a poll to gather feedback or predictions from the audience.

When the user taps the 😡 or 🎉 emojis more than 20 times in 60 seconds, Illuminate triggers a poll to gather feedback or predictions from the audience.

When the poll is displayed, users can submit their votes, and the results can be processed and displayed instantly.

Track emoji taps

When a user taps an emoji (e.g., 😡), a message is published to a dedicated channel (e.g., game.stream-reactions) with the following data:

async function emojiClicked(emoji) {
  if (!chat) return
  await chat.sdk.publish({
    message: { text: `${emoji}`, type: 'reaction' },
    channel: streamReactionsChannelId
  })
}

Depending on the emoji tapped, the app reacts differently. In this case, we use the 😡 emoji tap as an indicator of frustration and the 🎉 emoji tap as an indicator of excitement, but you can use any behavior you want to track and react to.

Tracking other emoji taps

For information on tracking other emoji taps, refer to Real-time ads and updates.

Configure Illuminate

Now that we have a steady stream of data on the game.stream-reactions channel, we can configure Illuminate to trigger the corresponding poll based on the user's behavior.

Illuminate consists of these modules:

• Business Object – how you get data into Illuminate. Business Objects are containers for capturing data from the selected apps and keysets. You can add and define (data fields, create metrics) with the desired aggregation, and activate Business Objects to start the data capture process.
• Decision – where you take action on the metrics you've created. You can do that by defining rules with conditions to be met, and actions triggered whenever these rules are met.
• Dashboard – where you visualize the metrics you've created in Business Objects and actions executed in Decisions through charts and dashboards (collections of charts).

Let's start with creating a Business Object.

Create a Business Object

In Illuminate, the first thing to do is create a business object. You can see what the business object looks like in detail in the Demo Admin portal account here.

When you create a new business object, you must attach it to an app and keyset and map the data fields to the events you want to track. For detailed information on creating business objects, refer to Create Business Object. In the meantime, inspect the business object that the Live Events demo uses.

Field Name	Mapped From	Type	Description
Reaction	$.message.body.text	String	This is the emoji or user reaction content. It captures the emoji tapped by the user, providing insight into user interactions and preferences.
Channel	$.message.channel	String	This captures the channel name on which the message was sent.
MessageType	$.message.body.type	String	This is always reaction in the Live Events demo, but if you are sending multiple message types on the same channel, you can filter them by this field.

You can use the data fields for conditional logic, but more on that later. For now, let's focus on what we want to track.

Create metrics

By defining specific metrics, product managers can tailor the user experience to be more responsive and engaging, ensuring that the application reacts to user behavior in meaningful ways. For detailed information on creating metrics, refer to Create Metric.

In the Live Events application, the Count of Reactions in a Minute metric tracks how many user reactions (emoji taps) occur in a specific channel, filtered by message type and evaluated every minute. It's used to power decisions such as emoji upgrades, dynamic ads, and live polls.

Field	Value	Description
Name	Count of Reactions in a Minute	Human-readable name for the metric, used in dashboards and decisions.
Function	COUNT	Aggregation function that counts the number of messages matching the filter during each evaluation period.
Measure	None	No custom numeric field is being measured (e.g., summing a value). The metric just counts the number of matching events.
Period	1 minute	The aggregation window. Messages are counted over a rolling one-minute period.
Filter	Channel Equals game.stream-reactions MessageType Equals reaction	Filters incoming PubNub messages to only include messages of type reaction sent on the game.stream-reactions channel.
Dimensions	Reaction, Channel, MessageType	Fields used to group the metric data. Allows the count to be tracked separately for each unique emoji (reaction), channel, and message type.
Used in Decisions	Emoji Upgrades & Ads	This metric triggers downstream Illuminate Decisions that perform actions like upgrading emojis or launching dynamic content (e.g., polls).
Used in Dashboards	Live Events	This metric is also used in the Showcase: Live Events dashboard for monitoring and visualizing reaction activity in real-time.

To start capturing and storing the data, you must activate the business object.

Activate the business object

When you click the Activate button, Illuminate starts capturing the emoji taps until you deactivate or delete the business object. You can't add or remove data fields once you've activated a business object, but you can add a metric to it.

Data you defined in business objects and subsequently captured are housed in a single database for 90 days.

With the business object that is configured and active, you can create a decision or a dashboard.

Before you activate

Create a decision

Decisions are the core of Illuminate. They are triggered by metrics and contain rules that define the conditions for actions to be executed. You can see the decision in detail in the Demo Admin portal account here.

More on decisions

The Live Events demo has a dedicated decision to trigger a poll when a user taps the 😡 or 🎉 emojis more than 20 times in 60 seconds.

Each decision must have at least one associated condition and action. The Live Events demo has one action:

Action	Description
Showcase: Live Event Start Poll	Starts a poll depending on the user's reaction.

Live Event Start Poll

The Showcase: Live Event Start Poll action creates a new poll when user engagement metrics meet specific criteria. In the Live Events demo, the action is configured to run once per minute to avoid spamming the channel with new polls.

This action publishes a message to the game.server-video-control channel with the following payload:

{
  "type": "ON_DEMAND_SCRIPT",
  "params": {
    "emoji": "Reaction"
  }
}

The emoji is defined as Reaction because, in your Illuminate metric, you map incoming fields from PubNub messages to named fields so you can use them later. Remember when we mapped reaction to $.message.body.text during the Create a Business Object step? This is how we can use the actual emoji tapped by the customer in the Illuminate decision.

The Live Events demo uses a simple backend server to trigger polls and show the principles of automated polling. Based on the emoji in the message sent from Illuminate, the server publishes a message to the game.new-poll channel.

😡 tapped

await pubnub.publish({
  channel: "game.new-poll",
  message: {
    id: 101,
    title: "Which team is playing the dirtiest?",
    victoryPoints: 0,
    alertText: "Take your frustration out on this poll",
    pollType: "side",
    options: [
      { id: 1, text: "Leeds United" },
      { id: 2, text: "Southampton FC" }
    ]
  }
});

🎉 tapped

await pubnub.publish({
  channel: "game.new-poll",
  message: {
    id: 102,
    title: "Which team's fans are celebrating the hardest?",
    victoryPoints: 0,
    alertText: "Only winners unlock this poll",
    pollType: "side",
    options: [
      { id: 1, text: "Leeds United" },
      { id: 2, text: "Southampton FC" }
    ]
  }
});

The Live Events demo allows the dynamic poll to run for 30 seconds and tabulates results during that time. When the time is up, results are displayed to all users.

More about live polling

For more information on working with live polls, refer to Live polling.

By leveraging PubNub Illuminate, you can automate real-time polling in your applications that respond instantly to user engagement. The best thing about it is that you don't need to change your app code to do it. Once set up in the app, you can change the decision rules and actions directly in Illuminate.