Guide
Guía del widget de Populvo
Última actualización: November 2026
<script src="https://populvo.com/widget.min.js" data-site-id="YOUR_API_KEY" async></script>Quick start
Sign up, add your website under Dashboard → Sites, and copy the embed snippet from the site card. It looks like this:
- Paste the snippet just before
</body>on every page where popups should appear. - Create a campaign under Dashboard → Campaigns, pick a theme, and keep it active.
- Reload your site. After the campaign delay (default 5 seconds) the first popup appears in the bottom-right corner. Until you add real notifications, the widget shows sample data so you can see the layout immediately.
Embedding: script tag reference
The widget is a single script tag with data-* attributes. Load it with async (as in the snippet), so it never blocks page rendering.
| Attribute | Required | Description |
|---|---|---|
data-site-id | Yes | The site's API key from the dashboard. Without it the widget logs an error and does nothing. |
data-api-url | No | Base URL of your Populvo app (no trailing slash). Optional since widget v1.8.0: when omitted, the widget derives the origin from the script tag's own src, which is the Populvo app in every standard embed. See below for when to pass it. |
any other data-* | No | Privacy-mode values (names, locations, products, and more). See Feeding notifications below. |
When is data-api-url needed?
Since widget v1.8.0 the widget reads the API origin from the script tag's own src, so the standard snippet needs nothing extra. Keep passing data-api-url when widget.js reaches the page from an origin other than the Populvo API: a self-hosted or CDN copy of the file, or a same-origin proxy setup. In those cases pass data-api-url="https://populvo.com" exactly as the dashboard snippet shows it. One widget script per page: the first script tag with a site id is the one that runs.
Feeding notifications
Option A: privacy mode with data-* attributes (recommended)
Put notification values directly on the script tag as comma-separated lists:
<script async
src="https://populvo.com/widget.min.js"
data-site-id="YOUR_API_KEY"
data-name="John,Manny,Joseph"
data-location="India,USA,Canada"
data-product="Pro Plan"></script>- Values are paired up by position:
John/India/Pro Plan,Manny/USA/Pro Plan,Joseph/Canada/Pro Plan. - Shorter lists cycle. With one entry in
data-product, all three popups use "Pro Plan". - The longest list decides how many notifications exist, capped at 20.
- Values are trimmed; empty entries are dropped. A single value cannot contain a comma (the comma is the separator).
- Fake timestamps ("just now", "3 min ago", ...) are shown and cycle through a fixed set.
Values stay on your site
These values never leave the visitor's browser. They are not sent to Populvo, not stored, and never appear in any log. The widget substitutes values locally as plain text. When any data-* variable is present, stored notifications are ignored.
Privacy mode also joins the product-link map: data-product values match it exactly like stored notifications do, and per-item data-url / data-imageUrl lists on the script tag act as per-item overrides (same position pairing and cycling as the other lists).
Option B: stored notifications
Without data-* attributes, the widget shows notifications attached to the campaign. Add them in the dashboard (campaigns store the values the template uses). The widget shows the 20 most recent active notifications with a relative timestamp on each ("just now", "12 min ago", "3 hours ago", "2 days ago"). New notifications appear in the widget within about a minute.
Fallback samples
A campaign with no notifications (and no data-* attributes) is served random sample notifications with plausible names, locations, and products. This keeps the widget demonstrable out of the box. Add one real notification (or switch to privacy mode) to replace the samples. On these samples {{count}} and {{timeframe}} (used by the Live Visitor Signup and Milestone demo themes) are filled with random values (a count between 4 and 40, a timeframe between 10 minutes and 24 hours), so consecutive popups vary. Any built-in variable the samples do not carry, such as {{discount}} or {{quote}}, is filled with its default.
Message templates
A campaign's template is the sentence each popup shows. {{var}} placeholders are filled from notification data:
- Variable names may contain letters, digits, underscores, and dashes (
{{name}},{{productId}},{{plan-2}}). - Any variable name works. The template defines the vocabulary, not the dashboard.
- Placeholders with no matching value are left visible on purpose, so a misconfigured template is immediately obvious. The seven built-in variables (
{{name}},{{location}},{{product}},{{count}},{{timeframe}},{{discount}}and{{quote}}) are the exception: they fill with defaults (John, New York, Pro Plan, 12, 24 hours, 20 and a sample quote) when your data has no such field, because you get them from the theme picker and the editor's variable buttons rather than writing them yourself. In privacy mode, pass the matchingdata-*attributes. - Substitution is single-pass and the result is rendered as plain text, never HTML. Values cannot inject markup into your pages.
- Picking a demo theme in the dashboard auto-fills a matching default template (custom themes never change it). The auto-fill only applies until you edit the template yourself.
Campaign settings reference
All of these live in the campaign form under Dashboard → Campaigns. Defaults apply when a value is missing or invalid.
| Setting | Type | Range | Default | What it does |
|---|---|---|---|---|
delay | seconds | ≥ 0 | 5 | Wait before each popup appears. |
frequency | seconds | ≥ 1 | 10 | Pause between popups in the rotation. |
displayDuration | seconds | 1–300 | 5 | How long each popup stays on screen. |
position | enum | 4 corners | bottom-right | Screen corner the popups occupy. |
appearAnimation | enum | slide / fade / pop / bounce / none | slide | How each popup enters the screen. |
disappearAnimation | enum | slide / fade / pop / bounce / none | slide | How each popup leaves the screen. |
attentionEffect | enum | none / pulse / wiggle / shine | none | Subtle repeating effect while a popup is visible. |
themeId | string | demo id or custom theme id | classic | Which theme styles the card (see Themes below). |
schedule | datetime pair | both optional | none | Window in which the campaign is served. |
productLinks | array | ≤ 50 entries | none | Per-product click-through URL + thumbnail image URL, matched on the notification's product value. |
cardWidth | px | 180–600 | theme default | Card width override. |
borderRadius | px | 0–40 | theme default | Corner radius; 0 gives square corners. |
backgroundColor | CSS color | hex / rgb() | theme default | Card background override. |
textColor | CSS color | hex / rgb() | theme default | Message text color override. |
pageTargeting | object | all / contains / exact | all | Stored with the campaign; not applied yet. |
isActive | boolean | Only active campaigns are ever served. | ||
template | string | per style | The popup sentence. |
position
One of bottom-right, bottom-left, top-right, top-left. On screens 480px wide or narrower the popup shrinks to fit the viewport and the corner insets tighten to 12px.
appearAnimation / disappearAnimation
How each popup enters and leaves the screen, set independently: slide (the default, in from and out to the screen edge), fade (opacity only), pop (scales up from and down to 85%), bounce (slides in with an overshoot, wind-up exit), and none (instant). Missing or unknown values fall back to slide.
attentionEffect
A subtle effect that repeats while the popup is on screen: pulse (a soft breathing glow around the card), wiggle (a tiny shake every few seconds), and shine (a light band sweeping across the card). The cycle length varies a little for every popup, and every effect switches off for visitors who prefer reduced motion.
Timing model
One popup cycle takes delay + displayDuration, and cycles are separated by frequency, so with the defaults (5 / 10 / 5) a new popup appears every 20 seconds. The widget never overlaps cards. A displayDuration below 1 second is treated as 1 second.
schedule
Optional start and end datetimes. Both bounds are independent: a campaign with only a start comes up at that moment and stays up; one with only an end goes down at that moment. end must be after start.
pageTargeting
You can store a targeting rule (all, contains, or exact, plus a URL value), but the current widget does not apply it: a served campaign shows on every page that embeds the script. Treat it as reserved for a future release; if you need per-page control today, embed privacy-mode data-* values only on the pages that should show popups.
One live campaign per site
The widget serves the first active campaign whose schedule window includes now. Deactivate other campaigns to make sure the one you want is the one being served.
Appearance (cardWidth, borderRadius, backgroundColor, textColor)
Every field is optional; anything unset keeps the theme's default. Colors accept hex (#rgb, #rrggbb, #rrggbbaa) or rgb()/rgba(). A radius of 0 gives square corners, and a custom text color also recolors the timestamp (at reduced opacity) so the card stays readable on custom backgrounds. These live in the Advanced section next to the product links.
Themes
The popup's card background, border, shadow, corner radius, icon bubble, icon, text colors, verified badge, and font all come from the campaign's theme (themeId): one of the 12 read-only demo themes below, or one of your own themes designed at Dashboard → Themes with full control over every token (including any Lucide icon, or none). The "Verified" badge is a small green checkmark plus the word "Verified" on the timestamp line, rendered only for themes that have it. Legacy style ids keep working and translate to their demo theme.
Classic Purchase
classic
White card, indigo/violet gradient bubble, user icon, Verified badge
Live Visitor Signup
live-visitor
Dark card, indigo/violet bubble, users icon
Plan Upgrade
plan-upgrade
Green-tinted card, green bubble, crown icon, Verified badge
Product/Feature Usage
product-feature
Purple-tinted card, purple bubble, file icon
Free Trial Signup
free-trial
Orange-tinted card, orange bubble, zap icon, Verified badge
Testimonial
testimonial
Red-tinted card, amber bubble, star icon
Milestone / Stats
milestone
Blue-tinted card, blue bubble, users icon
Special Offer
discount
Pink-tinted card, pink bubble, tag icon
Stock Alert
low-stock
Amber-tinted card, amber bubble, package icon
Download Activity
download
Sky-tinted card, sky bubble, download icon
5-Star Review
review
Violet-tinted card, violet bubble, thumbs-up icon
New Lead
lead
Slate-tinted card, slate bubble, calendar icon, Verified badge
Clicks and product links
Where the click-through URL comes from
Every popup click opens the notification's product URL in a new tab (noopener,noreferrer) when one resolves; only http:// and https:// URLs are honored, and javascript:/data: URLs are always rejected. The URL comes from:
- The notification's own
data.url/data.imageUrl(per-notification override), when set. - Otherwise the campaign's product links map: the entry whose product name matches the notification's product value (trimmed, case-insensitive) supplies the click URL and optional thumbnail image URL.
- Privacy-mode notifications participate in both:
data-productmatches the same map anddata-urllists on the script tag act as per-item overrides.
When an image URL resolves, the thumbnail renders in place of the style's icon bubble (loaded with referrerPolicy="no-referrer", so the visitor's page URL never reaches the image host); a broken image falls back to the icon.
productLinks
An array of { "product": "Pro Plan", "url": "https://…", "imageUrl": "https://…" } entries (both URLs optional, http(s) only, ≤ 2048 characters, ≤ 50 rows). The widget matches each notification's product value against the entries (trim + case-insensitive); on a hit, clicking the popup opens the URL in a new tab and the image renders as the card thumbnail in place of the icon bubble. Notifications with explicit data.url / data.imageUrl override the map for that item. Rows are managed in the campaign form's Advanced section.
Troubleshooting
No popups appear
- Check the browser console for
[Populvo]messages. A missingdata-site-idis reported there. - Confirm the campaign is active, inside its schedule window, and that no earlier active campaign on the same site is shadowing it.
- Wait at least
delayseconds after page load. With defaults the first popup shows after 5 seconds.
Popups show on the wrong domain / fail to load
Since widget v1.8.0 the widget derives the API origin from the script tag's own src, so a standard embed needs no data-api-url. If widget.js is served from an origin other than the Populvo API (self-hosted copy, CDN, proxy), the derived origin is wrong: add data-api-url="https://populvo.com".
A placeholder like {{color}} is visible in the popup
The template has a variable your data does not provide. Fix the template or add the matching data-* attribute or data field. The seven built-in variables ({{name}}, {{location}}, {{product}}, {{count}}, {{timeframe}}, {{discount}}, {{quote}}) are the exception: they fill with defaults server-side; in privacy mode pass the matching data-* attributes.
Values are cut or repeated
Privacy mode pairs list positions and cycles shorter lists, capped at 20 notifications. Also remember values cannot contain commas.
I changed a setting and nothing happened
The widget refreshes on its own schedule; allow up to a minute before judging the change.