Kindly EditDocumentationTry the editor

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.

About this page

Documents Kindly Edit 0.9.16. Source: cantata_edit_popup_schema(). Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.