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.

/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, that initiates the widget with parameters, such as an employeeToken and a respondentEmail:

<!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", {
                parameters: {
                    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(
                    {
                        action: "SET_PARAMETERS",
                        parameters: { ...parameters },
                    },
                    "*" // use feedbackWidgetSrc attribute, if inviornment allows
                );
            };
            window.addEventListener("message", (event) => {
                if (event.data && event.data.action === "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.parameters,
                });
            });
            iframeElement.src = feedbackWidgetSrc;
        </script>
    </body>
</html>

Actions

This section describes the actions that can be sent to (Incoming Actions) and received from (Outgoing Actions) the iframe application using the postMessage method, facilitating interactive communication between the host platform and the embedded application.

Definitions

  • Incoming Actions: Actions initiated by external platforms to send specific commands and data to the iframe application.
  • Outgoing Actions: Actions sent from the iframe application to notify the external platform of events or data changes within the iframe.

Communication Protocol

The data object of both Incoming and Outgoing postMessage events is structured like below:

{
    "action": /* Action name - see table below */,
    "parameters": { /* parameters as needed */ }
}

Actions Table

Action Type Action Description Parameters (Type)
Incoming SET_PARAMETERS Allows external platforms to set various operational parameters within the iframe application. - respondentEmail (string)
- respondentPhone (string)
- analyticsFetchDays (number)
- token (string)
- currentOrganizationId (string)
- persistedData (array of PersistDataParams - see PERSIST_DATA action below)
- enableLogout (boolean)
Outgoing FEEDBACK_WIDGET_READY Indicates that the feedback widget within the iframe is ready to interact with the user. None
Outgoing PERSIST_DATA Triggered when the iframe application persists data, informing the parent platform, which may opt to handle data persistence on its own. { key: string; data: any; } (Object)
Outgoing LOGOUT Signals that a logout process has been initiated within the iframe. None
Outgoing INVALID_TOKEN Alerts to an invalid authentication token, prompting necessary action to re-authenticate or refresh the token. None