Widget integration reference
Quick picture: every embed is one tag with data-pub and data-website. You choose which script file matches your product: full-page geo overlay, in-page section, or optional decline (server-triggered). Same API host (data-api or default https://api.affilfinder.com).
This page explains how each mode works, which file to load, and how the pieces fit together.
Scripts at a glance
| Script | Doc | Use case |
|---|---|---|
widget.js | Geo-blocking widget | Full-page overlay when the visitor is outside your allowed regions (geo rules). |
widget-section.js | Section widget | Sponsored offers inside a container (mode=section on the decision API). |
widget-decline.js | Decline widget | Optional; your server triggers the overlay after your own decline path. |
Host scripts from https://affilfinder.com/ (or your dashboard origin when testing). The root DOM container for overlays is #affilfinder-root (created by the script).
Required attributes
Every script tag needs:
data-pub— your public keydata-website— your website key
Optional:
data-api— override the API base URL (defaults tohttps://api.affilfinder.com). Use this for staging or self-hosted API.data-comments="false"— reduce console logging from the snippet.data-dev-country/data-dev-region— development only to simulate a location (e.g.US,NY).
Section mode also needs a container on the page, e.g. , and:
data-container="affilfinder-ads"on the script if you use a non-default id.
Geo-blocking (widget.js)
1. Visitor loads your page; the script requests GET /v1/decision with keys and inferred location.
2. If the visitor is allowed, nothing is shown (normal site).
3. If blocked, the script loads offers via GET /v1/offers and renders the overlay (#affilfinder-root).
Your site domain must match the domain configured on the website in the dashboard (CORS).
Section mode (widget-section.js)
Same keys and domain rules; the API uses mode=section. Offers render inside your container instead of a full-screen overlay.
Decline widget (widget-decline.js)
For “we’re not proceeding” flows where you still want alternative offers, with you deciding when the overlay opens.
Turn it on in Site details → Decline widget to get the integration secret and snippet (Widget installation in the app).
Simple flow
1. Browser loads widget-decline.js → AffilFinder returns a sessionId and starts polling.
2. Your frontend sends that sessionId to your API (cookie session, signed token, etc.).
3. When your rules say “show offers”, your server calls POST /v1/widget-decline/trigger with the secret and { "sessionId" }. The next poll sees ready and the overlay runs (same offer UI as geo-blocking).
If you never trigger, the session eventually expires and polling stops.
Security: Integration secret = server only. Never in the browser or NEXT_PUBLIC_*.
Publisher app proxy (optional)
If you load the script from the publisher dashboard origin (e.g. /api/widget), the response may define AFFILFINDER_API for you. The legacy name AFFILIGATE_API is set as an alias for compatibility.
Further reading
- Widget installation hub — choose an embed.
- Geo-blocking widget · Section widget · Decline widget
- REST API reference — request/response shapes for public endpoints.
- Configuring geo rules — allowlists and blocked traffic.
Need more help?
Can't find what you're looking for? Reach out to our team and we'll get you sorted.