Polls & Quizzes

The Poll feature in the HMS SDK allows you to create, manage, and participate in Polls and Quizzes. Polls are an effective way to gather opinions, feedback, and insights from a group of people in a quick and convenient manner. With the Poll feature, you can create custom polls, set their properties, add questions, and manage responses. You can also receive real-time updates on poll status, and view poll results in an organized and easy-to-use format.

This feature can also be used to create Quizzes. Under the hood, Quizzes are like polls where questions have right or wrong answers.

This document provides guidance on how to use the Poll APIs to create a poll, receive updates on a poll, and vote on a poll.

Prerequisites

• SDK 1.9.11 or higher
• Poll Read permission should be enabled for roles that can view polls.
• Poll Write and Poll Read permission should be enabled for roles that can create polls.

Creating a Poll

Quick Start

Here is how to quickly start a poll

Let's consider an example. We'll create a single-choice poll with the title Survey and the question Do you like TypeScript? The poll will offer two options: Yes and No.

await hmsInstance.interactivityCenter.startPoll({
    pollId: 'myUniqueID',
    title: 'Survey',
    type: HMSPollType.poll, // or `HMSPollType.quiz`
    mode: HMSPollUserTrackingMode.customerUserID,
    questions: [
        {
            index: 1,
            text: 'Do you like TypeScript?',
            type: HMSPollQuestionType.singleChoice,
            skippable: false,
            options: [
                {
                    text: 'Yes',
                    // isCorrectAnswer: true // In case of quiz
                },
                {
                    text: 'No',
                    // isCorrectAnswer: false // In case of quiz
                }
            ]
        }
    ]
});

The above code will create a Poll with the specified title and a single choice question and share it with the Room.

Receiving Updates on a Poll

Once you have started a Poll, you can receive real-time updates on the poll's status using the addPollUpdateListener method. This method allows you to listen for updates on the poll, such as when the poll is started, when the results are updated, and when the poll is stopped.

///  enum HMSPollUpdateType {
///     started,
///     resultsUpdated,
///     stopped,
/// }

useEffect(() => {
    const subscription = hmsInstance.interactivityCenter.addPollUpdateListener(
        (poll: HMSPoll, pollUpdateType: HMSPollUpdateType) => {
            console.log('Poll Update: ', poll, pollUpdateType);
        }
    );
    return () => {
        subscription.remove();
    };
}, []);

You can use the HMSPoll object to access information about the poll, such as its current state, duration, and questions.

Voting on a Poll

To participate in a poll, you can use the add(pollQuestionResponseParams: PollQuestionResponseCreateParams) method. This method allows you to vote on a poll by providing the poll ID, the index of the question you want to answer, and the response you want to submit.

/// index of the selected Poll Question option
const selectedOptionIndex = 1;

await hmsInstance.interactivityCenter.add({
    pollId,
    pollQuestionIndex: pollQuestion.index, // index of the question
    responses: {
        options: [selectedOptionIndex] // array of selected option indices, single item if it's a single-choice question and one or more if it's a multiple-choice question
    }
});

Once you have submitted your responses, other peers in the room will get POLL_VOTES_UPDATED notification. You can check updated vote counts for each option of poll questions.

Stopping a Poll

Use hmsInstance.interactivityCenter.stop(pollId: string) method when you want to stop the Poll and prevent further responses recorded.

await hmsInstance.interactivityCenter.stop(pollId);

Fetching the Quiz Leaderboard

Once the quiz has ended, the leaderboard can be fetched which has the quiz summary and peer level statistics sorted by score using the asynchronous fetchLeaderboard function added to the interactivityCenter.

const response = await hmsInstance.interactivityCenter.fetchLeaderboard(
  quizId, // `pollId` of the poll/quiz
  5, // The number of peer entries that should be fetched at a time
  1, // The position offset after which the peer level entries should be fetched
  false, // Whether to include the current peer in the fetched leaderboard entries
);

The props accepted are:

• quizId :HMSPoll - pollId of the poll/quiz
• count :number - The number of peer entries that should be fetched at a time
• offset :number - The position offset after which the peer level entries should be fetched, Note that "Indexing starts from 1"
• includeCurrentPeer: boolean - Whether to include the current peer in the fetched leaderboard entries

The response contains:

• An array of entries of type HMSPollLeaderboardEntry,
• A boolean hasNext which indicates if there are more entries to be fetched, and
• An object of type HMSPollLeaderboardSummary containing details like the average score, average time taken to answer a question, number of users with all correct answers and more.

{
  entries: [...],
  summary: {
    totalUsers: number,
    votedUsers: number,
    avgScore: number,
    avgTime: number,
    correctUsers: number,
  };
  hasNext: false
}

Viewing Poll Results Summary

After poll has ended you can use poll.result to get statistics like how many peers responded and how many total peers were in the room at the time of poll.