SoluCX Widget

The SoluCX widget allows the integration of surveys directly into your website, providing an easy and efficient way to collect customer feedback.

Compatibility with Form Flex and Survey Research

The widget is compatible with Form Flex and Survey research types, allowing flexibility in data collection according to your business needs.

Installation

To use the widget, add the following script to your website:

<script src="https://widget.solucx.com.br/widget.js"></script>

This script exposes the global function createSoluCXWidget, which is used to initialize the widget.

Usage via Script Tag

For direct insertion via <script> in HTML:

  1. Add the script above in the <head> tag or before the closing <body> tag in your HTML.
  2. Create the widget inside a <script> tag.

Note: When added in the <head> tag, it is necessary to check if the DOM has loaded or add the function in some trigger method (e.g., button click).

Example:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>SoluCX Widget Example</title>
        <script src="https://widget.solucx.com.br/widget.js"></script>
    </head>
    <body>
        <script>
            const apiKey = "YOUR_API_KEY";
            const type = "inline";
            const data = {
                name: "Customer Name",
                transaction_id: "Transaction ID",
                email: "[email protected]",
                document: "123.456.789-00",
            };

            createSoluCXWidget(apiKey, type, data);
        </script>
    </body>
</html>

Usage via Google Tag Manager

To use the SoluCX Widget within Google Tag Manager (GTM):

  1. Access your GTM account and select the desired container.
  2. Click on Tags in the side menu and then on New.
  3. Give the tag a name and click on Tag Configuration.
  4. Select Custom HTML.
  5. In the Custom HTML field, insert the following code (adjusting as needed):
    <script src="https://widget.solucx.com.br/widget.js"></script>
<script>
  (function () {
    var apiKey = "YOUR_API_KEY";
    var type = "modal"; // inline, bottomBar, bottomBox, bottomBoxLeft or modal
    var data = {
      name: "Customer Name",
      transaction_id: "Transaction ID",
      email: "[email protected]",
      document: "123.456.789-00",
    };
    var options = {
      width: 600,
      height: 400,
      retry: {
        attempts: 3,
        interval: 2,
      },
      waitDelayAfterRating: 30,
    };

    createSoluCXWidget(apiKey, type, data, options)
      .then(function (response) {
        console.log("Widget created successfully:", response);
      })
      .catch(function (error) {
        console.error("Error creating widget:", error);
      });
  })();
</script>
  6. In Triggering, select when you want the tag to be triggered (e.g., on all pages).
  7. Save the tag and publish the changes in the container.

Note: The <script src="https://widget.solucx.com.br/widget.js"></script> tag can be placed together with the custom code above in the same Custom HTML Tag, or in a separate tag that fires before it (e.g., on site initialization). The important thing is that the script is loaded before calling the createSoluCXWidget function.

Advanced Example: Floating "Rate Us" Button

In this example, the widget script is loaded in a separate tag on site initialization. A second tag creates a floating button on the side of the page that, when clicked, opens the widget. The button is only displayed after verifying that the createSoluCXWidget function is available.

Tag 1 — Script Loading (triggered on all pages):

<script src="https://widget.solucx.com.br/widget.js"></script>

Tag 2 — Floating Button + Widget (triggered on all pages, after Tag 1):

<script>
  (function () {
    if (typeof createSoluCXWidget !== "function") {
      console.warn("SoluCX Widget is not available.");
      return;
    }

    var button = document.createElement("button");
    button.innerText = "Rate Us";
    button.style.cssText =
      "position:fixed;right:0;top:50%;transform:translateY(-50%);" +
      "writing-mode:vertical-rl;text-orientation:mixed;" +
      "background-color:#4CAF50;color:#fff;border:none;padding:12px 8px;" +
      "cursor:pointer;font-size:14px;font-weight:bold;border-radius:8px 0 0 8px;" +
      "z-index:9999;box-shadow:0 2px 8px rgba(0,0,0,0.2);";

    button.addEventListener("click", function () {
      var apiKey = "YOUR_API_KEY";
      var type = "modal";
      var data = {
        name: "Customer Name",
        transaction_id: "Transaction ID",
        email: "[email protected]",
      };

      createSoluCXWidget(apiKey, type, data)
        .then(function (response) {
          console.log("Widget opened successfully:", response);
        })
        .catch(function (error) {
          console.error("Error opening widget:", error);
        });
    });

    document.body.appendChild(button);
  })();
</script>

Widget Types

The available widget types are:

  • bottomBar: Displays the widget as a fixed bar at the bottom of the page.
    In bottomBar mode, the widget is displayed as a fixed horizontal bar at the bottom of the page.
    This means it remains visible as the user scrolls the page, ensuring the widget is always accessible.
  • bottomBox: Displays the widget as a fixed box in the bottom right corner of the page.
    In bottomBox mode, the widget is displayed as a fixed box in the bottom right corner of the page.
    This allows the widget to stand out without interfering with the main content, ideal for capturing user attention.
  • bottomBoxLeft: Displays the widget as a fixed box in the bottom left corner of the page.
    In bottomBoxLeft mode, the widget is displayed as a fixed box in the bottom left corner of the page.
    Like bottomBox, it highlights the widget without interfering with the main content, but positioned on the left side.
  • inline: Displays the widget embedded in the page content.
    In inline mode, the widget is displayed directly within the existing layout.
    This means it integrates seamlessly with the page content, without overlapping or covering other elements. Ideal when you want the widget to be part of the natural content flow.
  • modal: Displays the widget as a centered modal on the page.
    In modal mode, the widget is displayed as a centered modal window on the page.
    This means it overlays the page content, capturing all of the user's attention. Ideal when you want to ensure the user interacts with the widget before continuing to browse.

Initialization Parameters

The createSoluCXWidget function accepts the following parameters:

Parameter apiKey (string) Required

API key provided by SoluCX.

Example:

const apiKey = "YOUR_API_KEY";

Parameter type (string) Required

Type of widget to be created. Accepted values:

  • inline
  • bottomBar
  • bottomBox (positioned to the right by default)
  • bottomBoxLeft
  • modal

Example:

const type = "bottomBox";

Parameter data

Customer data to be sent to the Widget.
transaction_idstring
Transaction ID. This is the external ID provided by the customer.
form_idstring
Form ID. Required only if targeting Flex Forms
customer_idstring
Customer ID. Required if not providing transaction_id OR name AND (email OR phone)
namestring
Customer name. Required if not providing transaction_id OR customer_id
emailstring
Customer email. Required if not providing transaction_id OR customer_id AND phone
phonestring
Customer phone. Required if not providing transaction_id OR customer_id AND email
phone2string
Customer secondary phone.
documentstring
Customer document.
birth_datestring
Customer birth date.
store_idstring
Store ID. Required if not providing transaction_id
store_namestring
Store name.
employee_idstring
Employee ID. Required if not providing transaction_id
employee_namestring
Employee name.
amountnumber
Transaction amount. Required if not providing transaction_id
scorenumber
Customer score.
journeystring
Customer journey. Required if more than one journey is registered for the instance. If not provided, the default journey will be used. An error will be displayed if provided incorrectly.

Example:

{
    transaction_id: 'Transaction ID',
    form_id: 'Form ID',
    customer_id: 'Customer ID',
    name: 'Customer Name',
    email: '[email protected]',
    phone: '1234567890',
    phone2: '0987654321',
    document: 'ABC123',
    birth_date: '1990-01-01',
    store_id: 'Store ID',
    store_name: 'Store Name',
    employee_id: 'Employee ID',
    employee_name: 'Employee Name',
    amount: 100,
    score: 5,
    journey: 'purchase',
    param_coupon: 'XXX-XXX'
}

Any field prefixed with param_ is considered an extra transaction parameter that can be used for traceability.

Parameter options

Additional configuration options for the Widget.
targetstring|null
For inline widgets, defines the ID of the element where the widget will be inserted.
widthnumber
Widget width. When not defined, the default width is 100%.
heightnumber
Widget height. When not defined, the height is automatic.
retryobject
Configures widget display attempts. attempts: How many times to show the widget before giving up, interval: Interval (in days) between collection attempts.
waitDelayAfterRatingnumber
Time for the widget to reappear after a response (in days). Default value: 60.
callbacksobject
Enables callback options.

Example:

interface WidgetOptions {
    target?: string | null;
    width?: number;
    height?: number;
    retry?: {
        attempts?: number;
        interval?: number;
    };
    waitDelayAfterRating?: number;
    callbacks?: {
        onOpened?: (userId: string) => void;
        onClosed?: () => void;
        onError?: (message: string) => void;
        onPageChanged?: (page: string) => void;
        onQuestionAnswered?: () => void;
        onCompleted?: (userId: string) => void;
        onPartialCompleted?: (userId: string) => void;
        onResize?: (height: string) => void;
    };
}

const options: WidgetOptions = {
    target: "my_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
};

Callbacks Configuration

The widget supports callback functions that are triggered when specific events occur. Add them to your options object:

  • callbacks (object): Optional callback functions for widget events.
    • onOpened (function): Called when the widget is opened. Receives userId as parameter.
    • onClosed (function): Called when the widget is closed.
    • onError (function): Called when an error occurs. Receives error message as parameter.
    • onPageChanged (function): Called when the user navigates to a different page within the widget. Receives page as parameter.
    • onQuestionAnswered (function): Called when the user answers a question.
    • onCompleted (function): Called when the widget is completed successfully. Receives userId as parameter.
    • onPartialCompleted (function): Called when the widget is partially completed. Receives userId as parameter.
    • onResize (function): Called when the widget is resized. Receives height as parameter.

Example with callbacks:

const options = {
    target: "my_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    callbacks: {
        onOpened: (userId) => {
            console.log('Widget opened for user:', userId);
        },
        onCompleted: (userId) => {
            console.log('Widget completed by user:', userId);
            window.location.href = '/thank-you';
        },
        onError: (message) => {
            console.error('Widget error:', message);
        },
        onClosed: () => {
            console.log('Widget closed');
        }
    }
};

Complete Example:

const apiKey = "YOUR_API_KEY";
const type = "inline";
const data = {
    transaction_id: "Transaction ID",
    form_id: "Form ID",
    customer_id: "Customer ID",
    name: "Customer Name",
    email: "[email protected]",
    phone: "1234567890",
    phone2: "0987654321",
    document: "ABC123",
    birth_date: "1990-01-01",
    store_id: "Store ID",
    store_name: "Store Name",
    employee_id: "Employee ID",
    employee_name: "Employee Name",
    amount: 100,
    score: 5,
    journey: "purchase",
    param_coupon: "XXX-XXX",
};

const options = {
    target: "my_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    callbacks: {
        onOpened: (userId) => console.log('Widget opened:', userId),
        onCompleted: (userId) => console.log('Widget completed:', userId),
        onError: (message) => console.error('Widget error:', message),
        onClosed: () => console.log('Widget closed')
    }
};

createSoluCXWidget(apiKey, type, data, options);

Widget Response Handling

The createSoluCXWidget function returns a promise that resolves to an object with the following structure:

  • status: "success" or "error"
  • message: A string containing an error message if the status is "error"

Example:

createSoluCXWidget(apiKey, type, data, options)
    .then(response => {
        console.log(response); // { status: "success" }
    })
    .catch(error => {
        console.log(error); // WidgetError { status: "error", message: "Error message" }
    });

Conclusion

By following the instructions above, you can quickly integrate and configure the SoluCX Widget in your application or website. Use the provided examples to adjust and customize the widget according to your data collection and customer feedback needs.

If you have any questions or encounter any issues, please contact SoluCX support. Happy implementation!

How to configure
Comprehensive documentation about the SoluCX Widget - platform and code configurations
Flutter
Flutter package for integration with SoluCX Widget