This article covers the following
Overview
Wingify's built-in widget library provides a strong starting point for enhancing conversions, but unique design requirements and business objectives often demand more tailored solutions. Custom widgets address this need directly.
Creating custom widgets lets you build proprietary UI components from scratch and deploy them in your experimentation and personalization campaigns. Use them to align with your brand's design, capture specific user interactions, or deliver experiences precisely suited to your audience.
For example, a SaaS company might want to add a custom Pricing Comparison widget that pulls live data from their API. Instead of manually coding this change into every variation, a developer can build a reusable custom widget template. This allows marketing teams to deploy the interactive comparison tool across multiple campaigns simply by dragging and dropping the widget and filling in the required fields in the visual editor.
Create a Custom Widget
Follow these steps to build a new custom widget from scratch within the Wingify interface:
- Open your campaign in the Visual Editor.
- On the left-hand menu, click the Add icon and select Widgets.
- In the Widgets panel, click Start building under the Custom Widgets section.
- In the Create widget dialog, enter a Name for your widget (for example, EMI Calculator).
- Select a Category from the dropdown menu, such as Engagement, Conversion, or Social, to help categorize your widget in the widget library.
- [Optional] Click + Add description to provide details on the widget's intended use or limitations.
Configure Widget Properties
Once the basic details are set, you must define the technical structure and the user-facing settings of the widget. A widget consists of four sections:
-
HTML
Enter the HTML markup that defines the structure and content of the widget. -
Styles
Enter the CSS code used to control the appearance and styling of the widget. -
JavaScript
Enter the JavaScript code that injects, renders, and controls the widget behavior on the page. -
Configuration
Define the settings that users can modify from the Visual Editor without editing the underlying code.
The Configuration section creates a dedicated form that appears whenever a user adds the widget to a campaign. Users can update widget parameters directly through this form, making the widget easier to customize and reuse.
Configuration Properties
Each configuration field is defined as an object with the following properties:
| Property | Type | Description |
| type | String | Defines the type of component to display in the configuration form |
| propName | String | Specifies the key used to store and retrieve the value from the DATA object |
| label | String or Object | Defines the label displayed for the field in the configuration form |
| value | Any | Specifies the default value of the component. |
Tip: Click + Insert Setting to view all available configuration components and insert the required component with the correct syntax. After insertion, update the property names and default values to match your widget requirements.
Developer Notes
- In the HTML and STYLES sections, variables can be used anywhere with the following syntax: {{propName}}. The code is automatically parsed and detected variables are replaced dynamically. In the JavaScript section, these variables are available through the DATA object, which can be accessed directly in your code.
- When the widget is rendered:
- CSS is injected into a dedicated <style> tag within the page's <head>.
- Variable placeholders in the HTML are replaced with their configured values.
- The processed HTML is passed to the JavaScript code as a string.
- The JavaScript is executed immediately after the CSS is injected.
The platform executes your JavaScript inside a function and provides the following arguments:
Available Arguments
HTML
An HTML string with all configuration variables already replaced. You can insert it into the DOM directly or convert it into DOM elements for further manipulation.
DATA
An object containing all widget configuration values. Each property corresponds to a configured propName and contains either the default value or the value specified by the user.
UNIQUE_ID
A unique string identifier for the widget instance. Use it to generate unique IDs, class names, storage keys, and similar identifiers.
TEST_ID
The numeric identifier of the current campaign. This can be useful for tracking, analytics, or debugging purposes.
HELPERS
A shared helper object available to all custom widgets and scripts.
You can explore the default Custom Widget examples available in your account to understand different implementation patterns:
- Download Button – A simple example demonstrating basic widget structure and configuration.
- Wheel of Fortune – A more advanced example showcasing a complex configuration form and custom widget behavior.
Use Custom Widgets
After creation, your widget appears in the Custom Widgets section of the Add menu.
- Navigate to the Add > Widgets menu in the Visual Editor.
- Under Custom Widgets, select the widget you created.
- Select the desired location on your webpage.
- Use the Edit panel on the right to configure the custom settings you defined during the configuration step, such as entering text or adjusting values with the sliders.
Need more help?
For further assistance or more information, contact Wingify Support.