Instagram Sample Bot (Adaptive Scroll, Sample & Like)
🚀 Overview
The Instagram Sample Bot is a Tampermonkey userscript designed to automate your Instagram Browse experience. It intelligently scrolls your feed, detects potential "free sample" or "offer" posts from popular beauty brands, and can even auto-like posts related to cologne and beauty. The bot adapts its scrolling behavior based on whether the Instagram tab is in the foreground or background, ensuring a smooth experience without hogging resources.
✨ Features
- Adaptive Scrolling:
- Fluid Scrolling: Smooth, pixel-by-pixel scrolling when the Instagram tab is active (in the foreground).
- Jumpy Scrolling: Efficient, interval-based "jumping" to the bottom of the visible feed when the tab is in the background, saving CPU resources.
- Intelligent Sample Detection:
- Scans post captions and action buttons for keywords indicating free samples, trials, or offers.
- Provides a customizable "confidence threshold" to fine-tune detection sensitivity.
- New! Popular Brand Filter: Option to only alert for offers from a predefined list of popular beauty brands.
- Auto-Liking: Automatically likes posts that contain keywords related to cologne or general beauty products.
- Interactive Modals:
- When a potential sample offer is found, a custom, in-app modal appears, pausing the bot and allowing you to review the offer.
- The modal appears instantly, even if you switch back from a background tab, ensuring you don't miss offers.
- Customizable Settings: A dedicated settings modal allows you to adjust bot behavior, and your preferences are saved locally.
- In-App Help: A "Help" button in the settings modal provides quick troubleshooting tips.
- Userscript Update Button: Directly opens the script's raw source for easy updates via Tampermonkey.
- Fluid UI Animations: The main bot control panel appears smoothly when the page loads.
⚙️ Installation
To use this script, you need a userscript manager like Tampermonkey (recommended) or Violentmonkey.
- Install Tampermonkey:
- If you don't have it, install the Tampermonkey browser extension for your browser:
- Install the Userscript:
- Tampermonkey should automatically detect the script and prompt you to install it.
- Click "Install" or "Confirm" to add the script to Tampermonkey.
🎮 Usage
Once installed, a floating control panel will appear on the top-left of your Instagram feed.
- Start Bot: Click the "Start Bot" button to begin automated scrolling and post processing.
- Stop Bot: Click the "Stop Bot" button to pause all bot activities.
- Settings (⚙️ Icon): Click the gear icon in the top right of the control panel to open the settings modal.
Settings Explained:
- Fluid Scroll Speed (px/frame):
- Controls how many pixels the page scrolls per animation frame when the Instagram tab is active.
- Higher value = faster scrolling. (e.g., 4 is smooth, 10 is faster)
- Jumpy Scroll Interval (ms):
- Determines how often (in milliseconds) the page "jumps" to the bottom of the visible feed when the Instagram tab is in the background.
- Lower value = more frequent jumps (faster background scrolling). (e.g., 1000ms = 1 second)
- Enable Auto-Liking:
- A checkbox to toggle the automatic liking of posts containing cologne or beauty-related keywords.
- Default: ON
- Enable Sample Detection:
- A checkbox to toggle the detection of free sample/offer posts.
- Default: ON
- Sample Confidence Threshold:
- A numerical value (e.g., 1.5) that determines how confident the bot needs to be (based on detected keywords, action buttons, and sponsored status) before alerting you about a potential sample.
- Lower value = more alerts (potentially more false positives).
- Higher value = fewer alerts (more precise, but might miss some).
- Only Popular Beauty Brands:
- A checkbox. If enabled, the bot will only trigger sample offer alerts for posts that contain keywords from a predefined list of popular beauty brands, even if other sample criteria are met.
- Default: OFF
Saving Settings: After making changes in the settings modal, click "Save Settings" to apply them. Your settings are saved locally in your browser and will persist across sessions.
Help & Updates:
- Help Button: In the settings modal, click "Help" to open an in-app popup with common troubleshooting steps.
- Update Userscript Button: In the settings modal, click "Update Userscript" to open a new tab to the script's raw source. Tampermonkey will usually detect this and prompt you to update if a newer version is available.
⚠️ Troubleshooting
If the bot isn't working as expected, try these common solutions:
- Ensure Tampermonkey is active: Check your browser's Tampermonkey extension icon; it should be enabled and colored (usually green).
- Script Enabled: In the Tampermonkey dashboard, make sure 'Instagram Sample Bot' is toggled ON.
- Disable Ad Blockers: Ad blockers (e.g., uBlock Origin, AdBlock Plus) or privacy extensions can sometimes interfere with userscripts. Try disabling them for
instagram.com to see if it resolves the issue.
- Refresh Page: A simple page refresh (F5 or Ctrl+R / Cmd+R) can often resolve minor issues.
- Restart Bot: If the bot seems stuck, try clicking the 'Stop Bot' then 'Start Bot' button in the UI.
- Check Console for Errors: Open your browser's developer tools (usually by pressing F12 or Ctrl+Shift+I / Cmd+Option+I), go to the 'Console' tab, and look for any red error messages. These can provide clues.
- Update Script: Click 'Update Userscript' in the settings to check for the latest version.
- Clear Cache/Cookies: As a last resort, clearing browser cache and cookies for
instagram.com can sometimes fix persistent issues (note: this will log you out).
💡 Customization (Advanced)
For advanced users, you can directly edit the script in Tampermonkey to:
- Modify the
sampleKeywords and sampleActionTexts arrays to include more (or fewer) phrases for sample detection.
- Adjust the
cologneKeywords and beautyKeywords for auto-liking.
- Expand the
popularBeautyBrands list with your preferred brands.
📜 License
This project is licensed under the MIT License - see the LICENSE file for details.
