QCLean is a browser extension that removes ads, suggested pages, and posts from Facebook news feeds for various browsers. It has over 30,000 users worldwide and has been available since 2013. It works by using content scripts to select and remove certain elements from pages as they load. Over time, it has improved how it identifies ads by observing changes to page structure and using APIs to update classified elements. It is open source and available on Chrome and Firefox extension stores.

1. How QCLean works?
Introduction to Browser Extensions
@qcl
Code & Beer 2015.03.06

3. What is QCLean?
● A browser extension/add-on that removing
ads, suggested pages and posts on
Facebook news feed for Chrome, Firefox,
Safari, Opera and IE users.
● http://qcl.github.io/QCLean/

4. History
● Since 2013.02.28 (2 years old!)
● Popular add-on (Firefox) 2013.04.06
● Popular extension (Chrome) 2013.08.21

5. Overview
● Support 5 browsers
○ Chrome/Chromium, Firefox, Safari, Opera, IE
● More than 30,000 users over the world.
○ GC ~30,000
○ FF ~8,500
● Donated mainly by Firefox user!
○ Receive about $24
○ Donate NOW!

6. Overview
● Rating
○ ★★★★★ 4.5/5.0 Chrome
○ ★★★★ 4.0/5.0 Firefox
○ ★★★★ 4.0/5.0 Opera
● Operating System
○ 93% Windows
● Languages
○ Chrome 74% zh-tw
○ Firefox 53% en-us

7. About icon

8. Extension/Add-on v.s. Plugin
● Extension/Add-on
○ Extensions are small software programs that can
modify and enhance the functionality of the browser.
You write them using web technologies such as
HTML, JavaScript, and CSS. (Chrome)
● Plugin
○ Plugins are shared libraries that users can install to
display content that the application itself can't display
natively. (MDN)

9. Extensions
● Written by HTML/JavaScript/CSS
● chrome://extensions
● about://addons

10. Plugins
● Written by C/C++, depend on platform
○ NPAPI, NaCl (Chrome)
● chrome://plugins
● about://plugins

11. Plugins
● NPAPI
○ PCManX GTK2 on Chrome using NPAPI
@qcl, @JeromeWu, 2010

12. Extension developing 101
● Firefox
○ http://blog.qcl.tw/2013/08/sdkfirefox-add-on.html
● Chrome
○ Create a file named manifest.json
○ Open your Chrome, go to chrome://extensions
○ Click Developer Mode
○ Then import the folder which contains manifest.json

13. manifest.json
{
“manifest_version” : 2,
“name” : “extension_name”,
“version” : “version_string” ,
“description” : “extension_description”
...
}
● https://developer.chrome.com/extensions/manifest

14. manifest.json (QCLean)

15. Background
background: {
“script”:[“background.js”]
}
● It exists for the lifetime of your extension.
● Only ONE instance of it at a time.
● It can be used to manage some task or state.

16. Permissions
● permissions: [“tabs”]
● https://developer.chrome.com/extensions/declare_permissions
● https://developer.chrome.com/extensions/permission_warnings

17. Content Scripts
“content_scripts” : [
{
“matches”: [match patterns],
“css”: [“kerker.css”],
“js”: [“haha.js”],
“run_at”: “document_start”
}
]
● https://developer.chrome.com/extensions/content_scripts

18. Content Scripts
● Content scripts are JS that run in the content
of web page
● Can not use chrome.* API of extension,
i18n, runtime, storage
● Can not use functions defined by extension
page
● Can not use functions defined by web page
or other content script
● Match Pattern
○ https://developer.chrome.com/extensions/match_patterns

19. Content Script
● run_at
○ doucment_start
■ Before any other DOM is constructed or any
other script is run
○ doucment_end
■ After DOM is complete, but before subresources
like images and frames have loaded
○ doucment_idle (defualt)
■ After window.onload

20. Remove Suggested Pages&Posts
● First commit of QCLean

21. Remove Suggested Pages&Posts
● What will happen when all posts on your
newsfeed use the same class name?
○ All the posts will be removed :p
● Or the class name used by other elements
on the page
○ Those elements will be removed, too :p
● Or you can not get Ad elements directly
● Select elements that you can identify then try
to do something.

22. Remove Suggested Pages&Posts
● Select some special elements, try to find the
Ad block, then remove it.
● If Facebook changes the structure of page,
this method will GG
● It will run once when page did load. (run_at)

23. Facebook infinite scrolling
● When to run the script?
○ document_start? document_end? document_idle?
○ setInterval?
● When you scrolls down the page, it will load
more and more post (and Ads)
● Need to find a trigger point to remove Ads!

24. Override the prototype of DOM
● Check Ads when appending new elements
into the page.
● Override the prototype of some DOM
○ HTMLDivElement.prototype.appendChild
○ HTMLUlElement.prototype.appendChild

25. Prevent Requesting Ads
● Check AJAX requests by overriding
XMLHttpRequest.prototype

26. Content Scripts
● Can not override the prototype of HTML
DOM in web page (directly)
● But we can add new element into web page.

27. Override prototype is DANGEROUS

28. MutationObserver
● QCLean-Chrome-Experiment
https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver

29. ClassName changed frequently
● Static classnames list is not enough
● I want to build a API for user, it can update
classnames list.

30. Some QCLean API
● Story API
○ http://qcl.github.io/QCLean/api/story.js
● Line Tagging API
○ http://qcl.github.io/QCLean/api/lineTagging.js
● XHR Cross-origin request issue
● Content security policy issue

31. Content Security Policy
“content_security_policy” : “policy”
● It can not be show on permission warning
● CSP works as a black/whitelisting mechanism
for resources loaded or executed by your
extension.
https://developer.chrome.com/extensions/contentSecurityPolicy
http://www.html5rocks.com/en/tutorials/security/content-security-policy/

32. Distribute Extensions
Cost Review Publish
Chrome $5 no directly publish
Firefox free optional directly publish
Opera free required after review
Safari free required unknow*

33. Extension source
● Web Store / Addon Center
○ You don’t need to mantain a update server
● Mantain your own update server

34. Update URL
update_url : “http://qcl.github.io/QCLean/chrome_update.xml”
● Packaging your extension (with key)
○ extension.crx
● Write update XML
○ https://developer.chrome.com/extensions/autoupdate

35. How others write extensions?
● Install the extension
● Get the extension’s ID (chrome://extensions)
● Go to
○ ~/Library/Application Support/Google/Chrome/Default/Extensions (mac)

36. QCLean
https://github.com/qcl/QCLean