============================================================
  ADS LIBRARY HUNTER  —  HOW TO USE
  Find & score winning products on the Facebook Ads Library
============================================================

Thanks for installing Ads Library Hunter! This guide gets you
from zero to your first scored product list in a few minutes.


------------------------------------------------------------
1. INSTALL (Developer mode / Load unpacked)
------------------------------------------------------------
1) Unzip this folder somewhere permanent
   (avoid the Downloads folder - it is easy to clear).
2) Open Chrome and go to:   chrome://extensions
3) Turn ON "Developer mode" (top-right corner).
4) Click "Load unpacked" and select THIS folder.
5) An orange magnifier icon appears in the toolbar.
   Click the puzzle-piece icon and PIN it for easy access.

Tip: after any update, return to chrome://extensions and click
the Reload (circular arrow) button on the extension card.


------------------------------------------------------------
2. OPEN THE PANEL
------------------------------------------------------------
Click the orange magnifier icon. The extension opens the
Facebook Ads Library and shows the control panel on the right.

You must be LOGGED IN to Facebook, and the panel only appears
on  facebook.com/ads/library .

Switch language (EN / VI / ZH / ES) from the dropdown at the
top of the panel.


------------------------------------------------------------
3. SCAN PRODUCTS (main workflow)
------------------------------------------------------------
1) KEYWORDS  - type one or more, separated by commas
               e.g.  posture corrector, neck massager
2) COUNTRIES - 2-letter codes separated by commas (US, GB, DE)
               or type  ALL  to scan globally.
3) PAGES     - how many pages to scan (start with 20).
4) Click  "Silent scan (API)".  A progress bar runs while it
   pages through Facebook's API in the background.

Each result row shows a SCORE on the right. Click a row to open
the details: download the video/image, copy the ad copy, view
the landing page and competitor targeting.

If the silent scan returns nothing, use the "Scrape page" button
instead, then scroll the page to gather more ads.


------------------------------------------------------------
4. FILTERS (the "chips")
------------------------------------------------------------
Turn these on to keep only the products worth your time:
  - Active only        : only ads currently running
  - Variations >=      : many variations = scaling (try >= 3)
  - Days running >=    : older = more likely profitable (>= 14)
  - Score >=           : keep only high scores (try >= 60)
  - Exclude scanned    : skip pages seen in a previous scan

Recommended winning combo:
  Active only + Variations >= 3 + Days running >= 14 + Score >= 70


------------------------------------------------------------
5. THE SCORE (0 - 100)
------------------------------------------------------------
Each product is scored on real "scaling" signals:
  GREEN  80-100 : strong winning signal - research these first
  GOLD   60-79  : promising - review more before deciding
  GRAY   < 60   : weak or too new - usually skip

The score is a SIGNAL, not a guarantee. Always check the
creative, price, market saturation and supplier yourself.


------------------------------------------------------------
6. SPY ON COMPETITORS  &  EXPORT
------------------------------------------------------------
- "Group by competitor" : groups results by advertiser/page so
  you can see who is pushing the most ads in a niche.
- "Export CSV"          : downloads all results (name, score,
  variations, days, links) for Excel / Google Sheets.

Note: Facebook only publishes targeting data for ads running in
the EU. To inspect targeting, scan EU countries (DE, FR, ES...)
or use ALL.


------------------------------------------------------------
7. LICENSE / FREE TRIAL
------------------------------------------------------------
- New users get a full 30-day trial - no key required.
- To unlock unlimited access, click "Enter key" at the top of
  the panel, paste your key and click Activate. Status becomes PRO.
- Need a key? Contact us on Telegram (see below).


------------------------------------------------------------
8. TROUBLESHOOTING
------------------------------------------------------------
* I clicked the icon but see no panel
  -> Make sure you are on facebook.com/ads/library and logged in.
     Reload the extension at chrome://extensions, then retry.

* "Service worker registration failed" on chrome://extensions
  -> Click Reload on the extension card. If it persists, remove
     the extension and Load unpacked again from this folder.
     Make sure ALL files in this folder were unzipped together
     (do not move or delete any .js file).

* Silent scan returns empty
  -> Open the Ads Library once and search anything so the
     extension learns Facebook's latest internal ID, then retry.
     Or lower the page count, or use "Scrape page".

* Scanning stops / gets rate-limited
  -> Scan fewer pages at a time and wait a few minutes.

* DOM scrape misreads ads
  -> Set your Facebook language to English (US).


------------------------------------------------------------
9. PRIVACY & DISCLAIMER
------------------------------------------------------------
- Scan results and settings are stored locally in your browser
  (chrome.storage.local). The extension only contacts the server
  to validate a license key.
- The API mode uses YOUR own logged-in session cookie via
  same-origin requests to facebook.com. Your cookie is never
  stored or sent anywhere else.
- This tool reads only PUBLIC data on the Ads Library, for
  personal product research. Please follow Facebook's Terms.
- Ads Library Hunter is an INDEPENDENT tool. It is NOT affiliated
  with, sponsored by, or endorsed by Meta. "Facebook" and "Meta"
  are trademarks of Meta Platforms, Inc.


------------------------------------------------------------
  SUPPORT
------------------------------------------------------------
  Telegram : <https://t.me/adslibraryhunter>
  Website  : <https://adshunter.pages.dev/#how>

  (c) 2026 Ads Library Hunter. All rights reserved.
============================================================
