Amazon – eBay API ADS Light 1.0.1

---

What are the system requirements?

• XenForo 2.2.0 or higher
• PHP 8.0+ with cURL and JSON extensions
• MySQL or MariaDB

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

Can I upgrade to the Pro version later?
Yes. Install the ADS Pro add-on alongside the Light version. All existing settings and data are preserved. After verifying everything works, you can disable the Light version.

---

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.

Which marketplaces are supported?
Amazon: 21 marketplaces including DE, COM, CO.UK, FR, IT, ES, CA, AU, JP, IN, BR, NL, SE, PL, BE, MX, AE, SA, SG, TR, EG.
eBay: 8 marketplaces including DE, AT, CH, US, GB, FR, IT, ES.

How can I test my API connections?
Go to ACP > Amazon - eBay ADS > Tools > Connection Test. You can test Amazon and eBay 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, 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?
13 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?

• 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 keyword extraction work?
The built-in keyword extractor analyzes thread title and first post using text frequency analysis. Common words are filtered via configurable stop-word lists. You can set the maximum number of keywords (default: 3), add negative keywords and pin or blacklist specific terms. Keywords are cached per thread so extraction runs only once.

What are negative keywords and stop words?
Negative keywords are terms you want to exclude globally from product searches (e.g. "free", "crack"). Stop words are common words filtered during extraction (e.g. "the", "and", "with"). Both are fully configurable in ACP > Settings.

---

How does bot protection work?
The add-on detects 70+ known bot user-agent patterns and prevents unnecessary API calls for search engine crawlers. This saves API quota and avoids counting bot visits in your statistics.

Is there click tracking protection?
Yes. Every click is tracked per ad per day with unique click counting. The system records click data for statistics and detects duplicate clicks from the same visitor via IP tracking.

Can users disable ads?
Yes. Users with the toggleAds permission can disable product recommendations in their privacy settings. You control this per user group. There is also a stealth mode that uses obfuscated URLs to prevent ad blockers from detecting the ads.

---

What statistics are tracked?
Daily stats per ad: views, clicks, unique clicks, CTR, Amazon API calls, eBay API calls and error counts. Stats retention is configurable (default: 365 days). The ACP dashboard shows an overview with trends and top-performing ads.

How does the caching system work?
Database-backed caching with configurable TTL (default: 7 days). Products and keywords are cached per thread so API calls only happen on cache miss. A "stale fallback" mechanism serves expired cache data when APIs are unavailable. Optional AJAX lazy loading lets ads load asynchronously after the page renders. No Redis required.

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

• Cache Cleanup (every 6h) -- Removes expired product and keyword cache entries
• Stats Cleanup (daily at 3 AM) -- Removes statistics older than the configured retention period
• Precompute (every 2h) -- Pre-caches products for active threads to reduce API latency

---

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.

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

---

Want more power? ADS Pro includes:

• OpenAI keyword extraction with purchase-intent detection
• Anchor Text Ads -- auto-convert keywords to affiliate links
• Geo-Targeting -- 200+ countries via IP detection
• A/B testing & MAB ranking -- intelligent product optimization
• Advanced fraud detection -- auto-blocking, alerts, fraud dashboard
• Revenue tracking -- EPC, conversion rates, commission reports
• 6 CSV export types + automated weekly email reports
• Redis caching + global cache warming + debug mode

---