Popup settings schema
The complete released settings schema for popup display, triggers, rules, frequency, and appearance.
Released definition#
The complete released settings schema for popup display, triggers, rules, frequency, and appearance. This is a reference snapshot, not a replacement for server validation or capability checks.
{
"layout": {
"width": {
"kind": "len",
"units": [
"px",
"vw",
"%",
"rem",
"em"
],
"default": "640px",
"about": "The box's width, never wider than the screen."
},
"height": {
"kind": "len",
"units": [
"px",
"vh",
"rem",
"em",
"%"
],
"also": [
"auto",
"screen"
],
"default": "auto",
"about": "auto fits what is inside; screen fills the screen's height (less the edge); a length scrolls longer content inside."
},
"h": {
"kind": "enum",
"options": [
"left",
"center",
"right"
],
"default": "center",
"about": "Where it sits across the screen."
},
"v": {
"kind": "enum",
"options": [
"top",
"center",
"bottom"
],
"default": "center",
"about": "Where it sits up and down the screen."
},
"edge": {
"kind": "len",
"units": [
"px",
"rem",
"em",
"vw",
"vh",
"%"
],
"zero": true,
"default": "16px",
"about": "The space kept between the box and the screen's edges. 0 for bars and full-screen popups."
},
"tablet": {
"kind": "size",
"default": [],
"about": "Tablet overrides of width, height, h, v and edge. Anything left out is the desktop value."
},
"phone": {
"kind": "size",
"default": [],
"about": "Phone overrides of width, height, h, v and edge. Anything left out is the tablet value, then the desktop one."
},
"overlay": {
"kind": "bool",
"default": true,
"about": "Dim the page behind it. On: a modal (focus stays inside, the rest of the page is inert). Off: the page stays usable."
},
"overlayColor": {
"kind": "color",
"default": "rgba(16,24,40,0.6)",
"about": "The overlay's color; its alpha is how much it covers."
},
"overlayBlur": {
"kind": "int",
"min": 0,
"max": 20,
"default": 0,
"about": "Blur the page behind the overlay, in pixels."
},
"close": {
"kind": "enum",
"options": [
"inside",
"outside",
"none"
],
"default": "inside",
"about": "The close button: inside the box's corner, outside it, or none."
},
"closeAt": {
"kind": "enum",
"options": [
"right",
"left"
],
"default": "right",
"about": "Which top corner the close button sits in."
},
"closeDelay": {
"kind": "int",
"min": 0,
"max": 60,
"default": 0,
"about": "Seconds before the close button appears. Esc and the overlay still close it unless turned off."
},
"closeSize": {
"kind": "int",
"min": 12,
"max": 64,
"default": 28,
"about": "The close mark's size in pixels. Its target stays at least 44 pixels square."
},
"closeColor": {
"kind": "color",
"empty": true,
"default": "",
"about": "The close mark's color. Empty: the box's text color (white outside the box)."
},
"closeBg": {
"kind": "color",
"empty": true,
"default": "",
"about": "The close button's background. Empty: none."
},
"closeHoverColor": {
"kind": "color",
"empty": true,
"default": "",
"about": "The close mark's color on hover and keyboard focus. Empty: unchanged."
},
"closeHoverBg": {
"kind": "color",
"empty": true,
"default": "",
"about": "The close button's background on hover and keyboard focus. Empty: unchanged."
},
"in": {
"kind": "enum",
"options": [
"none",
"fade",
"zoom",
"zoom-out",
"up",
"down",
"left",
"right",
"flip",
"rotate",
"bounce",
"blur"
],
"default": "fade",
"about": "The opening animation. up: rises into place; left: comes in from the right."
},
"out": {
"kind": "enum",
"options": [
"none",
"fade",
"zoom",
"zoom-out",
"up",
"down",
"left",
"right",
"flip",
"rotate",
"bounce",
"blur"
],
"default": "fade",
"about": "The closing animation, played in reverse: up leaves downwards."
},
"time": {
"kind": "int",
"min": 0,
"max": 3000,
"default": 300,
"about": "The opening animation's length in milliseconds."
},
"outTime": {
"kind": "int",
"min": 0,
"max": 3000,
"default": 300,
"about": "The closing animation's length in milliseconds. Left out: the same as time."
},
"ease": {
"kind": "enum",
"options": [
"ease",
"linear",
"ease-in",
"ease-out",
"ease-in-out",
"spring"
],
"default": "ease",
"about": "The animations' easing. spring overshoots a little and settles."
},
"z": {
"kind": "int",
"min": 1,
"max": 2147483000,
"default": 99990,
"about": "Its stacking order (z-index) over the page."
}
},
"behavior": {
"autoClose": {
"kind": "int",
"min": 0,
"max": 600,
"default": 0,
"about": "Close by itself after this many seconds. 0: stays until closed."
},
"overlayCloses": {
"kind": "bool",
"default": true,
"about": "A click on the overlay closes it."
},
"escCloses": {
"kind": "bool",
"default": true,
"about": "The Esc key closes it."
},
"pageScroll": {
"kind": "bool",
"default": false,
"about": "The page can scroll behind a modal."
},
"single": {
"kind": "bool",
"default": true,
"about": "Never opens by itself while another popup is open."
},
"selector": {
"kind": "sel",
"default": "",
"about": "Elements matching this CSS selector open it when clicked (or Enter and Space on them). Prefer the element setting Advanced > Popup, which needs no selector."
},
"closeOthers": {
"kind": "bool",
"default": false,
"about": "Opening it closes any other open popup first."
},
"linkCloses": {
"kind": "bool",
"default": false,
"about": "Following any link inside it closes it first (for menus and jump links)."
},
"submitClose": {
"kind": "int",
"min": -1,
"max": 60,
"default": -1,
"about": "After a form inside it is sent: -1 stays open (showing the form's message), 0 closes at once, a number closes after that many seconds."
},
"afterSubmit": {
"kind": "enum",
"options": [
"never",
"wait",
"none"
],
"default": "never",
"about": "After a form inside it is sent: never stops it opening by itself again for that visitor; wait stops it for afterSubmitDays; none changes nothing."
},
"afterSubmitDays": {
"kind": "int",
"min": 1,
"max": 365,
"default": 30,
"about": "With afterSubmit wait: how many days."
},
"snooze": {
"kind": "int",
"min": 0,
"max": 365,
"default": 0,
"about": "After a visitor closes it, it does not open by itself again for this long. 0: no wait."
},
"snoozeFrom": {
"kind": "enum",
"options": [
"close",
"open"
],
"default": "close",
"about": "When the snooze starts: when the visitor closes it, or as soon as it opens."
},
"snoozeUnit": {
"kind": "enum",
"options": [
"hours",
"days"
],
"default": "days",
"about": "The unit of snooze."
},
"focus": {
"kind": "enum",
"options": [
"first",
"box"
],
"default": "first",
"about": "Where keyboard focus goes when it opens: the first control inside, or the box itself (screen readers start at the top)."
},
"dataLayer": {
"kind": "bool",
"default": true,
"about": "Also tell the site's own Google Tag Manager or Analytics (window.dataLayer, when the site has one): kindly_popup_open, kindly_popup_close and kindly_popup_convert, with popup_id and popup_name."
},
"stats": {
"kind": "bool",
"default": true,
"about": "Count views, conversions and closes for the Popups list. Counts only, per day: nothing about the visitor is kept."
}
},
"rules": {
"views": {
"kind": "int",
"min": 0,
"max": 1000,
"default": 0,
"about": "Opens by itself only after the visitor has viewed this many pages on the site."
},
"sessions": {
"kind": "int",
"min": 0,
"max": 1000,
"default": 0,
"about": "Opens by itself only after this many visits (a visit is a browser tab's session)."
},
"visitor": {
"kind": "enum",
"options": [
"any",
"new",
"returning"
],
"default": "any",
"about": "new: on the visitor's first visit only; returning: from their second visit on."
},
"times": {
"kind": "int",
"min": 0,
"max": 1000,
"default": 0,
"about": "Opens by itself at most this many times (per). 0: no limit. Opening by hand does not count."
},
"per": {
"kind": "enum",
"options": [
"ever",
"session",
"day",
"week",
"month"
],
"default": "ever",
"about": "What times counts within: ever in this browser, each visit, each day, each week (from Sunday) or each month."
},
"from": {
"kind": "enum",
"options": [
"any",
"search",
"social",
"ai",
"external",
"internal",
"url"
],
"default": "any",
"about": "Where the visitor arrived from (the page's referrer): a search engine, a social network, an AI assistant, another site, this site, or an address containing fromUrl."
},
"fromUrl": {
"kind": "str",
"max": 200,
"pattern": "/^[^<>\"\\s]*$/D",
"default": "",
"about": "With from url: words the referring address contains."
},
"fromNot": {
"kind": "bool",
"default": false,
"about": "Turns the from rule around: opens for everyone except visitors arriving that way."
},
"query": {
"kind": "strs",
"max": 5,
"pattern": "/^[A-Za-z0-9_.\\-\\[\\]]{1,60}(=[^&#<>\"\\s]{0,100})?$/D",
"default": [],
"about": "Address parameters that must all be present, as name or name=value (such as utm_source=newsletter)."
},
"popups": {
"kind": "strs",
"max": 5,
"pattern": "/^[1-9]\\d{0,9}:(seen|closed|converted|not-seen|not-converted)$/D",
"default": [],
"about": "Other popups this visitor must (or must not) have seen, closed or converted with, as ID:seen, ID:closed, ID:converted, ID:not-seen or ID:not-converted. All must hold."
},
"cookie": {
"kind": "str",
"max": 64,
"pattern": "/^[A-Za-z0-9_.\\-]*$/D",
"default": "",
"about": "A cookie's name to check. Empty: no cookie rule."
},
"cookieHas": {
"kind": "bool",
"default": true,
"about": "true: opens only when the cookie is set; false: only when it is not."
},
"devices": {
"kind": "list",
"options": [
"desktop",
"tablet",
"phone"
],
"min": 1,
"default": [
"desktop",
"tablet",
"phone"
],
"about": "Screen sizes it opens by itself on, from the site's own screen sizes."
},
"os": {
"kind": "list",
"options": [
"windows",
"mac",
"ios",
"android",
"linux",
"chromeos"
],
"default": [],
"about": "Only on these operating systems. Empty: every one."
},
"browsers": {
"kind": "list",
"options": [
"chrome",
"edge",
"firefox",
"safari",
"opera",
"samsung"
],
"default": [],
"about": "Only these browsers. Empty: every browser."
},
"start": {
"kind": "when",
"default": "",
"about": "Opens by itself from this date and time (the site's time zone). Empty: no start."
},
"end": {
"kind": "when",
"default": "",
"about": "Until this date and time (the site's time zone). Empty: no end. After it, pages no longer load it."
},
"scheduleTz": {
"kind": "enum",
"options": [
"site",
"visitor"
],
"default": "site",
"about": "Whose clock start, end, days and times of day are read on: the site's time zone or the visitor's own."
},
"days": {
"kind": "days",
"default": [],
"about": "Only on these weekdays (0 Sunday to 6 Saturday, the site's time zone). Empty: every day."
},
"timeFrom": {
"kind": "time",
"default": "",
"about": "Only from this time of day (HH:MM, the site's time zone). With timeTo earlier, the window runs past midnight."
},
"timeTo": {
"kind": "time",
"default": "",
"about": "Only until this time of day (HH:MM, the site's time zone)."
},
"hide": {
"kind": "enum",
"options": [
"none",
"in",
"roles"
],
"default": "none",
"about": "Signed-in people: show to everyone, hide from everyone signed in, or hide from some roles. Decided on the server: pages that get such a popup are sent uncacheable."
},
"roles": {
"kind": "roles",
"default": [],
"about": "With hide roles: the roles it is hidden from."
},
"split": {
"kind": "str",
"max": 40,
"pattern": "/^[A-Za-z0-9_\\-]*$/D",
"default": "",
"about": "A split-test group name. Of the popups loaded on a page that share it, each visitor is given one at random (kept in their browser) and only that one opens by itself. Compare them in the Popups list."
}
}
}
Use in an integration#
Preserve enum values and stable identifiers exactly. Use visible labels for people and serialized keys for requests. A missing key can invoke a default; it should not be treated as equivalent to every possible empty value. Re-read the installed version’s schema when updating an integration.