WebComponent – Technical Documentation

Main Configuration

Base parameters passed to the config object:

• id: Identifier of the HTML (DOM) element where the survey will be rendered. This is a required parameter to place the survey in the correct spot on the page.
• rootElement: The rootElement attribute allows you to specify the DOM element where the survey should be rendered. It can be a function returning a DOM element, a direct DOM element, or a CSS selector. If not provided, standard document.getElementById(id) behavior is used.
• surveyId: Identifier of the survey created on the Customerhero.com platform. This identifier is obtained after copying the base survey with the SEQ prefix and is necessary for calling the API.
• marketingConsent: A boolean value (true or false) determining whether the user has given marketing consent.
• externalKey: An optional field that can contain an additional variable describing the respondent's context, such as a channel identifier.
• userToken: An optional token used for user identification.
• accessToken: An optional API token, which in the older version of the configuration was fetched from window.omni.accessToken.
• prefillUrl: An optional URL used for prefilling the survey. It is utilized in the case of surveys for non-logged-in users.
• validationText: Global validation error text for questions that do not have their own validationText defined.
• submitButtonText: Text on the main button that submits the survey.
• submitButtonLoadingText: Text displayed on the submit button after it is clicked, during processing.

Events

• onFirstClick: Function triggered on the user's first click on any survey element.
• onSubmit: Function triggered after clicking the "Submit" button and successful form validation.
• onRender: Function triggered after the survey component is fully rendered in the DOM structure.
• onClose: Function triggered after closing the survey (by clicking the "Close" button on the thank you page) and the closing animation is finished.
• onError: Function triggered when an error occurs in the webcomponent (configuration error, connection error).

"cookie" Object

This object manages the settings of the cookie file used by the survey.

• name: The name of the cookie where the survey data is stored.
• age: Determines the lifespan of the cookie in days.

"capping" Object

Used to manage survey display limits.

• value: The maximum number of survey impressions per user (based on the cookie). A value of undefined means no limit.
• pageViewsTrigger: Determines every how many page views the survey should be displayed. A value of undefined means no such restriction.
• hideFilled: A boolean value (true or false). If set to true, the survey will not be shown to a user who has already completed it.
• showChance: Determines the probability (from 0.0 to 1.0) of the survey appearing. A value of undefined means the survey will always be shown.

"attributes" Object

Allows passing additional attributes describing the respondent. It replaces the previous labels section. Maximum: 15 fields.

• a1, a2, age, lang, ...: Example attributes that can be passed, such as first name, last name, age, or language.

"questions" Array

This is an array of objects, where each object defines one question in the survey. The survey can contain different types of questions.

Common Question Parameters

These are common parameters that can be defined in every question:

• type: Question type. Available options are rate, nps, text, singleChoice.
• title: Main title or content of the question.
• description: Additional description or instruction for the question.
• required: Optional boolean value. Defaults to true for closed questions (e.g., nps) and false for open questions (e.g., text).
• style: Optional object defining alignment. Available values for align are 'left', 'center', 'right'. The default is 'center' for NPS questions and 'left' for the rest.

"rate" Type Question (Rating)

• answers: An array of strings that represent labels for consecutive ratings. Example: ['yes', 'no']

"nps" Type Question (Net Promoter Score)

• minLabel: Label for the minimum scale value.
• maxLabel: Label for the maximum scale value.
• minValue: Minimum value on the scale (e.g., 0).
• maxValue: Maximum value on the scale (e.g., 10).

"text" Type Question (Open-ended)

• placeholder: Text containing additional hints, displayed below the text field.
• maxlength: The maximum allowed number of characters in the response.
• validationLimitExceededText: Default: 'Character limit exceeded'. Text displayed when the user exceeds the maximum number of characters and tries to submit the form.
• validationText: Validation error text displayed when an answer is required but has not been provided. If not defined, the global config.validationText value is used.
• waitForPreviousQuestion: Optional boolean value. Defaults to false. If true, the question will appear only after the previous question has been answered.
• counter: Optional boolean value (true/false) that toggles the visibility of the character counter for the text field. It is set to falseby default.
  • false (default value): The character counter is hidden. The text field blocks the ability to type more characters than specified in maxlength. When attempting to paste longer text, excess characters are automatically removed, and the user is informed of this via an alert.
  • true: Displays the character counter. The user can type more text than the maxlength limit, but the field is validated. When attempting to paste longer text, excess characters are automatically removed, and the user is informed of this via an alert.

"singleChoice" Type Question (Single Choice)

• answers: An array of objects, where each object has:
  • label: Answer label visible to the user.
  • value: Answer value sent in the data.
• direction: Optional parameter specifying the layout of the answers: 'vertical' (vertically) or 'horizontal' (horizontally). Defaults to 'horizontal'.

"thankYouPage" Object (Thank You Page)

Configures the thank you page that appears after submitting the survey.

• title: Title on the thank you page.
• description: Text below the title on the thank you page.
• closeButtonText: Text on the button that closes the survey. If this attribute is not provided, the button will not be displayed.
• image: Optional object for managing the image on the thank you page. If missing, a heart is shown.
  • hidden: Boolean value (true or false) determining whether to hide the default image.
  • code: SVG code to be displayed as the image.

"wcag" Object

An object used to configure texts related to accessibility (Web Content Accessibility Guidelines).

• text: Contains objects with texts for screen readers:
  • thankYouPageAlert: Text read by the screen reader after the response is submitted.
  • thankYouPageButton: Label for the button closing the survey, read by the screen reader.

CustomerHero Object Methods Documentation

Below is a description of the methods available in the global window.CustomerHero object.

CustomerHero.init(config)

Initializes and renders the survey on the page based on the passed configuration object.

Operation:

1. Creates an internal store with the survey configuration.
2. Checks if the survey cookie exists. If not, it creates it. If it exists, it increments the page views counter.
3. Destroys the previous instance of the survey, if one existed, to prevent duplicates.
4. Calls the checkRenderConditions() method to verify if the survey can be displayed.
5. If conditions are met, it renders the survey in the DOM element specified by config.id.

Returns:

• true, if the survey was successfully initialized and rendered.
• false, if the conditions for displaying the survey were not met.

CustomerHero.show()

Displays a survey that was previously initialized and is hidden.

Operation:

1. Checks if the survey can be displayed using the internal Renderer.showSurvey()function.
   • Verifies whether accessToken or prefillUrl was provided in the configuration. Without one of them, the survey cannot function.
2. If so, it increments the survey view counter (increaseSurveyViews), which is essential for the capping mechanism.

CustomerHero.hide()

Hides the survey without destroying its component. The survey remains in the DOM structure and can be displayed again using the show() method.

Operation:

1. Calls the internal function Renderer.hideSurvey(), which visually hides the survey component.

CustomerHero.destroy()

Completely removes the survey from the page.

Operation:

1. Calls the internal function Renderer.destroySurvey(), which removes the survey component from the DOM structure and clears its associated events. To display the survey again, it must be re-initialized using the init() method.

CustomerHero.setAuthorization(accessToken)

Sets the authorization token (accessToken) for the services used by the survey.

Parameters:

• accessToken (string): The API token used to authorize requests.

Operation:

1. Passes the token to the services module, where it is stored and used during communication with the API.

CustomerHero.setPrefillUrl(prefillUrl)

Sets the prefill URL address (prefillUrl).

Parameters:

• prefillUrl (string): The URL address used to authorize requests.

Operation:

1. Passes the URL address to the services module, where it is stored and used during communication with the API.

CustomerHero.checkRenderConditions()

An internal method that checks if all the necessary conditions for displaying the survey are met.

Operation: Checks sequentially:

1. Marketing consent: Checks if marketingConsent is set to true.
2. Number of views: Verifies if the pageViewsTrigger condition from the capping object has been met.
3. Capping: Checks if the maximum limit of survey impressions has not been exceeded (value in the capping object).
4. Completion status: Checks if the survey has not already been filled out by the user (if hideFilled is set to true).

Returns:

• true, if all conditions are met.
• false, if any of the conditions is not met. An appropriate warning (console.warn) will appear in the developer console.

Creating a component (Example)

Only one survey can be initialized on a page at a time. If another one is initialized, the previous one is removed. The survey component is created using the init() function.

const config = {
    id: 'customerhero-js', // ID of the DOM element where the survey will be rendered
    surveyId: '548662', // ID of the survey created in the client's account
    marketingConsent: true, // Marketing consent
    externalKey: 'ChannelID', // Optional
    userToken: 'UserID', // Optional
    prefillUrl: 'https://example.com/prefill', // (optional) URL for the survey prefill.
    cookie: {
        name: 'snt-survey', // Name of the cookie containing survey data
        age: 90, // Lifespan of the cookie in days
    },
    capping: {
        // Maximum number of survey views per cookie
        // Range from 0 to infinity or undefined - no limit
        value: undefined,
        // Survey display: Once per X views
        // Range from 0 to infinity or undefined - no limit
        pageViewsTrigger: undefined,
        // When <true> - the survey will not show if the user has already completed it
        hideFilled: false,
        // Chance of showing the survey.
        // Range from 0.0 to 1.0 or undefined - always shows the survey
        showChance: undefined,
    },
    attributes: {
        a1: 'firstname',
        a2: 'lastname',
        wiek: 35,
        lang: 'en', // Language attribute
    },
    questions: [
        {
            type: 'rate',
            title: 'How do you rate the [process name] process?',
            description: 'Your voice is important to us',
            answers: [
                'Very dissatisfied',
                'Dissatisfied',
                'Neutral',
                'Satisfied',
                'Very satisfied',
            ]
        },
        {
            type: 'text',
            title: 'Why?',
            placeholder: 'Do not include personal data in your comment',
        },
        {
            type: 'singleChoice',
            title: 'How do you rate the account opening process?',
            answers: [
                { label: 'very difficult', value: 'o1' },
                { label: 'difficult', value: 'o2' },
                { label: 'average', value: 'o3' },
                { label: 'easy', value: 'o4' },
                { label: 'very easy', value: 'o5' }
            ]
        }
    ],
    thankYouPage: {
        title: 'Thank you!',
        description: 'Your feedback helps us grow',
        closeButtonText: 'Close',
    },
    validationText: 'Select a rating',
    submitButtonText: 'Submit feedback',
    submitButtonLoadingText: 'Please wait...',
    onFirstClick: function (item) {
        console.log('onFirstClick:', item);
    },
    onSubmit: function (item) {
        console.log('onSubmit:', item);
    },
    onRender: function () {
        console.log('onRender');
    },
    wcag: {
        text: {
            thankYouPageAlert: 'Your response has been submitted',
            thankYouPageButton: 'Close the survey',
        }
    }
};

CustomerHero.init(config);

if (CustomerHero.checkRenderConditions()) {
    CustomerHero.setAuthorization('v2-YnEJ10ii-PRslF0iz-JUNf7ii0-GP5sMan');
    CustomerHero.show();
}

// Showing
CustomerHero.show();

// Hiding
CustomerHero.hide();

// Destroying
CustomerHero.destroy();

How it works

For a logged-in user

After initializing the component, we build an HTML element with an assigned id attribute, which serves as the survey container, e.g., <div id=”feedbackSurveyPanel”></div>. The attribute value must be passed in the id parameter of the CustomerHero.init() function call. The client fills out the survey. Upon clicking the Submit button, an HTTP request is sent with the parameters below. Request details can be viewed in the browser's developer tools under the Network -> XHR tab.

• Method = POST
• URL = /**********/api/v1/feedback/survey
• POST param:
  Survey-URL: [ID_SURVEY]/index.html?q1=[ANS_1]&q2=[ANS_2]&external_key=[EXTERNAL_KEY]

Service /**********/api/v1/feedback/survey:

1. Retrieves the Survey-URL parameter.
2. Creates an absolute URL address to CustomerHero.
3. Appends the user_token parameter with a randomly generated client identifier to the URL.
4. Sends the request to the CustomerHero server.
5. Passes the user_token value and the client's CIF to the server.

Regardless of the HTTP response status, a thank you message is presented for completing the survey.

Example URL of a survey completed after performing a transaction at the Currency Exchange:
https://ankieta.bank.pl/ankieta/491634/badanie-satysfakcji.html?user_token=xxxxxxxxxx&l1=internet&l2=I&l3=SPOT

• 491634 is the survey identifier described in the configuration point.
• user_token signifies the unique identifier of the respondent.
• l1 signifies the transaction channel.
• l2 signifies the client type (I=individual client).
• l3 signifies the transaction type.

Sending a request in prefill mode (non-logged-in user)

In prefill mode, the process of sending survey data differs from the mode for a logged-in user. The request is sent directly from the client's browser to the survey server, bypassing the internal /**********/api/v1/feedback/survey service. All logic for building the URL and appending parameters occurs on the client side (in the browser).

Below is a description of the steps that take place after clicking the "Submit" button:

1. Retrieving the base URL address: The script retrieves the prefillUrl address from the configuration object passed during initialization.
2. Dynamic URL address construction: Subsequent query parameters are appended to the base URL:
   • Question answers: Each survey answer (payload) is added as a parameter, e.g., q1=[ANS_1], q2=[ANS_2].
   • External key: If externalKey is defined in the configuration, it is appended as the external_key=[EXTERNAL_KEY] parameter.
   • User token: If userToken is defined in the configuration, it is appended as the user_token=[USER_TOKEN] parameter.
   • Attributes: All values from the attributes object in the configuration are added as sequential parameters l1, l2, l3, etc.

Sending the HTTP request:

• Method: GET
• URL: A fully constructed URL containing all the parameters mentioned above.

Response handling:
The script listens for a response from the server to complete the process (Promise resolve or reject operation depending on the response status). Upon receiving the response, a thank you message is presented.

Example of the final URL in prefill mode:
https://ankieta.bank.pl/prefill/123456/ankieta-satysfakcji.html?q1=5&q2=Very helpful&external_key=ChannelID&user_token=UserID-123&l1=internet&l2=individual&l3=account

Key differences compared to the logged-in mode

Additional information

• Documentation on how to generate a prefill
• Passing answers to questions in the survey link
• Examples of implementing different variants:
  • Survey - Poland
  • Prefill: NPS Survey or Rating - Prefill - Poland
    
    

Content-Security-Policy: connect-src 'self' Portal finansowy | Miesięcznik Finansowy BANK ;