Promos & trigger rules

A promo is a marketing overlay — a discount announcement, exit-intent email capture, flash sale — authored in Dashboard → Promos from ten visual templates, raw custom HTML/CSS, or a plain-language description (the AI generator picks the template and writes the copy). Each template pairs authoring defaults with a render preset (colors, timer style, image side); your config overrides any of it: eyebrow, headline (+accent), body, discount line, image, badge, perks footer, decline link, CTA, countdown, colors, and an optional click-to-copy coupon_code.

Promos report three counters — impression (rendered), click (CTA or coupon), submit (email captured, stored as a lead on the promo) — via POST /v1/promos/track.

Countdown modes

Trigger rules

WHEN a promo (or a survey) appears is a trigger rule: a small JS function body stored with the rule and executed by the tag as new Function("ctx", script). A broken rule can never take the storefront down — every rule runs in its own try/catch.

The ctx API:

ctx.show()                      // show the target (respects frequency + rollout)
ctx.onExitIntent(fn)            // cursor leaves the viewport top
ctx.onTimer(seconds, fn)
ctx.onIdle(seconds, fn)         // no mouse/key/scroll/touch for N seconds
ctx.onScrollDepth(pct, fn)
ctx.onEvent(name, fn)           // any tracked analytics event
ctx.onUrl("/cart*", fn)         // glob match on the pathname
ctx.page     // { path, url, referrer }
ctx.visitor  // { isNew, visits }

Example — exit intent on the cart, new visitors only:

if (ctx.visitor.isNew) {
  ctx.onUrl("/cart*", function () {
    ctx.onExitIntent(function () {
      ctx.show();
    });
  });
}

Rules ship with GET /v1/engage only while both the rule and its target are active. Rules are merchant-authored code for the merchant's own site — the same trust model as a GTM custom-HTML tag.

Frequency, rollout & scheduling

Same machinery as surveys: once_visitor / once_session / always, plus a sticky rollout_percentage hash. Evergreen countdown starts, seen-state and the visit counter persist in sg_promo_* storage keys. An optional starts_at / ends_at schedule window bounds the run — outside it the promo (and any rule targeting it) stops shipping even while status is active.

Trigger rules can also be generated from a description ("exit intent on the cart, new visitors only") — the generator returns the name, a plain-English summary and the script, validated against the ctx-only contract before you save it.

SDK API

signals.showPromo("flash-sale");   // bypasses frequency capping
signals.dismissPromo();