349 lines
10 KiB
Markdown
349 lines
10 KiB
Markdown
# Yupoo Product Image Downloader - Chrome Extension
|
|
|
|
A powerful Manifest V3 Chrome extension that automatically downloads all product images from Yupoo-style gallery pages, organizing them by product into individual folders.
|
|
|
|
## Features
|
|
|
|
✨ **Automatic Product Detection** - Scans gallery pages to find all product cards
|
|
🖼️ **Complete Image Collection** - Downloads all images from each product's detail page
|
|
📁 **Organized Downloads** - Creates one folder per product with numbered images
|
|
🔄 **Retry Logic** - Automatically retries failed downloads
|
|
⚙️ **Concurrency Control** - Limit simultaneous downloads to avoid overwhelming the server
|
|
🔀 **Deduplication** - Prevents downloading the same image twice in a session
|
|
📋 **Progress Tracking** - Real-time updates on scanning and downloading status
|
|
🛠️ **Easy Customization** - Simple selector configuration for different website structures
|
|
✅ **Rate Limiting** - Automatic delays between requests to be respectful to servers
|
|
|
|
## Installation
|
|
|
|
### 1. Prepare the Extension
|
|
|
|
Clone or download this directory to your computer. You should have these files:
|
|
```
|
|
yupoo-downloader/
|
|
├── manifest.json
|
|
├── popup.html
|
|
├── popup.js
|
|
├── styles.css
|
|
├── background.js
|
|
├── content.js
|
|
└── README.md
|
|
```
|
|
|
|
### 2. Load Extension in Chrome
|
|
|
|
1. Open Chrome and navigate to `chrome://extensions/`
|
|
2. Enable **Developer mode** (toggle in the top-right corner)
|
|
3. Click **"Load unpacked"**
|
|
4. Select the `yupoo-downloader` folder
|
|
5. The extension should now appear in your extensions list
|
|
6. Pin it to the toolbar for easy access (click the puzzle icon)
|
|
|
|
### 3. Grant Permissions
|
|
|
|
When you first use the extension, Chrome will ask for permissions:
|
|
- **Download files** - Needed to save images
|
|
- **Access current tab** - Needed to scan the page
|
|
- **Access all websites** - Needed to fetch product detail pages
|
|
|
|
Click "Allow" to proceed.
|
|
|
|
## Usage
|
|
|
|
### Basic Workflow
|
|
|
|
1. **Navigate to a Yupoo gallery page** with products you want to download
|
|
2. **Click the extension icon** in your toolbar
|
|
3. **Click "🔍 Scan Products"** - The extension will find all products on the current page
|
|
4. **Adjust settings** if needed:
|
|
- Set "Max Concurrent Downloads" (1-10, default 2)
|
|
5. **Click "⬇️ Download All"** - Downloads will begin automatically
|
|
6. **Monitor progress** in the activity log and statistics
|
|
7. **Downloads save to** your browser's default download folder
|
|
|
|
### Download Structure
|
|
|
|
Images are organized like this:
|
|
```
|
|
Downloads/
|
|
├── 3me10101430/
|
|
│ ├── 01.jpg
|
|
│ ├── 02.jpg
|
|
│ └── 03.jpg
|
|
├── 3mf10083295/
|
|
│ ├── 01.jpg
|
|
│ ├── 02.jpg
|
|
│ ├── 03.jpg
|
|
│ └── 04.jpg
|
|
└── product_001/
|
|
├── 01.jpg
|
|
└── 02.jpg
|
|
```
|
|
|
|
## Customization
|
|
|
|
The extension is designed to work with Yupoo and similar gallery sites, but websites vary in their HTML structure. You can customize the selectors to match your target website.
|
|
|
|
### Editing CSS Selectors
|
|
|
|
#### For Gallery Page (Finding Products)
|
|
|
|
Edit the `SELECTORS` object in **`content.js`** (around line 15):
|
|
|
|
```javascript
|
|
const SELECTORS = {
|
|
// The container div for each product tile/card
|
|
productCard: [
|
|
'div.item', // Try these in order
|
|
'div.product-item',
|
|
'div.product-card',
|
|
// Add more selectors that match your site
|
|
],
|
|
|
|
// The link that goes to the product detail page
|
|
productLink: [
|
|
'a[href*="/item/"]',
|
|
'a[href*="/product"]',
|
|
// Add more link selectors
|
|
],
|
|
|
|
// The visible product title/name
|
|
productTitle: [
|
|
'.product-name',
|
|
'.product-title',
|
|
'h3',
|
|
// Add more title selectors
|
|
],
|
|
};
|
|
```
|
|
|
|
**How to find the right selectors:**
|
|
1. Open the website in Chrome
|
|
2. Right-click on a product card → **"Inspect"**
|
|
3. Look at the HTML structure
|
|
4. Copy the class names or tag names you see
|
|
5. Add them to the corresponding array in `content.js`
|
|
|
|
#### For Detail Page (Finding Images)
|
|
|
|
Edit the `DETAIL_PAGE_SELECTORS` object in **`background.js`** (around line 30):
|
|
|
|
```javascript
|
|
const DETAIL_PAGE_SELECTORS = {
|
|
// Container that holds all product images
|
|
imageContainer: [
|
|
'div.photo-list',
|
|
'div.details-images',
|
|
'div.gallery',
|
|
// Add more container selectors
|
|
],
|
|
|
|
// Individual image elements
|
|
imageElements: [
|
|
'img.photo',
|
|
'img[class*="detail"]',
|
|
'img', // Fallback to all images
|
|
],
|
|
|
|
// Links to large images
|
|
imageLinks: [
|
|
'a[href*=".jpg"]',
|
|
'a[href*=".png"]',
|
|
],
|
|
};
|
|
```
|
|
|
|
### Testing Your Selectors
|
|
|
|
1. **For gallery page:**
|
|
- Open DevTools (F12) on a gallery page
|
|
- Open the Console tab
|
|
- Paste: `document.querySelectorAll('your-selector-here').length`
|
|
- Should return > 0 if selector is correct
|
|
|
|
2. **For detail page:**
|
|
- Open DevTools on a product detail page
|
|
- Try: `document.querySelectorAll('img').length`
|
|
- Should show number of images on that page
|
|
|
|
## Configuration Options
|
|
|
|
Edit the `CONFIG` object in **`background.js`** to adjust:
|
|
|
|
```javascript
|
|
const CONFIG = {
|
|
REQUEST_DELAY: 800, // ms between requests (lower = faster but more load on server)
|
|
RETRY_ATTEMPTS: 3, // How many times to retry failed downloads
|
|
RETRY_DELAY: 2000, // ms to wait before retrying
|
|
MAX_CONCURRENT_DOWNLOADS: 2, // Can be overridden in UI (1-10)
|
|
TIMEOUT: 30000, // ms before request times out
|
|
};
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "No products found"
|
|
|
|
1. Check the URL - make sure you're on a gallery page with product links
|
|
2. Verify selectors are correct:
|
|
- Right-click product card → Inspect
|
|
- Check if the selector matches the HTML
|
|
- Update `SELECTORS` in `content.js`
|
|
|
|
3. Check browser console (F12 → Console):
|
|
- Look for error messages
|
|
- Type: `document.querySelectorAll('your-selector').length`
|
|
- Should be > 0
|
|
|
|
### Downloads not starting
|
|
|
|
1. Verify Chrome permissions:
|
|
- Go to `chrome://extensions/`
|
|
- Find "Yupoo Downloader"
|
|
- Click "Details"
|
|
- Check "Permissions" tab
|
|
|
|
2. Check Chrome's download settings:
|
|
- Go to `chrome://settings/downloads`
|
|
- Verify download location is accessible
|
|
- Disable "Ask where to save each file" option
|
|
|
|
### Slow downloads
|
|
|
|
1. Increase `MAX_CONCURRENT_DOWNLOADS` in the popup (2-5 is usually good)
|
|
2. Decrease `REQUEST_DELAY` in `background.js` if the server allows
|
|
3. Check your internet connection
|
|
|
|
### Getting 404 errors for images
|
|
|
|
1. The image URLs might be dynamic or time-limited
|
|
2. Check detail page selector:
|
|
- Open a product page in your browser
|
|
- F12 → Inspect the images
|
|
- Update `DETAIL_PAGE_SELECTORS` in `background.js`
|
|
|
|
3. The site might require headers:
|
|
- Add custom headers to `fetchWithRetry()` in `background.js` if needed
|
|
|
|
### Extension stops working after Chrome update
|
|
|
|
1. Go to `chrome://extensions/`
|
|
2. Click "Update" or toggle off/on
|
|
3. If still broken, reload the extension:
|
|
- Remove it
|
|
- Reload this folder again
|
|
|
|
## How It Works
|
|
|
|
### 1. Content Script (`content.js`)
|
|
- Runs on the gallery page you're viewing
|
|
- Finds all product cards/links using CSS selectors
|
|
- Extracts product codes and detail page URLs
|
|
- Sends data to the background worker
|
|
|
|
### 2. Popup UI (`popup.html`, `popup.js`, `styles.css`)
|
|
- Shows "Scan Products" and "Download All" buttons
|
|
- Displays real-time progress
|
|
- Shows activity log
|
|
- Allows concurrency adjustment
|
|
|
|
### 3. Background Service Worker (`background.js`)
|
|
- Fetches each product's detail page
|
|
- Parses the HTML to find all images
|
|
- Downloads images using Chrome's downloads API
|
|
- Manages concurrency queue
|
|
- Handles retry logic and deduplication
|
|
- Tracks progress and errors
|
|
|
|
## Technical Details
|
|
|
|
### Manifest V3
|
|
- Uses service workers instead of background pages
|
|
- Latest Chrome extension security model
|
|
- Future-proof implementation
|
|
|
|
### Downloads API
|
|
- Uses `chrome.downloads.download()` with `filename` parameter
|
|
- Automatically creates product folders
|
|
- Works with browser's native download system
|
|
|
|
### Content Security Policy
|
|
- Safe from malicious scripts
|
|
- Follows Chrome extension best practices
|
|
- No external dependencies
|
|
|
|
### Rate Limiting
|
|
- 800ms delay between requests (configurable)
|
|
- Respects server resources
|
|
- Can be adjusted for faster downloads
|
|
|
|
## Performance Tips
|
|
|
|
1. **Reduce concurrency on slow connections** - Set to 1-2
|
|
2. **Increase concurrency on fast connections** - Set to 4-5 (but check server limits)
|
|
3. **Decrease REQUEST_DELAY for faster downloads** (but be respectful):
|
|
- 800ms (default) = 1.25 requests/sec
|
|
- 500ms = 2 requests/sec
|
|
- 300ms = 3.3 requests/sec
|
|
4. **Close other Chrome tabs** to free up bandwidth
|
|
5. **Disable VPN/proxy** if it's slowing things down
|
|
|
|
## File Organization
|
|
|
|
```
|
|
popup.html → User interface
|
|
popup.js → UI logic and user interaction
|
|
styles.css → Visual styling
|
|
|
|
content.js → Page scanning (runs on website)
|
|
background.js → Download orchestration (service worker)
|
|
manifest.json → Extension configuration
|
|
|
|
README.md → This file
|
|
```
|
|
|
|
## Browser Support
|
|
|
|
- Chrome 88+ (Manifest V3 support)
|
|
- Edge 88+ (also based on Chromium)
|
|
- Brave, Opera, and other Chromium-based browsers
|
|
|
|
## Known Limitations
|
|
|
|
- Does not work with infinite scroll pages (only scans initial visible products)
|
|
- Some sites with JavaScript-rendered images may not work
|
|
- Image watermarks are preserved as-is
|
|
- Login-required sites need active session
|
|
|
|
## Future Improvements
|
|
|
|
- [ ] Handle infinite scroll pages
|
|
- [ ] Support for lazy-loaded images
|
|
- [ ] Filter by product category
|
|
- [ ] Scheduling downloads
|
|
- [ ] Export metadata (product names, links)
|
|
- [ ] Resume incomplete downloads
|
|
- [ ] Image quality selection
|
|
|
|
## Legal Notice
|
|
|
|
This extension is for personal, non-commercial use only. Respect website ToS and copyright laws when downloading images. The author is not responsible for misuse.
|
|
|
|
## License
|
|
|
|
MIT License - feel free to modify and distribute
|
|
|
|
## Support
|
|
|
|
If you encounter issues:
|
|
|
|
1. Check the activity log in the popup for error messages
|
|
2. Open DevTools (F12) and check the Console tab
|
|
3. Verify CSS selectors for your target website
|
|
4. Try on a different gallery page to isolate the issue
|
|
5. Check that you have permission to download from the website
|
|
|
|
---
|
|
|
|
**Happy downloading! 📸**
|