Cloaking
The Cloaking stream schema splits traffic into two branches: suspicious visitors (bots, moderators, data centers, VPNs) see the safe page, real people the money page. One module (core/CloakDetector.php) makes the decision for all entry points: the campaign URL (index.php), click.php, and Click API v3.
A detailed technical write-up in English: How the Orbitra Cloaker Works.
Stream setup
Safe page
Built-in HTML, an external URL, a local landing, or a local offer. Landings and offers in the list are grouped by group, with a search.
Money page
Works like the "Landing + Offer" schema, including "before the click / after the click" offer selection.
Clean visitors to the next stream
The "Send clean visitors to the next stream" checkbox turns the cloak into an entry filter. Suspicious visitors get the safe page, while clean ones continue down the stream list β geo, devices, and languages are split up by regular streams. This stream's money page is not used in this mode. Put such a stream first or make it intercepting so that every visitor passes the check.
Detection layers
| Layer | Source | Does not work without |
|---|---|---|
| Data centers / hosting | An ASN blocklist (core/data/asn_blocklist.json), published cloud and crawler ranges, hosting keywords in the ISP name | The ASN database (GeoLite2-ASN) |
| VPN / proxy | IP2Proxy PX12 (VPN, TOR, residential, threat, fraud score β₯ 80), a VPN-ASN list | IP2Proxy PX12 / the ASN database |
| Bot blacklists | IPs and User-Agent signatures from Settings β Bots | β |
| User-Agent heuristics | Crawlers and tools (facebookexternalhit, meta-externalagent, curl, python, headlessβ¦), an empty User-Agent, a missing Accept-Language | β |
If a required database is missing, the campaign editor shows a warning right in the cloak card.
Sensitivity
Signals are either hard (an explicit hit in a blocklist or reputation database) or soft (individually noisy heuristics).
| Level | Safe page when |
|---|---|
| Low | only a hard signal |
| Medium (default) | a hard signal, or two soft ones |
| High | any single signal |
Targeting filters
Applied after the passive layers; a mismatch means the safe page (TARGETING_SAFE):
- Countries β allow or block a list. If the country cannot be determined, the reason is recorded as
geo_unknownrather thangeo_country. Without a geo database every visitor isUnknown, and the country filter will send 100% of traffic to the safe page; the editor warns about this. - Device types β only the selected ones, or all except the selected ones.
- Block bots and data-center providers β the visitor's ISP and ASN compared against a list: the stream's local list or, if it is empty, the global one from Settings β Bots.
JavaScript verification
Off by default. The visitor first receives the safe page and moves to the money page via a one-time signed link (TTL 5 minutes) only after executing JS. navigator.webdriver = true stays on the safe page. So does anything that does not execute JS. The price is one extra hop for every live visitor.
With the browser check on (Settings β Bots), the same step also collects browser signals: in Soft or Strict mode a virtual machine, emulator or spoofed phone gets the safe page here, with a bc_ reason. The stream's Browser check* field can turn it off for this stream only.
Preloader. While the JS step runs (a fraction of a second) the visitor sees a loading page, configured per stream under JS Challenge Preloader: the built-in page, or your own HTML with a live preview. Historically this step reused the safe page's HTML β that markup is still shown when no preloader is configured, so existing campaigns keep their look; pick Custom HTML to override it. The verification probe is injected into your HTML automatically β do not add your own redirect scripts, they race the signed link.
Recording and reports
| Setting | Default | What it does |
|---|---|---|
| Record Safe Page clicks | on | Safe-page hits are written with is_safe_page = 1. Turn it off and they will not reach the database |
| Exclude Safe Page clicks from reports | on | Hits stay in the click log but drop out of every report metric β clicks, visits, uniques, bots, empty referers, cost, CPV. A safe hit is still a visit to the campaign link, so with the box off it counts in "Clicks" too (since 1.8.5 clicks count every visit) |
Even when hits are not written, the suppressed-hit counter (cloak_suppressed_stats) counts them per campaign, stream, day, and verdict β "zero clicks" will not hide the real traffic.
Global settings: Settings β Bots
- Bot IP addresses β IPs and CIDR, IPv4 and IPv6. Every entry has a source (manual or from a feed); cleanup can delete entries of one source only.
- Signatures (User-Agent) β substrings.
- Global Bot ISP blacklist β one provider per line. Too-short and too-generic strings (
Inc,LLC) are ignored: they would match almost every ISP. - Data-center and crawler IP ranges β published ranges of AWS, Google Cloud and Googlebot, Bing, Azure, Oracle, DigitalOcean, Facebook, Telegram, OpenAI, Cloudflare, Apple Private Relay, and others from lord-alfred/ipranges. Updated daily by the
ipranges_cron.phpcron (manually via the "Update now" button orphp ipranges_cron.php --force), stored invar/ipranges/. Until the lists are downloaded, the layer is inactive. - Browser check β Off / Observe only / Soft / Strict: bots, VMs and emulators caught by contradictions in the browser. β Browser check
- Treat VPN ASN as a bot signal β on by default. Turn it off if your audience widely sits behind a commercial VPN.
Diagnostics
- The cloak card in the editor β how many hits went to money and to safe over the selected period, the top reasons, and a link into the click log with the same window. If almost all traffic goes to the safe page, the card warns.
- The click log β the "Route" and "Reason" columns appear automatically when there are cloak clicks on the page, with a filter by route and reason. The click card shows the verdict and reasons, but only for clicks the cloak actually judged.
- The test link with
_dbg=1β a routing trace without recording a click;_geo=XXoverrides the country (Campaigns and streams). - The PHP log β lines like
Orbitra cloak [campaign=12 stream=34]: stage=PASSIVE_SAFE ... reasons=[crawler_or_tool_ua].
Verdicts and reasons
Verdicts: money, passive_safe, targeting_safe, js_safe. Reasons are written to clicks.cloak_reasons; the main ones:
| Code | Meaning |
|---|---|
geo_country / geo_unknown | country not in the list / country could not be determined |
device_type | device type not allowed |
bot_isp, isp_blocklist | ISP in the bot and data-center list |
datacenter_asn, asn_datacenter | data-center or hosting ASN |
vpn_proxy_asn | VPN or proxy provider ASN |
iprange_datacenter | IP in a published cloud or crawler range |
hosting_isp | hosting keyword in the ISP name |
ip2proxy_* | an IP2Proxy signal: vpn_proxy, datacenter, residential, tor, bot, threat, high_fraud |
bot_blocklist | IP in the bot list |
crawler_or_tool_ua, suspicious_ua, no_user_agent, missing_accept_language | User-Agent and header heuristics |
webdriver, js_missing, js_fingerprint | JavaScript verification |
Common problems
| Symptom | What to check |
|---|---|
| The ad dashboard shows clicks, the tracker shows zero | Whether Safe Page click recording is off; the suppressed-hit counter |
| 100% of traffic on the safe page | Whether the geo database is installed (β β Geo databases); geo_unknown reasons in the click log |
| Live mobile users on the safe page | Reason ip2proxy_vpn_proxy β remove the VPN/proxy layer (it is a hard signal; low sensitivity will not cancel it) |
| Meta or Telegram reviewers reach the offer | Their networks are not flagged as data centers by ASN; a single range hit at medium sensitivity is only a soft signal. Raise the sensitivity or add a "Bot" filter to an intercepting stream |
Quick start: your first campaign
The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.
Read guide βDocsInstallation and updates
Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.
Read guide βDocsMigrating from Keitaro
Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β what transfers and what to check.
Read guide βDocsMigrating from Binom
Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.
Read guide βDocsFeature overview
Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.
Read guide βDocsCampaigns and streams
The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.
Read guide βDocsCloaking
Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.
Read guide βDocsBrowser check
How the JS check catches bots, VMs and emulators through contradictions in the browser environment.
Read guide βDocsLanding pages
Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β the complete reference.
Read guide βDocsPWA and Web Push
Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.
Read guide βDocsPWA Funnel
A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.
Read guide βDocsConversion popups
Show real conversion events as on-page popups: setup, triggers and placement.
Read guide βDocsSession recordings and heatmaps
Replay real visits and see click and scroll maps. Storage limits and privacy notes.
Read guide βDocsContent gallery
Central storage for icons, screenshots and creatives used across PWAs and landings.
Read guide βDocsCreatives library
Store creatives with subid tracking and test them across campaigns.
Read guide βDocsExternal PWA and Telegram channels
Publish PWAs to external domains and run Telegram channels as a traffic source.
Read guide βDocsPostbacks and conversions
Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.
Read guide βDocsCosts
Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β and how the revenue aggregator works.
Read guide βDocsPush and pop networks
Working with push and pop traffic sources: feeds, zone optimization and the zone killer.
Read guide βDocsFacebook / Meta
Cost import from Meta Ads and the Conversions API: server-side events with deduplication.
Read guide βDocsDolphin / Fbtool
Receive Facebook costs through the Dolphin (Fbtool) API in real time.
Read guide βDocsFB comment cleaner
Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.
Read guide βDocsTraffic sources and affiliate networks
Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.
Read guide βDocsReports, logs and metrics
The report builder, saved reports, click logs and every metric explained.
Read guide βDocsDomains and SSL
Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.
Read guide βDocsCloudflare
How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.
Read guide βDocsAdministration
Users, roles and permissions, security settings, geo databases, updates and system health.
Read guide βDocsTelegram bot
Manage the tracker from Telegram: stats, conversions and alerts in chat.
Read guide βDocsMCP: an AI assistant in the tracker
Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.
Read guide β