Advertising Suite Pro 2.0.0

---

What are the system requirements?

• XenForo 2.2.0 or higher
• PHP 8.0+ with cURL and JSON extensions
• MySQL or MariaDB
• Redis recommended for optimal caching (optional)

How do I install the add-on?
Upload the DEB/AmazonEbayAds folder to src/addons/ and install via ACP > Add-ons > Install/upgrade from archive. The add-on creates 18 database tables, 8 cron jobs and all required indexes automatically.

---

Which API keys do I need?

• Amazon Creators API — Credential ID + Secret (OAuth 2.0). Apply at Amazon Associates.
• Amazon Partner Tag — Your affiliate tracking tag for commission earnings.
• eBay Browse API — App ID + Cert ID via eBay Developers Program. Plus a Campaign ID from the eBay Partner Network.
• OpenAI API Key (optional) — For AI keyword extraction. Get one at platform.openai.com.

What if I don't have an OpenAI key?
The add-on works perfectly without OpenAI. It includes a built-in simple keyword extractor based on text frequency analysis. You can also set the mode to "AI + Simple Fallback" — it will use OpenAI when available and automatically fall back to simple extraction on API errors.

How can I test my API connections?
Go to ACP > Amazon - eBay ADS > Tools > Connection Test. You can test Amazon, eBay and OpenAI separately with one click. Results show status, response time and error details.

---

What ad types are available?

What display modes can I choose?
12 display modes: Product Cards, Product Cards v2 (with badges), List, Text Links, Banner, Leaderboard (728x90), Rectangle (300x250), Large Rectangle (336x280), Skyscraper (160x600), Billboard (970x250), Mobile Banner (320x50) and Half Page (300x600). Every ad can also be displayed as a virtual forum post with avatar, username and "Sponsored" tag.

Where can ads be placed?
12 positions including: After First/Middle/Last Post, Before/After Messages, Sidebar, Above/Below Content, Above/Below Thread List, Below Navigation, and In First/Last Post (inline).

---

What targeting options are available?

• Geo-Targeting — Filter by visitor country (200+ countries via IP detection)
• User Groups — Show/hide ads per XenForo user group
• User Criteria — Post count, membership duration and more
• Forum Exclusion — Exclude specific forums from ad display
• Page Criteria — Conditions based on node, style, controller etc.
• Weighted Rotation — Multiple ads per position with priority weight (1-100)

How does the AI keyword extraction work?
OpenAI GPT analyzes thread title and first post to extract purchase-relevant keywords with intent detection (Buy / Compare / Info). The system prompt is fully customizable. Keywords are cached per thread so the API is only called once per thread. You can also pin or blacklist keywords manually.

What is the Multi-Armed Bandit (MAB) ranking?
MAB is an intelligent product ranking algorithm. Products that perform well (high CTR) are shown more often, while a configurable exploration rate (epsilon) ensures new products also get tested. Products earn badges: "Bestseller" (CTR ≥ 8%) or "Trending" (CTR ≥ 5%).

---

How does click fraud protection work?
Two-layer system:

• Real-time — Every click is checked against IP block lists and browser fingerprints.
• Batch scan (cron) — Runs every 15 minutes. Detects burst patterns via IP, user ID and fingerprint. Automatically blocks suspicious IPs for a configurable duration (default: 24h).

Fraud alerts can be sent via email. All activity is logged in the Fraud Dashboard.

Can users disable ads?
Yes. Users with the toggleAds permission can disable product recommendations in their privacy settings. You can control this per user group.

Is there an ad blocker stealth mode?
Yes. When enabled, the add-on uses obfuscated URLs that prevent common ad blockers from detecting the ads.

---

What statistics are tracked?
Views, clicks, CTR, API calls (per service), revenue estimates, forum performance and fraud activity. All metrics are available per ad, per product, per forum and as daily aggregates. 6 CSV export types are available.

How does the weekly report work?
An automated email is sent weekly (configurable day, default: Monday) containing: total views, clicks, CTR, top-performing ads, revenue estimates and fraud statistics. Configure recipients in ACP > Settings > Email Alerts.

What are A/B tests?
You can create A/B tests to compare different ad configurations (e.g. display mode A vs. B). The system automatically splits traffic and tracks performance per variant. Results include statistical significance calculation.

---

How does the caching system work?
2-layer cache: Redis (L1, fast) + Database (L2, fallback). Products are cached per thread with configurable TTL (default: 7 days). A "stale fallback" mechanism serves expired cache data up to 24h to prevent empty results during API outages.

What are the automated background tasks?
8 cron jobs run automatically:

• Cache Warming (every 10 min) — Pre-loads global ads and top products
• Precompute (every 30 min) — Renews expiring product caches
• Fraud Scan (every 15 min) — Burst detection and auto-blocking
• Alert Check (hourly) — CTR thresholds and API error monitoring
• Stats Cleanup (configurable) — Maintains data retention
• Cache Cleanup (every 6h) — Removes expired entries
• Forum Stats (periodic) — Aggregates per-forum performance
• Weekly Report — Sends summary email

Does the add-on slow down my forum?
No. Lazy loading is supported — ads are loaded via AJAX after the page renders. Bot detection prevents unnecessary API calls for search engine crawlers. All product data is served from cache; API calls only happen on cache miss.

---

Ads are not showing — what should I check?

• Is the add-on enabled? (ACP > Settings > Main Toggle)
• Is at least one ad created and active? (ACP > Ads > List)
• Are API keys configured? (ACP > Settings)
• Does the user group have viewAds permission?
• Is the forum excluded from ad display?
• Run the Connection Test (ACP > Tools) to verify API access.

API calls are failing — what can I do?

• Check the Connection Test page for detailed error messages.
• Amazon uses automatic failover: Creators API → PA-API 5.0 with exponential backoff (30s → 600s).
• Verify your API credentials are correct and not expired.
• Check the Dashboard for API error rate statistics.
• Enable Debug Mode for detailed request/response logging.

How do I clear the cache?
Go to ACP > Amazon - eBay ADS > Tools > Cache Management. You can selectively clear: AI keyword cache, simple keyword cache, product cache, forum stats or all caches at once.

---