Widget installation overview
ReTarget.gg ships three embeds plus an iframe fallback. Pick the one that matches your flow: same keys, same API.
ReTarget.gg ships three scripts and one iframe fallback. You use exactly one per page. They all share the same keys, the same API, and the same analytics: only the surface differs.
Pick an embed
| Script | Doc | Best for |
|---|---|---|
widget.js | Geo-blocking widget | Full-page overlay when visitors are outside your licensed regions. |
widget-section.js | Section widget | Sponsored offers in a box inside your layout (sidebar, article footer). |
widget-decline.js | Trigger Widget | After your server declines a user, show alternative offers (server-triggered). |
iframe | Iframe fallback | Popup builders (GeoTargetly, OptinMonster) where you can't drop a script tag. |
Which one do I want?
Is your vertical regulated (iGaming, finance, crypto)?
Use the Geo-blocking widget. It renders a full-screen overlay only when the visitor is outside your license: visitors who should see your product never notice it's there.
Do you run a content site (recipes, news, how-to)?
Use the Section widget. Offers render inline inside a
<div>you place in the page: works like any other ad block.Does your app decide eligibility per user (KYC, deposit, risk)?
Use the Trigger Widget. Your server triggers the overlay only for users you've already declined: perfect fallback for failed signups.
Are you stuck inside a popup builder without access to a script tag?
Use the Iframe fallback. Two query params, any popup builder that accepts custom HTML.
Before you start
Register your website
Add a website in the dashboard and copy the public key and website key.
Configure your geo allowlist
Dashboard → Websites → your site → Geo rules. Add the countries where your primary product is available. Everyone else becomes eligible for offers.
Plan your test
Grab a VPN or have a friend in a blocked country reload the page after install. Without a real blocked test, you'll never know the install worked.
Common attributes
Every script tag takes the same three minimum attributes:
| Attribute | Required | Purpose |
|---|---|---|
src | yes | URL of the script (widget.js, widget-section.js, or widget-decline.js). |
data-pub | yes | Your public key (pk_…). |
data-website | yes | Your website key (web_…). |
Optional, shared across all three:
| Attribute | Purpose |
|---|---|
data-api | Override API base URL (defaults to https://api.retarget.gg). Use for a staging API. |
data-comments="true" | Turn on verbose console logging for local debugging. |
data-dev-country / data-dev-region | Localhost only. Force a simulated country (e.g. DE, BY). Ignored on non-localhost hosts unless data-allow-localhost="true" is set. |
Section mode also accepts a data-container="<id>" attribute to pick which <div> to mount into, plus data-max-ads="<n>" (1 to 24, default 6).
Verifying installation
After you install any embed, test from a VPN or location that matches your geo rules. On the website detail page in the dashboard, the Visitors panel shows a green Live pill within a minute of your first page view, along with country and device breakdowns as traffic builds.
See Debugging when the overlay doesn't render or clicks don't show up in analytics.
Performance
All three scripts are:
- Async by default: they never block first paint or hurt Core Web Vitals.
widget.jsandwidget-section.jsissue one decision request and, only when blocked, one offers request. - Lazy: offer fetch only runs after a blocked decision, so allowed visitors incur one tiny fetch and nothing else.
Next steps
Geo-blocking widget
Full-page overlay install with attributes, iframe setups, and verification.
Section widget
Inline section embed with layout tips and container options.
Trigger Widget
Server-triggered overlay for KYC / deposit decline flows.
Iframe fallback
No-script path for popup builders like GeoTargetly and OptinMonster.
Widget integration reference
End-to-end reference for every attribute, API URL, and behavior.
API reference
REST endpoints behind the widgets.
Publisher
Geo Popup & Decline Popup overview
The product framing for the install you just read.
Advertiser
CPC, CPA, eCPM in one auction
The demand side of the network — useful context even for publishers.
Essays
Long-form strategy
How others think about geo-blocking, KYC declines, and bid models.
Need help with setup?
Send us your website stack, target regions, and whether you are installing Geo Popup or Decline Popup.