{"id":13513595,"url":"https://github.com/AdguardTeam/PopupBlocker","last_synced_at":"2025-03-31T02:32:34.326Z","repository":{"id":22842120,"uuid":"97457101","full_name":"AdguardTeam/PopupBlocker","owner":"AdguardTeam","description":"Popup blocking userscript","archived":false,"fork":false,"pushed_at":"2025-02-20T05:48:53.000Z","size":3371,"stargazers_count":364,"open_issues_count":28,"forks_count":33,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-03-25T08:03:44.637Z","etag":null,"topics":["adguard","open-source","popup-blocker","userscript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdguardTeam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-17T09:08:55.000Z","updated_at":"2025-03-22T23:55:41.000Z","dependencies_parsed_at":"2024-04-18T11:55:56.586Z","dependency_job_id":"1579b59b-5e59-42b0-9b0a-dcc9121eb5fa","html_url":"https://github.com/AdguardTeam/PopupBlocker","commit_stats":{"total_commits":326,"total_committers":22,"mean_commits":"14.818181818181818","dds":0.6073619631901841,"last_synced_commit":"771f40c85119193f529ec200735ecfecc579f563"},"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FPopupBlocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FPopupBlocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FPopupBlocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FPopupBlocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdguardTeam","download_url":"https://codeload.github.com/AdguardTeam/PopupBlocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246407211,"owners_count":20772089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adguard","open-source","popup-blocker","userscript"],"created_at":"2024-08-01T05:00:32.309Z","updated_at":"2025-03-31T02:32:34.310Z","avatar_url":"https://github.com/AdguardTeam.png","language":"TypeScript","funding_links":[],"categories":["Userscripts","Web browsers"],"sub_categories":["Portable","Self-hosted VPNs","Userscripts"],"readme":"# Popup Blocker by AdGuard\n\n## Summary:\n\nPopup Blocker by AdGuard is a userscript that blocks all unwanted pop-up windows in different browsers.\n\n## Key features:\n\n- Cross-browser support\n\nWorks in Chrome, Firefox, Edge, Safari, IE10+ etc, basically in any browser that supports userscript managers. Exceptions are some of the oldest browsers that do not support the API we use, the script may not be fully functional there.\n\n- Advanced pop-up detection\n\nPopup Blocker doesn't apply the _filtering rules_ approach to pop-up detection. Instead, it adds an additional layer on top of browser's native APIs that are used to create pop-ups. This way, these APIs can only be called when caused by a manual input, and not by pop-up/pop-under scripts. That allows to block pop-ups even on websites that try to bypass regular ad blockers by using WebRTC or varying the ad servers.\n\n- Restores the expected click behavior\n\nSelf-explanatory but important: if a click would cause a pop-up to show, not only the pop-up is blocked, but also the initial click is processed as it would be without the pop-up.\n\n- Invisible to other scripts\n\nOther scripts on the page can not detect that Popup Blocker is being used, other than by actually trying to open a pop-up. This prevents any possible circumvention of Popup Blocker.\n\n## Installation\n\n- **Current release version**: https://userscripts.adtidy.org/release/popup-blocker/2.5/popupblocker.user.js\n\n- Current beta version: https://userscripts.adtidy.org/beta/popup-blocker/2.5/popupblocker.user.js\n\nPopup Blocker is being developed by the same team that develops AdGuard, and AdGuard for Windows can serve as a userscript manager. If you are an AdGuard user, go to Settings – Extensions – Add Extension and enter the desired Popup Blocker .js file URL there. This way you can use it in literally any browser.\n\nOn the other hand, Popup Blocker is an independent project, you can use it with any other userscript manager like Greasemonkey, Tampermonkey or Violentmonkey. Make sure one of them is installed in your browser to be able to use the Popup Blocker (just enter the script URL into the address bar, it will be automatically detected by the manager).\n\n## Options page\n\nYou can manage a list of allowlisted domains and silenced domain on a dedicated options page:\n* **Current release version**: https://popupblocker.adguard.com/release/v1\n* Current beta version: https://popupblocker.adguard.com/beta/v1\n\n## Reporting a bug\n\nTo report a bug, go to [this page](https://github.com/AdguardTeam/PopupBlocker/issues) and create a new issue.\n\n## Translation\n\nYou can help us with translating Popup Blocker into other languages! Our project on [Crowdin](https://adguard.com/kb/miscellaneous/contribute/translate/program/) is open for public contributions.\n\n## Development build\n\nDevelopment builds have logging enabled and overrides significantly more browser apis to introspect behavior of popup/popunder script. It is not suitable for normal usage.\n\nUnit test for dev build is [here](https://popupblocker.adguard.com/release/v1/test/).\n\n## How to build\n\nTo build the project, follow these steps:\n\nInstall local dependencies by running the following command in the terminal:\n\n```\nyarn install\n```\n\nTo build, run the following command in the terminal:\n\n```\n$ NODE_ENV=\u003cchannel\u003e ts-node tasks/builder --target=\u003ctarget\u003e\n```\n\nReplace `channel` with the desired channel, which can be `dev`, `beta`, or `release`. Also, replace `target` with the desired build target, which can be\n\n- `userscript` – build userscript for a specified channel;\n- `options` – build options page, which is a standalone page, that provides the user with convenient way of managing allowed and silenced websites;\n- `tests` – build tests;\n- `bundle` – build and bundle all of the above for a specified channel.\n\nAlternatively, you can run the following commands in a minimist style:\n\n```\nyarn userscript-\u003cchannel\u003e\nyarn options-page\nyarn tests\nyarn bundle:dev\nyarn bundle:beta\nyarn bundle:release\n```\n\nIf you are building for development, note that the output will not be minified and will contain logs in the browser console.\n\nBeta and release builds will be minified, and all logging codes will be stripped out.\n\n## How to debug the options page\n\nBuild using the options page, go to the build folder via `cd` command and run local server of you choice\n\n```\nyarn options-page\n```\n\nModify `isOptionsPage` at `option-init.ts` to allow specific address and port.\nAfter that, ensure, that userscript (for example, in AG) contains this address and port too.\n\nTo see the options page, ensure, that AG filters your debug page.\n\n## How to test\n\nAn easy way to test the script is to visit http://code.ptcong.com/better-js-popunder-script/\n\nJust click anywhere on that page to get a popunder, or use specific links to get popup/popunder/tabup/etc.\n\nExpected behavior: new windows get blocked with a notification in the top right corner.\n\n## How to deploy options page\n\nOptions page is deployed via GitHub Pages with a manual actions `Deploy popup blocker beta` and `Deploy popup blocker release` for `beta` and `release` versions respectively.\n\n## Exclusions Meta Information\n\n`AdGuard` exclusion websites are manually added to the meta information in the `/exclusions.ts` file. For `TinyShield` websites, the process is automated using a script. Here is how it works:\n\n1. **Update TinyShield Websites**:\n\n- Run the script to update the `TinyShield` websites:\n\n  ```bash\n  yarn update-tinyshield-websites\n  ```\n\n- This script downloads the latest `TinyShield` websites from the TinyShield Meta file at `https://raw.githubusercontent.com/List-KR/tinyShield/refs/heads/main/sources/banner.txt`.\n\n- The script updates the `/tinyShieldWebsites.json` file with the latest `TinyShield` websites.\n\n1. **Build Process**:\n\n- During the build process, the websites listed in `tasks/tinyShieldWebsites.json` and in `/exclusions.ts` are automatically added to the meta information with `//@exclude` prefix.\n\nWe exclude TinyShield websites in the metadata due to errors. For more details, refer to [this issue](https://github.com/List-KR/tinyShield/issues/1).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAdguardTeam%2FPopupBlocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAdguardTeam%2FPopupBlocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAdguardTeam%2FPopupBlocker/lists"}