Develop your App

It’s time to write your first app. We’ve provided documentation above how to scaffold your template to get you started.

Initialise the SDK

Firstly, it is required to import essential functions from the SDK. To do so, add these lines at the top of src/main.js:

// Used to configure the SDK with the project details
import { configure } from "@monterosa-sdk/core";

// Functions to interact with the project's data
import { getProject, getEvent, getElements, answer, onElementUpdated, onElementResults } from "@monterosa-sdk/interact-kit";

To initialise the SDK, you will need to retrieve the Hostname, Project ID, and Event ID from Studio.

For demonstration purposes, these values are hardcoded. In general, you’ll obtain these values from either:

• Hardcoding them

• A URL query parameter

• Data obtained from your own APIs

Your settings may vary, please ensure that the settings below match the settings in your project.

const host = "<HOST>";
const projectId = "<PROJECT ID>";
const eventId = "<EVENT ID>";

Now let’s create a function that will initialise the app by fetching the data required and rendering it:

init();
async function init() {
  // Configure the SDK with the specified host and project ID
  configure({
    host,
    projectId,
  });
  // Retrieve the event details
  const event = await getEvent(eventId);
  // Fetch the elements for the event
  const elements = await getElements(event);
  // Identify the most recent published poll element
  const poll = elements.reverse().find(({ type }) => type === "poll");
  if (poll !== undefined) {
    renderPoll(poll);
    setupPoll(poll, event);
  } else {
    document.getElementById("app").innerHTML =
      "No poll was found in this event. Please consider adding a poll to the event.";
  }
}

function renderPoll(poll) {
  // To Do
}

function setupPoll(poll, event) {
  // To Do
}

The code above performs the following operations with the Monterosa / Interaction SDK:

• configure: This function specifies to Monterosa / Interaction SDK which project we want to connect to.

• getEvent: Returns the event metadata for the id we specified.

• getElements: Returns the elements published in the Event, sorted from older to newer.

If you open the developer tools while running your app, you’ll see that some network calls are starting to flow, however the UI is not updated. This is because we haven’t yet implemented renderPoll. The following snippet adds a simple UI to display the Poll:

function renderPoll(poll) {
  const { question, answerOptions } = poll;
  document.getElementById("app").innerHTML = `
    <div>
      <h2>${question.text}</h2>
      <div>
        ${answerOptions
          .map(
            (option) => `
              <div>
                <button>
                  ${option.text}
                </button>
              </div>
            `
          )
          .join("")}
        </div>
    </div>
  `;
}

Once everything is correctly set up, you should see the poll rendered on your app:

Submit User Answers

Now let’s implement setupPoll to react to the user selecting an answer to the poll:

Let's enhance the code by adding event handlers for when a user clicks or taps on an answer button. This involves implementing functionality within the setupPoll function that was previously defined.

function setupPoll(poll) {
  // Retrieve all button elements
  const buttons = document.querySelectorAll("button");
  buttons.forEach((button, idx) => {
    // Add an event listener for the "click" event
    button.addEventListener("click", () => {
      // When the user clicks on the button, invoke the `answer()` function and
      // pass the `poll` instance and `idx` as the index of the option the user 
      // is voting for
      answer(poll, idx);
    });
  });
}

The gist of the implementation is that we iterate all buttons, and add a click event listener to them. The listener will later call the answer method of the Monterosa / Interaction SDK, which will then forward the user’s answer to Monterosa / Interaction Cloud and record it in Studio.

To test that it works as expected, navigate to the app and click on any option. Even though the user interface does not indicate that the user has voted, you can confirm in Studio that the option you selected has recorded a vote by hovering over the Element you created and checking its stats.

Display Poll Results

The poll instance offers a results getter that retrieves an array of results if they are available. The availability of results is determined by the "Reveal Result Breakdown" setting, which can be configured as: on user vote, always, on close, manual, or don't reveal. Each of these options is customisable for every poll in the element specification. For the purposes of the current demonstration, we assume that the poll is set to on user vote for revealing the results.

To enhance the functionality of the renderPoll() function to showcase our results, we make a slight adjustment:

function renderPoll(poll) {
  // 1. Retrieve the results array from the poll instance
  const { question, answerOptions, results } = poll;
  document.getElementById("app").innerHTML = `
    <div>
      <h2>${question.text}</h2>
      <div>
        ${answerOptions
          .map(
            (option, idx) => `
              <div>
                <button>
                  ${option.text}
                  <!-- 2. Display results percentage if results are not null -->
                  ${results !== null && `${results[idx].percentage}%`}
                </button>
              </div>
            `
          )
          .join("")}
        </div>
    </div>
  `;
}

After submitting your answer, each answer option will now show the percentage of users who selected it.

While we have successfully rendered a basic poll and enabled users to submit their answers, the button's UI does not yet update dynamically without a page refresh. To introduce real-time dynamic behaviour, we will add listeners for data change and update the UI accordingly.

Handle real-time data updates

To enhance the app's interactivity, we will incorporate real-time updates to the data. This will involve utilising the onElementUpdated and onElementResults functions provided by Monterosa / Interaction SDK.

These functions serve the purpose of alerting us whenever the element undergoes an update and when its results are altered.

To implement this feature, it is necessary to modify the setupPoll() function to invoke these functions and refresh the poll. Additionally, a new function should be created to dismantle all existing subscriptions upon each refresh.

/**
 * Tears down event listeners and subscriptions for the poll element
 */
function teardownPoll() {
  unsubs.forEach((unsub) => unsub());
}

function setupPoll(poll, event) {
  const buttons = document.querySelectorAll("button");
  buttons.forEach((button, idx) => {
    const handler = () => {
      answer(poll, idx);
    };
    button.addEventListener("click", handler);
    // Store the unsubscribe functions in a list (unsubs) for cleanup later
    unsubs.push(() => {
      button.removeEventListener("click", handler);
    });
  });
  const handleChanges = () => {
    // remove all existing subscriptions
    teardownPoll();
    // re-render the poll
    renderPoll(poll);
    // set up the poll again
    setupPoll(poll, event);
  };
  // Subscribe to element updated events
  const updateUnsub = onElementUpdated(event, handleChanges);
  // Subscribe to element results events
  const resultsUnsub = onElementResults(poll, handleChanges);
  // Store the unsubscribe functions in a list (unsubs) for cleanup later
  unsubs.push(updateUnsub);
  unsubs.push(resultsUnsub);
}

Now open two tabs side by side, vote on one, and check how the other one updates.

🪄 Real-time magic!