Widget Types Reference

Widget Types

Reference for supported widget types, placement intent, and implementation guidance.

Audience: Product and frontend teams choosing the right widget format per use case.

Critical: Widget type must match enum-backed supported values in create/update payloads.

Modules: Widgets Campaigns API Endpoints

Who This Page Is For

Use this page when selecting widget types for campaigns, announcements, behavior prompts, or metric badges.

Quick Start (2-5 Minutes)

Pick widget intent

Select widget based on campaign intent and placement context.

Announcement vs popup vs embedded vs metric badge.

Map intent to type

Use canonical widget enum value in payload.

Example: announcement_bar, slide_in, product_view_count.

Create and style widget

Create with contentJson/stylesJson/placementConfig.

POST /api/v1/widgets

Test and activate

Use isTestMode during QA, then toggle status to go live.

POST /api/v1/widgets/:id/toggle-status

Validate runtime output

Check active widget delivery from public endpoint.

GET /api/v1/public/sites/:siteKey/widgets

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`type`	Required	`WidgetType`	Widget create/update	Widget visual and behavioral type selector.
`contentJson`	Optional	`object`	Widget render	Widget content payload.
`stylesJson`	Optional	`object`	Widget render	Style and theme overrides.
`placementConfig`	Optional	`object`	Widget placement	Positioning and placement behavior controls.

Supported widget types

announcement_bar
inline_banner
floating_button
exit_intent_popup
slide_in
embedded_card
sticky_footer
countdown_timer
cookie_consent
custom
product_view_count
cart_count
newsletter

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Top-of-page promo message	announcement_bar	High visibility persistent announcement area.
Contextual embedded module in page flow	embedded_card or inline_banner	Fits naturally in content layout.
Trigger-based promotional modal	exit_intent_popup	Supports exit intent, time delay, scroll depth, page load, or custom event strategies.
Floating persistent CTA	floating_button	Always accessible action entry point.
Real-time social proof counters	product_view_count or cart_count	Metric-driven urgency indicators.
Tenant email lead capture	newsletter	Collects newsletter signups into tenant audience pool and supports audience sync.

newsletter supports fixed and selector placement modes.
Typical content fields: headline, text, emailPlaceholder, buttonText, successMessage, errorMessage.
Typical style fields: backgroundColor, textColor, input colors, maxWidth, showCloseButton.
Runtime submit target: POST /api/v1/public/sites/:siteKey/newsletter.

Common Errors and Fixes

Widget validation fails on create

Cause: Unsupported type value not in enum.

Fix: Use one of the supported widget type values exactly.

Count widgets show zero always

Cause: Product metrics events/item-code mapping missing, or storefront DOM lacks `[data-product-id]` for auto product resolution.

Fix: Validate product metrics endpoint integration, keep productItemCode consistent, and expose `[data-product-id="<productItemCode>"]` on PDP (or set contentJson.productId).

Popup widgets hurt UX

Cause: Overuse without targeting and frequency guard strategy.

Fix: Use segment/page targeting and schedule constraints.

Styled output differs from expected

Cause: stylesJson keys do not match renderer expectations.

Fix: Align style payload structure with active widget renderer schema.

Production Checklist

Widget type matches explicit campaign objective.Required
Style and placement are tested on desktop and mobile viewports.Required
isTestMode workflow is used before activation.Required
Segment/page targeting constraints are validated.Required
PDP exposes `[data-product-id]` for count widgets, or contentJson.productId is explicitly configured.Required
Public widget payload is verified on production domain.Required