man cloaking-x.stream-settingsReference

Stream Settings Reference

Every field on a stream, what it controls, and how it interacts with the check pipeline.

Name & Traffic Source#

name is the only required field on a stream. trafficSource (google / facebook / tiktok / bing / yandex / twitter / snapchat / pinterest / linkedin / taboola / other) is stored as a tag on every logged click for reporting — it doesn't change any filtering behavior.

Destination Pages & Rotation#

A stream can hold one or more destination URLs (moneyPages). With two or more configured, rotationMode decides how a passed visitor picks one:

random — a uniformly random page on every request (the default).
sequential — cycles through the list in order, one page per visitor.
timer — all traffic gets the same page for a fixed window (rotationInterval seconds), then the whole stream advances to the next page together.

With zero or one destination page configured, rotation settings have no effect.

Per-OS Overrides#

appleMoneyPage, windowsMoneyPage, and androidMoneyPage let you send specific operating systems to a dedicated destination instead of the general rotation. appleMoneyPage covers both iOS and macOS. These are checked before the rotation logic above — if a matching override is set for the visitor's detected OS, it wins.

Fallback Page#

safePage is where blocked visitors are sent. It is always delivered as a direct render — never a redirect — by design, regardless of your stream's Money Page Delivery setting below (which only applies to the destination page). If it's left empty, a blocked visitor simply isn't redirected anywhere.

Mode#

filter (full enforcement), moderation (record and score, but still deliver everyone to the destination page), off (no evaluation at all), or review (send every visitor to your Fallback Page instead, for the duration of an ad-platform review — see below). See the Block Reason Reference's mode section for exactly how each mode changes what a block reason results in.

Switch a stream to review while an ad platform (Google, Meta, TikTok, etc.) is reviewing a campaign that points at it. Every visitor — including entries on your own whitelist — is sent to your Fallback Page instead of the destination page for as long as the mode stays set, with no exceptions. Scoring and logging keep running normally underneath, so Reports still shows exactly who arrived during the review window.

Warning

While a stream is in review, "my money page isn't showing" is expected, not a bug — that includes testing from your own whitelisted IP. See Troubleshooting if this catches you off guard. There's no auto-expiry — once the campaign is approved, switch the stream back to filter (or moderation) yourself.

Threshold#

A number from 0 to 1 (default 0.5) that controls how aggressively this stream filters. Lower it to divert more traffic to your Fallback Page; raise it to let more borderline visitors through to your money page. See the Automated risk checks reference for what each individual block reason means.

Allowed Countries / OS / Devices#

Three independent allow-lists. Each is empty by default (no restriction). Once you add entries to one, a visitor who doesn't match is blocked immediately — before risk scoring even runs — with geo_blocked, os_blocked, or device_blocked respectively.

Require Click ID#

When enabled, any visitor arriving without a click ID from a recognized ad platform on the URL — gclid (Google), fbclid (Meta), ttclid (TikTok), msclkid (Microsoft/Bing), yclid (Yandex), twclid (X/Twitter), ScCid (Snapchat), epik (Pinterest), li_fat_id (LinkedIn), or tblci (Taboola) — is treated as bot/direct traffic — the check returns immediately with no risk evaluation.

Warning

This gate returns before a click is ever logged — a visitor caught by it produces no Reports entry and no click-count increment, and no redirect happens either (they stay on the page they landed on until the 10-second failsafe reveals it). If you enable this setting, expect direct/organic test visits to look like nothing happened at all — that's expected, not a bug. See the FAQ.

Visitor IP Detection#

Your PHP filter (the standalone file, or the WordPress plugin) resolves each visitor's real IP itself — it doesn't need any setting here for the most common cases. It automatically checks whether the connecting request genuinely belongs to Cloudflare's, Gcore's, or Bunny.net's own published network, and only then trusts that CDN's own forwarding header. A forwarded header is never trusted without that network proof, so a visitor with no CDN in front of them can't forge one to pick their own IP.

If this stream sits behind a different CDN or reverse proxy — one this automatic check doesn't recognize — open the stream's Filtering settings and turn on Advanced — my CDN isn't auto-detected, then enter the exact header name your CDN adds (e.g. X-Forwarded-For). That header is trusted unconditionally once set — there's no network check possible for an edge this filter doesn't know the ranges of, so only turn this on for a CDN/reverse proxy you actually control.

Warning

Get this wrong in either direction and traffic gets misjudged: picking the wrong header (or leaving this off while genuinely behind an unrecognized CDN) makes every visitor resolve to that CDN's own IP — real buyers get scored as datacenter traffic and blocked. Leaving this off while NOT behind any CDN is the SAFE default — the filter simply uses the direct connecting IP.

Warning

This is baked into your PHP filter file at download time. Changing it here does nothing to a filter you already have installed — you must re-download the file from the Integration page and replace it on your server before it takes effect.

Money Page Delivery#

moneyAction controls how a passed visitor is actually delivered to the destination page. Every existing stream defaults to proxy. A permanent 301 redirect is deliberately not offered as an option at all — browsers cache a 301 permanently, which would let a visitor bypass this filter forever after their first visit.

proxy (default)

Address bar unchanged

The server fetches the destination's HTML and serves it directly at your own URL. Can break on destinations built as a JavaScript-framework SPA (Next.js, Nuxt, Angular, React) — those apps try to take over the browser's address bar themselves and crash when served from a different domain. On the Hosted Ad Link integration, a shell like that is detected automatically (by its near-empty page content) and falls back to a real navigation instead; the downloadable PHP filter has no such detection and will show the broken shell as-is — see the FAQ.

redirect302

Address bar changes

A temporary (not permanently cached) client-side redirect, using history replace rather than a normal navigation so the Back button can't bounce the visitor into a loop.

js_redirect

Address bar changes

A straightforward client-side navigation to the destination URL.

meta_refresh

Address bar changes (eventually)

Reveals the current page first, then inserts a meta-refresh tag. Not a guaranteed-synchronous navigation the way a script redirect is — some browsers/extensions can delay or strip a meta-refresh.

iframe

Address bar unchanged

Renders the destination in a full-viewport iframe instead of navigating away. The wrapper iframe src is a same-origin relay (money is not in the outer page source). On PHP/WordPress the framed document is a same-origin rewrite; on Hosted Ad Link and the JS snippet hop-2 302s the framed document onto the money origin. Fails silently whenever the destination blocks framing.

iframe_cross_origin

Address bar unchanged

Same wrapper as iframe (same-origin relay src). Hop-2 is a 302 so the framed document is the real money origin — required on PHP/WordPress for domain-locked players (VTurb/ConverteAI) that refuse a same-origin rewrite. Visible in DevTools/Network, never the address bar. On Hosted Ad Link and the JS snippet, regular iframe already does this hop.

click_reveal

Unchanged until a real click (snippet only)

On the JavaScript snippet, shows a Continue button and gates delivery on a genuine click — the destination isn't referenced until then. On PHP, WordPress, and Hosted Ad Link this aliases to iframe (no page exists to wait for a click on the first response).

mirror

Address bar unchanged

Fetches the destination's HTML server-side and rewrites every asset reference to route through your own tracking domain instead — the destination's URL never appears anywhere the visitor can see, not even in the page source. Works best on static landing pages; a detected JavaScript-heavy app renders in place with a compatibility shim instead of being skipped, though that's best-effort and can still misbehave on complex apps. If the destination can't be fetched at all, the visitor now sees your configured Safe Page instead of a blank one — never a redirect to the destination. Currently applies to the Hosted Ad Link integration on a live custom tracking domain only — falls back automatically otherwise.

Warning

proxy does not hide your money page's own hostname from a visitor's browser: the destination's <base href> and every asset it loads (images, scripts, stylesheets) resolve directly against the money origin, in plaintext, for every passed visitor. That's a structural property of this mode, not a bug — the browser has to reach the real origin somehow. For high-risk verticals (betting, adult, pharma) that plaintext hostname is exactly the kind of link between your ad-facing domain and the money brand that gets accounts suspended for cloaking. Use mirror instead for these streams — it routes every asset through your own tracking domain so the money origin's hostname never reaches the visitor at all.

Active / Paused#

Pausing a stream (isActive: false) makes every visitor pass through untouched — no risk evaluation, no redirect, and no Reports entry at all. A visitor on a paused stream simply ends up looking at whatever HTML already exists on the page the snippet is installed on.

Read-only fields#

clickCount, blockCount, and createdAt are maintained by the server and can never be set directly, including through the API.