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.

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,
                    });
                }
            });
            // 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