How to Configure the SoluCX Widget
Introduction
What is the SoluCX Widget
The SoluCX Widget is a feedback collection tool that allows you to integrate satisfaction surveys directly into websites, applications, and digital platforms. Through it, you can capture customer ratings in real time using metrics such as NPS (Net Promoter Score), CSAT (Customer Satisfaction Score), and CES (Customer Effort Score).
The widget is compatible with two types of surveys:
- Flex Survey: Flexible and customizable forms
- Survey (Smart Survey): System-generated intelligent surveys
Overview: Platform vs Code
SoluCX Widget configurations are divided into two domains:
Administrative Platform: Visual, behavioral, and quarantine configurations managed through the SoluCX administrative interface, without the need to change code.
Code Integration: Initialization parameters, customer data, display options, and callbacks defined directly in the application code.
| Domain | Examples | Who configures |
|---|---|---|
| Platform | Logo, colors, input types, thank you screen, IP/CPF quarantine | Business team or administrators |
| Code | Widget type, customer data, callbacks, dimensions, retry | Development team |
| Both | Custom CSS, quarantine (platform + code) | Collaboration between teams |
Styling Configurations
Visual Identity (Platform)
Visual identity configurations are managed exclusively through the SoluCX administrative platform:
| Configuration | Description | Where to configure |
|---|---|---|
| Logo and brand | Logo upload displayed in the widget header | Platform > Settings > Visual Identity |
| Main colors | Primary and secondary widget colors | Platform > Settings > Colors |
| Dynamic colors | Colors that change based on customer score (e.g., red for detractors, green for promoters) | Platform > Settings > Dynamic Colors |
| Form Builder themes | Pre-defined visual themes for flexible forms | Platform > Form Builder > Themes |
These configurations are automatically applied to all widgets linked to the instance, without requiring code changes.
Rating Input Types (Platform)
The widget supports various rating input types, all configurable through the platform. You can edit them the same way you edit the Smart Survey or Flex Survey:
NPS (Net Promoter Score)
Scale from 0 to 10 measuring likelihood of recommendation.
| Input Type | Description |
|---|---|
| Arrow | Sliding arrow input on 0-10 scale |
| Buttons | Individual numeric buttons from 0 to 10 |
| Slider | Continuous sliding bar from 0 to 10 |
| Colored Buttons | Buttons with color gradient (red to green) |
| Gradient | Visual scale with color gradient |
CSAT (Customer Satisfaction Score)
Measures direct customer satisfaction with a product or service.
| Input Type | Scale | Description |
|---|---|---|
| Emoticons | 1-5 | Expressive faces from dissatisfied to very satisfied |
| Stars | 1-5 | Classic star rating |
| Buttons 1-5 | 1-5 | Numeric buttons from 1 to 5 |
| Buttons 1-10 | 1-10 | Numeric buttons from 1 to 10 |
CES (Customer Effort Score)
Measures the customer's effort to solve a problem or complete an action.
| Input Type | Description |
|---|---|
| Emoticon | Expressive faces representing effort level |
| Buttons | Buttons with effort scale |
| Stars | Star rating of ease level |
Scale nomenclature (endpoint labels, question title) is also customizable through the platform for each survey type.
Custom CSS
Advanced styling can be done in two ways:
Via Platform (customStyle)
The platform allows inserting custom CSS that will be applied internally to the widget iframe:
- Go to Platform > Settings > Journeys
- Insert CSS rules that will be injected inside the widget
- Useful for fine-tuning fonts, spacing, and internal colors
Via Code (options)
To style the widget's external container (position, dimensions, borders), use the code parameters:
Important difference: The platform CSS (customStyle) acts inside the iframe of the widget. Code options control the external container. For complete customizations, you may need to combine both.
Positioning and Dimensions (Code)
Widget positioning is controlled by the type parameter during initialization:
Widget Types
Embedded in page content
The widget integrates into the natural layout flow, without overlapping other elements.
- Respects DOM position
- Ideal for dedicated feedback pages
- Requires a
targetelement for rendering
Dimension Parameters
100% auto inline widgets. Default: null Behavior Configurations
Thank You Screen (Platform)
After the customer responds to the survey, a thank you screen is displayed. The following configurations are managed through the platform:
The customAcknowledgmentHTML option allows full customization of the thank you screen with custom HTML, replacing the successTitle and successMessage fields.
Redirection and Automation (Platform)
| Configuration | Description |
|---|---|
completedUrlRedirection | URL for redirection after survey completion |
autoSendTimeout | Time (in seconds) for automatic partial survey submission |
Practical use cases:
- E-commerce: Redirect to a discount coupon page after a positive rating
- Customer service: Redirect to FAQ page after feedback collection
- Auto-send: Ensure partial collection if the customer abandons the survey
Consent and Acceptance (Platform)
Configurations related to GDPR/LGPD and user consent:
| Configuration | Description |
|---|---|
| Custom contact consent text | Custom acceptance terms text |
| Consent pre-checked by default | Whether the consent checkbox comes pre-checked |
| Acceptance strategy | Acceptance strategy (e.g., opt-in, opt-out) |
LGPD/GDPR Considerations: It is recommended that the consent checkbox is not pre-checked (isUserConsentPreChecked: false) to comply with data protection laws. The acceptance strategy should be defined in conjunction with the legal team.
Contact Channels (Platform)
Configurations to enable contact channel requests based on respondent classification:
| Configuration | Description |
|---|---|
| Contact consent by channel if detractor | Request contact if the customer is a detractor (NPS 0-6) |
| Contact consent by channel if neutral | Request contact if the customer is neutral (NPS 7-8) |
| Contact consent by channel if promoter | Request contact if the customer is a promoter (NPS 9-10) |
This functionality allows collecting additional contact information strategically, focusing on the groups that need the most attention (such as detractors for experience recovery).
Quarantine System
The quarantine system controls how frequently the same customer is asked to respond to surveys, avoiding survey fatigue.
Platform Quarantine
Configurations managed through the administrative platform:
| Configuration | Description |
|---|---|
| Cookie quarantine | Enables cookie-based browser quarantine |
| IP quarantine | IP-based quarantine period (in days) |
| CPF quarantine | CPF-based quarantine period (in days) |
| Fingerprint antifraud | Device fingerprint-based quarantine period (in days) |
| Fingerprint API key | Fingerprint API key |
| Enable fingerprint collection | Enables device fingerprint collection |
Limitations: Cookie-based quarantine can be bypassed if the user clears cookies, uses incognito mode, or switches devices/browsers. For stricter control, combine with IP, CPF, or fingerprint quarantine.
Code Quarantine
Configurations defined in the options parameters during widget initialization:
| Configuration | Type | Default | Description |
|---|---|---|---|
retry.attempts | number | 3 | Number of widget display attempts before giving up |
retry.interval | number | 1 | Interval (in days) between collection attempts |
waitDelayAfterRating | number | 60 | Time (in days) for the widget to reappear after a rating |
Quarantine Flow
The quarantine system follows this logic:
- First display: Widget appears normally
- Customer doesn't respond: After the interval configured in
retry.interval, the widget tries again - Attempts exhausted: After
retry.attemptswithout response, the widget stops appearing - Customer responds: After the rating, the widget enters quarantine for
waitDelayAfterRatingdays - End of quarantine: After the period, the widget can be displayed again
Important: The widget's code-level quarantine control is based on client browser cookies. For scenarios requiring strict control, we recommend implementing additional server-side validations or using the platform quarantine options (IP, CPF, fingerprint).
Code Integration
Required Parameters
The createSoluCXWidget function requires two mandatory parameters:
apiKey (string)
API key provided by SoluCX that identifies your instance. Obtained in the administrative platform at Settings > API.
type (string)
Defines the widget display mode:
| Value | Description |
|---|---|
inline | Embedded in page content |
bottomBar | Fixed bar at the bottom |
bottomBox | Fixed box in the bottom right corner |
bottomBoxLeft | Fixed box in the bottom left corner |
modal | Centered modal on the page |
For the widget link, the required parameters are: name OR customer_id.
Customer Data (data)
The data object contains customer and transaction information:
Identification Fields
transaction_id OR name AND (email OR phone) Personal Data
transaction_id OR customer_id transaction_id OR customer_id AND phone transaction_id OR customer_id AND email YYYY-MM-DD Contextual Data
transaction_id Custom Parameters
param_ is considered an extra transaction parameter for traceability.Configuration Options (options)
Options Parameter
inline widgets, defines the DOM element ID where the widget will be inserted. attempts: number of attempts. interval: interval in days between attempts. Callback System
The widget supports callbacks for survey lifecycle events:
| Callback | Parameter | Description |
|---|---|---|
onOpened | userId: string | Widget was opened/displayed |
onClosed | — | Widget was closed by the user |
onCompleted | userId: string | Survey completed successfully |
onPartialCompleted | userId: string | Survey partially completed |
onError | message: string | An error occurred in the widget |
onPageChanged | page: string | User navigated to another page within the widget |
onQuestionAnswered | — | User answered a question. Works only for Flex Survey |
onResize | height: number | Widget was resized |
Response Handling
The createSoluCXWidget function returns a Promise:
Complete Comparison Table
Styling
| Feature | Platform | Code | Description |
|---|---|---|---|
| Logo and brand | ✓ | — | Logo upload and configuration |
| Main colors | ✓ | — | Primary and secondary colors |
| Dynamic colors | ✓ | — | Colors based on customer score |
| Form Builder themes | ✓ | — | Pre-defined visual themes |
| Input type (NPS/CSAT/CES) | ✓ | — | Visual style of the rating scale |
| Internal CSS (customStyle) | ✓ | — | CSS inside the widget iframe |
| Widget type | — | ✓ | inline, bottomBar, bottomBox, modal |
| Dimensions (width/height) | — | ✓ | Container width and height |
| Target element | — | ✓ | DOM element ID for inline |
Behavior
| Feature | Platform | Code | Description |
|---|---|---|---|
| Thank you screen | ✓ | — | Post-survey messages and HTML |
| Redirection | ✓ | — | Redirect URL after completion |
| Auto-send (timeout) | ✓ | — | Automatic submission after time |
| Acceptance text | ✓ | — | Consent terms customization |
| Acceptance strategy | ✓ | — | Opt-in vs opt-out |
| Contact channels | ✓ | — | Request contact by classification |
| Hide credits | ✓ | — | Remove "Powered by SoluCX" |
| Lock scroll | ✓ | — | Block scrolling during display |
| Allow HTML | ✓ | — | HTML in questions and descriptions |
| Language | ✓ | — | Widget language |
| Callbacks | — | ✓ | Functions for widget events |
Quarantine
| Feature | Platform | Code | Description |
|---|---|---|---|
| Cookie quarantine | ✓ | — | Based on browser cookies |
| IP quarantine | ✓ | — | Based on IP address |
| CPF quarantine | ✓ | — | Based on CPF document |
| Fingerprint quarantine | ✓ | — | Based on device fingerprint |
| Retries | — | ✓ | Number of attempts and interval |
| Post-rating delay | — | ✓ | Wait time after response |
Data and Integration
| Feature | Platform | Code | Description |
|---|---|---|---|
| API Key | — | ✓ | Authentication key |
| Widget type | — | ✓ | Display mode |
| Customer data | — | ✓ | Name, email, phone, etc |
| Transaction data | — | ✓ | ID, amount, store, employee |
| Custom parameters (param_*) | — | ✓ | Extra fields for traceability |
| Journey | — | ✓ | Customer journey identifier |
Practical Guides
Common Scenarios
Post-Purchase E-commerce
Ideal for collecting feedback after order completion:
Customer Service
For collecting feedback after support interactions:
Physical Store Survey (Kiosk/Tablet)
For in-person feedback collection on dedicated devices:
Web Application Feedback
For integration in web panels/dashboards:
Best Practices
When to use each widget type
| Type | Best for | Avoid when |
|---|---|---|
inline | Dedicated pages, kiosks, iframes | You don't want to take up layout space |
bottomBar | Passive collection, content sites | Many fixed elements in the footer |
bottomBox | E-commerce, post-transaction | Site has chat in the same corner |
bottomBoxLeft | Alternative to bottomBox | Site has left sidebar menu |
modal | Mandatory surveys, post-service | Experiences that cannot be interrupted |
Combining Platform and Code Configurations
- Set up visual identity on the platform before implementing the code
- Configure quarantine on the platform for robust control (IP, CPF, fingerprint)
- Supplement with code quarantine for additional cookie-based control
- Use code callbacks to integrate with analytics and internal systems
- Customize CSS on the platform for fine visual adjustments
Quarantine Optimization
- Testing environment: Use
waitDelayAfterRating: 0andretry.attempts: 1for easier testing - Production: Recommended
waitDelayAfterRating: 30-60days to avoid fatigue - Kiosks/Tablets: Use
waitDelayAfterRating: 0to allow consecutive ratings from different customers - Combine methods: Use platform IP quarantine + code cookie quarantine for maximum coverage
Troubleshooting
Widget doesn't appear
| Problem | Check | Solution |
|---|---|---|
| Invalid API Key | Browser console | Verify the key in the administrative platform |
| Missing required data | Browser console | Fill in name or customer_id |
| Active quarantine | Browser cookies | Clear cookies or reduce waitDelayAfterRating for testing |
| Target element doesn't exist | DOM inspector | Verify the target ID exists before calling the widget |
| Script not loaded | Network tab | Confirm widget.js loaded successfully |
CSS and positioning issues
| Problem | Likely cause | Solution |
|---|---|---|
| Widget cut off | Container with overflow: hidden | Remove overflow: hidden from parent container |
| Widget behind other elements | Low z-index | Adjust z-index via custom CSS on the platform |
| Widget not responsive | Fixed width | Don't set width or use percentage values |
| Scroll locked after closing | lockScroll active | Disable lockScroll on the platform if needed |
Debugging callbacks
Complete Code Examples
Basic Example
Advanced Example with All Parameters
Example with Callbacks and Analytics
Technical References
Available SDKs
| SDK | Technology | Package |
|---|---|---|
| JavaScript Widget | Vanilla JavaScript | widget.js (CDN) |
| React Native SDK | React Native / Expo | @solucx/react-native-solucx-widget |
| Web Component SDK | Vue.js / Web Components | solucx-survey-widget |
| Flutter SDK | Flutter / Dart | solucx_widget |
Script URL
Support
For questions or issues with widget integration, contact SoluCX support through the administrative platform or via the support email.