Skip to content

Feedback Widget Implementation Guide

Overview

This guide outlines the steps for integrating the nps.today Feedback Widget into your application, enabling direct feedback collection from users.

Prerequisites

Before you begin the implementation of the feedback widget, ensure you have the following:

  • API Token

    • Obtain this from the /employees/token endpoint. Refer to our API Documentation for detailed information.

  • Respondent Identifier

    • You must have either respondentEmail or respondentPhone.
    • These identifiers are used for displaying responses associated with a specific respondent.

/employees/token Endpoint Explained

The /employees/token endpoint plays a key role in the setup and security of the feedback widget:

  • Token Generation: It generates the API token required for widget access.
  • Security and Access Control: The token restricts access to only the necessary functionalities within the widget, enhancing overall security.
  • Limited Lifespan: With a 24-hour validity period, the token minimizes the risk of prolonged unauthorized access.
  • Personalization: Generated using an API key and an employeeEmail, the token enables personalization and sets the stage for future features.

In addition to token generation, the endpoint offers an "echo" JSON object feature, which has varying utility depending on the integration:

  • Echo JSON Object: This object replicates any values included in the request payload, echoing them back in the response. While not essential for all integrations, it can be beneficial for passing parameters to the widget in scenarios where direct parameter passing is limited by integration constraints.
  • Facilitating Parameter Passing: The "echo" object can be useful for ensuring that necessary parameters are included in the response payload, aiding in the widget's functionality.
  • Adaptability to Integration Requirements: The relevance of the "echo" object varies with each integration. For some setups, it provides a valuable means to pass parameters, while for others, its utility may be limited. This adaptability allows for customization based on specific integration needs.

Widget Implementation Guide

Key Steps for Implementation:

  1. Embedding the Widget: Place the feedback widget on your webpage using an <iframe> element.

  2. Listening for Widget Readiness: Your script should listen for a FEEDBACK_WIDGET_READY event. This signals that the widget is prepared to accept parameters.

  3. Configuring Initial Parameters: After the widget signals readiness, set the initial parameters like token, respondentEmail, and respondentPhone. These are crucial for the widget to function properly.

  4. Dynamically Updating Parameters: To change the widget's parameters post-loading, send a feedback-widget-nps-today-update-parameters event along with the new parameters.

Example Code for Embedding the Widget

Below is an HTML and JavaScript structure example for embedding the widget into your webpage:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>feedback-widget-nps-today</title>
    </head>
    <script>
        const feedbackWidgetSrc = "https://feedback.widget.nps.today?operationMode=admin";
        /*
         * Set initial parameters -
         */
        const token = "yourToken";
        const respondentEmail = "respondent@example.com";
        const respondentPhone = "+4512345678";

        /*
         * If you want to change the parameters after the widget is loaded,
         * you can do so by dispatching a custom event - see below
         */
        /*
        document.body.dispatchEvent(
            new CustomEvent("feedback-widget-nps-today-update-parameters", {
                detail: {
                    respondentEmail: newRespondentEmail,
                    respondentPhone: newRespondentPhone,
                },
            })
        );
        */
    </script>
    <body>
        <iframe
            title="feedback-widget-nps-today"
            id="feedback-widget-nps-today"
            width="100%"
            height="600px"
            frameborder="0"
        >
        </iframe>
        <script>
            const iframeElement = document.getElementById("feedback-widget-nps-today");
            const setFeedbackWidgetParameters = (parameters) => {
                iframeElement.contentWindow.postMessage(
                    {
                        response: "SET_PARAMETERS",
                        ...parameters,
                    },
                    "*" // use feedbackWidgetSrc attribute, if inviornment allows
                );
            };
            window.addEventListener("message", (event) => {
                if (event.data && event.data.response === "FEEDBACK_WIDGET_READY") {
                    setFeedbackWidgetParameters({
                        token: token,
                        respondentEmail: respondentEmail,
                        respondentPhone: respondentPhone,
                    });
                }
            });
            // Listen for custom events to provide the feedback widget with new data
            document.body.addEventListener("feedback-widget-nps-today-update-parameters", (event) => {
                setFeedbackWidgetParameters({
                    ...event.detail,
                });
            });
            iframeElement.src = feedbackWidgetSrc;
        </script>
    </body>
</html>