Feedback App Implementation Guide

Overview

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

Prerequisites

Before you begin the implementation of the Feedback App, 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 App:

Token Generation: It generates the API token required for Feedback App access.
Security and Access Control: The token restricts access to only the necessary functionalities within the Feedback App, 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 Feedback App 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 Feedback App'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.

Feedback App Implementation Guide

Key Steps for Implementation:

Embedding the Feedback App: Place the Feedback App on your webpage using an <iframe> element.
Listening for Feedback App Readiness: Your script should listen for a FEEDBACK_WIDGET_READY event. This signals that the Feedback App is prepared to accept parameters.
Configuring Initial Parameters: After the Feedback App signals readiness, set the initial parameters like token, respondentEmail, and respondentPhone. These are crucial for the Feedback App to function properly.
Dynamically Updating Parameters: To change the Feedback App's parameters post-loading, send a feedback-app-nps-today-update-parameters event along with the new parameters.
Sizing the iframe to its content (optional): Listen for the FEEDBACK_WIDGET_RESIZE event and set the height of the iframe from it, so the Feedback App is shown without its own scrollbar. See Sizing the iframe to its content.

Example Code for Embedding the Feedback App

Below is an HTML and JavaScript structure example for embedding the Feedback App into your webpage, that initiates the Feedback App 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-app-nps-today</title>
    </head>
    <script>
        const feedbackAppSrc = "https://feedback.nps.today?operationMode=integration";
        /*
         * Set initial parameters -
         */
        const token = "yourToken";
        const respondentEmail = "[email protected]";
        const respondentPhone = "+4512345678";

        /*
         * If you want to change the parameters after the Feedback App is loaded,
         * you can do so by dispatching a custom event - see below
         */
        /*
        document.body.dispatchEvent(
            new CustomEvent("feedback-app-nps-today-update-parameters", {
                parameters: {
                    respondentEmail: newRespondentEmail,
                    respondentPhone: newRespondentPhone,
                },
            })
        );
        */
    </script>
    <body>
        <iframe title="feedback-app-nps-today" id="feedback-app-nps-today" width="100%" height="600px" frameborder="0">
        </iframe>
        <script>
            const iframeElement = document.getElementById("feedback-app-nps-today");
            const setFeedbackAppParameters = (parameters) => {
                iframeElement.contentWindow.postMessage(
                    {
                        action: "SET_PARAMETERS",
                        parameters: { ...parameters },
                    },
                    "*" // use feedbackAppSrc attribute, if inviornment allows
                );
            };
            window.addEventListener("message", (event) => {
                if (event.data && event.data.action === "FEEDBACK_WIDGET_READY") {
                    setFeedbackAppParameters({
                        token: token,
                        respondentEmail: respondentEmail,
                        respondentPhone: respondentPhone,
                    });
                }
                // Optional - size the iframe to the content, instead of scrolling inside it
                if (event.data && event.data.action === "FEEDBACK_WIDGET_RESIZE") {
                    iframeElement.style.height = event.data.parameters.height + "px";
                }
            });
            // Listen for custom events to provide the Feedback App with new data
            document.body.addEventListener("feedback-app-nps-today-update-parameters", (event) => {
                setFeedbackAppParameters({
                    ...event.parameters,
                });
            });
            iframeElement.src = feedbackAppSrc;
        </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 App 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
Outgoing	`FEEDBACK_WIDGET_RESIZE`	Sends the height the Feedback App needs to show its content without its own scrollbar. Sent after loading, and whenever the height changes.	`{ height: number; }` (Object) - the height in pixels

Sizing the iframe to its content

By default, the Feedback App fills the iframe and shows its own scrollbar when the content is taller than the iframe. To size the iframe to the content instead, listen for the FEEDBACK_WIDGET_RESIZE action and set the height of the iframe from its height parameter:

{
    "action": "FEEDBACK_WIDGET_RESIZE",
    "parameters": {
        "height": 850
    }
}

The Feedback App sends the action when it runs in an iframe: after it has loaded, and again whenever the height of its content changes, both up and down. For example on a tab change, when feedback loads, and when the history is expanded or collapsed.
height is the height in pixels the Feedback App needs, including its bottom navigation. A border or padding on the iframe element itself is not included.
Handling the action is optional. If the parent ignores it, the Feedback App keeps filling the iframe and scrolls inside it.
While a page loads, the content can briefly be very short. Set a min-height on the iframe if the parent should not shrink below a certain height.

window.addEventListener("message", (event) => {
    if (event.data && event.data.action === "FEEDBACK_WIDGET_RESIZE") {
        iframeElement.style.height = event.data.parameters.height + "px";
    }
});