# Changelog of 1688.com Wholesale Scraper — Pay Per Product, No Subscription (`prodiger/1688-scraper`) Actor

- **URL**: https://apify.com/prodiger/1688-scraper/changelog.md
- **Full Actor documentation**: https://apify.com/prodiger/1688-scraper.md

## Changelog

All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

### \[0.1] — 2026-04-29

#### Added

- Initial release. 1688.com mobile-search scraper.
- Inputs: `keyword` (single search), `searchArray` (multi-search), per-search filters (`maxPages`, `priceStart`, `priceEnd`, `sortType`, `descendOrder`, `quantityBegin`, `searchType`).
- Output: 22 fields per product card via cheerio DOM scraping of `m.1688.com/offer_search/-{HEX}.html` — title, price, sales count, return rate, seller years, location (city), image, tags, factory/verified flags. Fields without mobile-DOM coverage (`shop_id`, `shop_url`, `seller`, `seller_type`, `price_tiers`) are emitted as empty strings / empty arrays for schema stability; detail-page enrichment is deferred.
- Pure HTTP via Crawlee `HttpCrawler` (no headless browser, no captcha solving).
- Pay-per-event pricing (`actor_start` + `product`) at premium tiers configured in Apify Console (see `docs/1688-scraper-runbook.md`).
- RESIDENTIAL CN-region proxy default with explicit guard warnings for non-RESIDENTIAL or non-CN configurations — 1688's mobile route only SSRs offer cards for CN-region residential traffic.
- Reactive 429 backoff; session retirement on slider-captcha challenge HTML detection.
- iPhone Safari User-Agent + zh-CN headers + `https://m.1688.com/` referer required to bypass the login wall.
- Mobile route hex-encodes the keyword in the URL path: `/offer_search/-{HEX(utf8(keyword))}.html`. Without this prefix the route 302s to the login page.
- Charge-event ordering: `product` charges only fire after a successful `Actor.pushData()`.

#### Architecture decisions

- 1688's PC search (`s.1688.com`) is fully client-rendered and login-walled outside CN; it is unscrapable without paid captcha-solving infrastructure or rotating authenticated accounts. The mobile route (`m.1688.com`) keeps SSR offer data for CN traffic, so the actor targets the mobile route exclusively.
- Decision is recorded in detail in `docs/brainstorms/1688-scraper-requirements.md`.