@wehelp/widget

WeHelp widget package for embedding survey widgets into web pages.

Installation

npm install @wehelp/widget
# or
pnpm add @wehelp/widget
# or
yarn add @wehelp/widget

Simple usage

This is the minimum required to display the survey:

import loadWeHelpWidget from '@wehelp/widget';

loadWeHelpWidget({
  surveyToken: '[YOUR_SURVEY_TOKEN_HERE]', // token obtained at https://app.wehelpsoftware.com/
  person: {
    name: 'John Doe',
    companyUnit: '[UNIT_CODE]', // Person's unit of origin
    createdAt: '2005-03-14', // Person's creation date in your system (used for 'customer since')
    type: 'CUSTOMER', // 'CUSTOMER' | 'COLLABORATOR'

    // at least one of these three is required, which one depends on your company configuration at WeHelp
    email: '[email protected]',
    phone: '1234567890',
    internalCode: 'some-unique-internal-code',
  }
});

However, we strongly recommend sending all personal data needed for follow-up in the survey response.

Advanced usage

The widget can be usage in three different ways:

Option 1: ESM Import (recommended)

Import the widget as an ES module in your JavaScript/TypeScript code:

import loadWeHelpWidget from '@wehelp/widget';

loadWeHelpWidget({
  // required options
  surveyToken: '[YOUR_SURVEY_TOKEN_HERE]',
  person: {
    companyUnit: '[UNIT_CODE]',
    createdAt: '2005-03-14',
    name: 'John Doe',
    type: 'CUSTOMER',
    email: '[email protected]',
    phone: '1234567890',
    internalCode: 'some-unique-internal-code',
  },
});

Option 2: IIFE Script Tag

Load the widget using a script tag that exposes a global function window.WeHelp.loadWidget(options).

<script type="text/javascript" src="https://cdn.wehelpsoftware.com/survey-site/load.js"></script>

<script>
  window.onload = () => {
    window.WeHelp.loadWidget({
      surveyToken: '[YOUR_SURVEY_TOKEN_HERE]',
      person: {
        // required options
        name: 'John Doe',
        type: 'CUSTOMER',
        companyUnit: '[COMPANY_UNIT_CODE]',
        createdAt: '2020-01-01',

        // at least one of these must be informed
        email: '[email protected]',
        phone: '1234567890',
        internalCode: 'some-unique-internal-code',

        // optional data
        state: 'RJ',
        country: 'BRA',
        gender: 'M',
        document: '',
      },
      customFields: [
        {
          name: 'Custom Field Name',
          value: 'Custom Field Value'
        }
      ]
    });
  };
</script>

Option 3: Google Tag Manager

Create a custom HTML tag like the following:

<script>
(function() {
  var el = document.createElement('script');
  el.src = 'https://cdn.wehelpsoftware.com/survey-site/load.js';
  el.async = true;

  el.onload = function() {
    window.WeHelp.loadWidget({
      surveyToken: '[YOUR_SURVEY_TOKEN_HERE]',
      type: 'box',
      person: {
        name: {{userName}},
        type: 'CUSTOMER',
        createdAt: {{userCreatedAt}},
        companyUnit: {{userCompanyUnitCode}},
        internalCode: {{userInternalCode}},
        email: {{userEmail}},
        phone: {{userPhone}},
      }
    });
  };

  document.head.appendChild(el);
})();
</script>

The placeholders {{...}} are automatically replaced by the corresponding dataLayer variables. Make sure the variable names match your dataLayer. Apply which triggers you see fit to the tag.

Options reference

| Field | Required | Type | Default | Description | |------------------------|--------------|----------------------------------------------------------------|------------------------------------|--------------------------------------------------------------------------------------------------------| | surveyToken | Yes | string | — | Survey token provided at the survey widget settings. | | companyUnit | — | string | Same as person.companyUnit | Unit code that will be registered in the survey. | | language | — | 'PORTUGUESE' \| 'PORTUGUESE_PT' \| 'ENGLISH' \| 'SPANISH' | negotiated from browser's language | The language to display the survey. | | logLevel | — | 'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'never' | 'warn' | Log level for console printing. | | experienceId | — | string \| number | — | Unique identifier of the action, usually used to store order number, service code, etc. | | type | — | 'modal' \| 'bar' \| 'box' | 'modal' | Widget layout type. | | forceOpen | — | boolean | false | Force message opening if survey has already been answered. | | customFields | — | Array<{ name: string; value: string \| number }> | — | Alias for person.customFields | | person.companyUnit | Yes | string | — | Person's origin unit code. | | person.name | Yes | string | — | Person's name. | | person.createdAt | Yes | string \| number \| Date | — | Person's creation date in your system. | | person.type | Yes | 'CUSTOMER' \| 'COLLABORATOR' | — | Person type. | | person.internalCode | Conditional¹ | string | — | Person's internal code. | | person.email | Conditional¹ | string | — | Person's email. | | person.phone | Conditional¹ | string | — | Person's phone. | | person.birthDate | — | string \| number \| Date | — | Person's date of birth. | | person.state | — | string | — | Person's state. (2 digits) | | person.country | — | string | — | Person's country. (3 digits) | | person.gender | — | 'M' \| 'F' | Inferred from person's name | Person's gender. | | person.document | — | string | — | Person's document. | | person.customFields | — | Array<{ name: string; value: string \| number }> | — | Custom fields to be sent along with the response. Values will be coerced to string | | elements.rootElement | — | HTMLElement \| string | document.body | Root element where the iframe will be mounted. Accepts an HTMLElement or the element id as a string. | | elements.iframeId | — | string | 'wehelp-widget-iframe' | ID of the iframe element created by the widget. | | elements.overlayId | — | string | 'wehelp-widget-overlay' | ID of the overlay element created by the widget. |

¹ Required depending on your company's auto-person-code configuration at WeHelp.

Snake_case aliases (survey_token, company_unit, etc.) are still accepted but deprecated.

Support

For bug reports and feature requests, please contact [email protected]