ads-review — 广告斗篷流量过滤系统 Ad Cloaking Traffic Filter

🛡️ Advanced three-layer traffic filtering system for media buyers. Protects ad accounts on Facebook, Google, TikTok, and more.

📋 Table of Contents

• What is Ad Cloaking?
• How It Works
• Quick Start
• Configuration
• API Reference
• Detection Layers
• Supported Platforms
• FAQ
• Resources

🔍 What is Ad Cloaking?

Ad cloaking shows different content to ad platform reviewers vs real users. It protects your landing pages and ad accounts from bans.

Used by performance marketers running:

• Finance and insurance offers
• Health and supplement products
• Dropshipping and ecommerce
• Crypto and trading platforms

🏗️ How It Works

                    ┌─────────────────┐
                    │  Incoming Visit  │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Layer 1: IP    │
                    │  Bot Database   │
                    │  2000+ IPs      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Layer 2: FP    │
                    │  Browser Print  │
                    │  Canvas/WebGL   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Layer 3: AI    │
                    │  Behavior Score │
                    │  Mouse/Scroll   │
                    └────────┬────────┘
                             │
                   ┌─────────┴─────────┐
                   │                   │
              ┌────▼────┐        ┌────▼────┐
              │  HUMAN  │        │   BOT   │
              │ → Offer │        │ → Safe  │
              │   Page  │        │   Page  │
              └─────────┘        └─────────┘

Three-Layer Detection

Layer	Method	Accuracy	Speed
🔴 IP Detection	2,000+ bot IP database, updated daily	85%	<5ms
🟡 Browser Fingerprinting	Canvas, WebGL, WebRTC analysis	95%	<20ms
🟢 Behavior Analysis	Mouse movement, scroll, click timing	99.7%	<50ms

🚀 Quick Start

Installation

git clone https://github.com/chaanli/ads-review.git
cd ads-review
pip install -r requirements.txt
cp config.example.yaml config.yaml

Basic Usage

from cloaking import TrafficFilter

filter = TrafficFilter(config_path="config.yaml")

# Check a single request
result = filter.check_request(
    ip="203.0.113.42",
    user_agent="Mozilla/5.0 ...",
    headers=request.headers
)

if result.is_bot:
    return redirect("/safe-page")
else:
    return redirect("/offer-page")

Flask Integration

from flask import Flask, request, redirect
from cloaking import TrafficFilter

app = Flask(__name__)
filter = TrafficFilter()

@app.route("/landing")
def landing():
    result = filter.check_request(
        ip=request.remote_addr,
        user_agent=request.user_agent.string,
        headers=dict(request.headers)
    )
    if result.is_bot:
        return render_template("safe.html")
    return render_template("offer.html")

⚙️ Configuration

# config.yaml
detection:
  ip_check: true
  fingerprint_check: true
  behavior_check: true
  
  ip_database:
    update_interval: 86400  # Daily updates
    sources:
      - "internal"
      - "firehol"
      
  fingerprint:
    canvas: true
    webgl: true
    webrtc: true
    audio: true
    
  behavior:
    min_mouse_events: 3
    min_scroll_depth: 10  # percent
    min_time_on_page: 2   # seconds
    
security:
  hmac_key: "your-secret-key"
  token_ttl: 300  # seconds
  
pixel:
  facebook_capi:
    access_token: "YOUR_FB_TOKEN"
    pixel_id: "YOUR_PIXEL_ID"
  tiktok_events:
    access_token: "YOUR_TT_TOKEN"
    pixel_id: "YOUR_TT_PIXEL"
  google_enhanced:
    measurement_id: "G-XXXXXXX"
    api_secret: "YOUR_SECRET"

logging:
  level: "INFO"
  file: "logs/cloaking.log"

📡 API Reference

POST /api/v1/check

Check if a visitor is a bot.

{
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 ...",
  "referer": "https://facebook.com/ads",
  "fingerprint": {
    "canvas_hash": "a1b2c3d4",
    "webgl_hash": "e5f6g7h8",
    "screen": "1920x1080"
  }
}

Response:

{
  "is_bot": false,
  "score": 92,
  "layers": {
    "ip": {"passed": true, "detail": "clean IP"},
    "fingerprint": {"passed": true, "detail": "human browser"},
    "behavior": {"passed": true, "detail": "natural patterns"}
  },
  "action": "show_offer",
  "latency_ms": 34
}

GET /api/v1/stats

Get filtering statistics.

{
  "total_requests": 15420,
  "bots_blocked": 3210,
  "humans_passed": 12210,
  "accuracy": "99.7%",
  "avg_latency_ms": 28
}

🎯 Supported Platforms

Platform	CAPI Support	Pixel Tracking	Auto-Rules
Facebook Ads	✅	✅	✅
Google Ads	✅	✅	✅
TikTok Ads	✅	✅	✅
Microsoft Ads	❌	✅	✅
Twitter/X Ads	❌	✅	❌
Taboola	❌	✅	❌

🔐 Key Features

• 99.7%+ bot detection accuracy with three-layer system
• Server-side pixel CAPI support for Facebook, TikTok, Google
• VPN/Proxy/Tor/Datacenter traffic blocking
• HMAC-SHA256 tamper-proof security tokens
• < 50ms response time per request
• Real-time dashboard with live traffic visualization
• Auto-updating IP database from multiple threat feeds
• Webhook alerts for suspicious traffic spikes

❓ FAQ

Q: Will this get my ad account banned? A: Cloaking itself is against platform ToS. This tool is for traffic quality analysis and research purposes. Use responsibly.

Q: How often is the IP database updated? A: Daily by default, with real-time additions for newly detected bots.

Q: Does it work with CDNs like Cloudflare? A: Yes. We read CF-Connecting-IP and X-Forwarded-For headers to get the real visitor IP.

Q: What about mobile traffic? A: Full mobile support including in-app browser detection for Facebook, TikTok, and Instagram webviews.

📚 Resources

• 🎥 Video Tutorial
• 📝 Technical Blog (中文)
• 🌐 WuXiang Shield Official

📞 Contact

• 🤖 Support Bot: @java2018_bot
• 💬 Technical: @java2019
• 🌐 Website: wuxiangdun.com

---

License

MIT License - see LICENSE for details.