SoluCX Widget

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

Compatibility with Form Flex and Survey

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

Usage based on HTML example

To use the widget, add the following HTML code to your site:

<!DOCTYPE html>
<html lang="pt">
    <head>
        <meta charset="UTF-8" />
        <title>Exemplo de Widget SoluCX</title>
        <script src="https://widget.solucx.com.br/widget.js"></script>
    </head>
    <body>
        <script>
            const apiKey = "SUA_API_KEY";
            const type = "inline";
            const data = {
                name: "Nome do Cliente",
                transaction_id: "ID da Transação",
                email: "[email protected]",
                cpf: "123.456.789-00",
            };

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

How to use:

  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 dispatch method (for example, button click).

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 while 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 be highlighted without interfering with the main content, ideal for capturing the user's 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 the 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. It is ideal for when you want the widget to be part of the natural flow of the content.
  • modal: Displays the widget as a modal centered 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 the user's full attention. It is ideal for 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 = "SUA_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 client.
form_idstring
Form ID. Required only if directed to Form 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: 'ID da Transação',
    form_id: 'ID do Formulário',
    customer_id: 'ID do Cliente',
    name: 'Nome do Cliente',
    email: '[email protected]',
    phone: '1234567890',
    phone2: '0987654321',
    document: 'ABC123',
    birth_date: '1990-01-01',
    store_id: 'ID da Loja',
    store_name: 'Nome da Loja',
    employee_id: 'ID do Funcionário',
    employee_name: 'Nome do Funcionário',
    amount: 100,
    score: 5,
    journey: 'compra',
    param_cupom: '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 response (in days). Default value: 60.
enableQuarantineOptionsboolean
Enables quarantine settings.
callbacksobject
Enables callback options.

Example:

interface WidgetOptions {
    target?: string | null;
    width?: number;
    height?: number;
    retry?: {
        attempts?: number;
        interval?: number;
    };
    waitDelayAfterRating?: number;
    enableQuarantineOptions?: boolean;
    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: number) => void;
    };
}

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

Callbacks Configuration

The widget now 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: "meu_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    enableQuarantineOptions: false,
    callbacks: {
        onOpened: (userId) => {
            console.log('Widget opened for user:', userId);
            // Track widget open event
        },
        onCompleted: (userId) => {
            console.log('Widget completed by user:', userId);
            // Redirect to thank you page or show success message
            window.location.href = '/thank-you';
        },
        onError: (message) => {
            console.error('Widget error:', message);
            // Report error to your error tracking service
        },
        onClosed: () => {
            console.log('Widget closed');
            // Clean up or track closure
        }
    }
};

Complete Example:

const apiKey = "SUA_API_KEY";
const type = "inline";
const data = {
    transaction_id: "ID da Transação",
    form_id: "ID do Formulário",
    customer_id: "ID do Cliente",
    name: "Nome do Cliente",
    email: "[email protected]",
    phone: "1234567890",
    phone2: "0987654321",
    document: "ABC123",
    birth_date: "1990-01-01",
    store_id: "ID da Loja",
    store_name: "Nome da Loja",
    employee_id: "ID do Funcionário",
    employee_name: "Nome do Funcionário",
    amount: 100,
    score: 5,
    journey: "compra",
    param_cupom: "XXX-XXX",
};

const options = {
    target: "meu_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    enableQuarantineOptions: false,
    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);

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.

Handling the Widget Response

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: "Mensagem de erro" }
    });

If you have any questions or encounter problems, please contact SoluCX support. Happy coding!

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