v0.0.1

nicjansma · Mar 22, 2014 · 1ce4569 · 1ce4569
commit 1ce4569
Show file tree

Hide file tree

Showing 15 changed files with 3,040 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+/node_modules
+.project
+.settings/
+npm-debug.log
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -0,0 +1,57 @@
+module.exports = function(grunt) {
+    // Project configuration.
+    grunt.initConfig({
+        pkg: grunt.file.readJSON('package.json'),
+        uglify: {
+            options: {
+                banner: '/*! <%= pkg.name %> v<%= pkg.version %> */\n'
+            },
+            build: {
+                src: 'src/<%= pkg.name %>.js',
+                dest: 'dist/<%= pkg.name %>.min.js'
+            }
+        },
+        jshint: {
+            files: [ 'src/**/*.js', 'test/**/*.js' ],
+            options: {
+                bitwise: true, 
+                camelcase: true, 
+                curly: true, 
+                eqeqeq: true, 
+                forin: true, 
+                immed: true,
+                indent: 4, 
+                latedef: true, 
+                newcap: true, 
+                noempty: true, 
+                nonew: true, 
+                quotmark: true, 
+                jquery: true,
+                undef: true, 
+                unused: true, 
+                strict: true, 
+                trailing: true, 
+                browser: true, 
+                node: true, 
+                white: false,
+                globals: {
+                    define: true,
+                    window: true
+                }
+            }
+        }
+    });
+
+    //
+    // Plugins
+    //
+    grunt.loadNpmTasks('grunt-contrib-uglify');
+    grunt.loadNpmTasks('grunt-contrib-jshint');
+
+    //
+    // Tasks
+    //
+    grunt.registerTask('default', ['jshint', 'uglify']);
+    grunt.registerTask('lint', ['uglify']);
+    grunt.registerTask('all', ['nodeunit', 'jshint', 'uglify']);
+};
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,20 @@
+Copyright (c) 2014 Nic Jansma, http://nicj.net
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,208 @@
+# adblock-detector.js
+
+v0.0.1
+
+Copyright 2014 Nic Jansma
+
+[http://nicj.net](http://nicj.net)
+
+Licensed under the MIT license
+
+## Introduction
+
+`adblock-detector.js` attempts to detect if the advertising on your site is being blocked by software in the visitor's
+browser such as [Adblock Plus](https://adblockplus.org/).
+
+As of March 2014, this library is able to detect Google AdSense ads being blocked on Windows machines when
+[Adblock Plus](https://adblockplus.org/) is installed for the following browsers:
+
+* Internet Explorer 11
+* Firefox 27
+* Chrome 33
+
+`adblock-detector.js` *may* work in other environments, such as other browsers, browser versions, ad publishers
+and ad-blockers, but it has not (yet) been thoroughly tested elsewhere.  If you have experience with this library
+working in other environments, please  update this README.  Validating and updating `adblock-detector.js` to work
+in new environments will be an ongoing process.
+
+**NOTE:** This library is intended to be used to monitor your ad-blocker rate, or to replace blocked ads with
+other *non-annoying* content such as a gentle text suggestion to donate to the site if the visitor feels so inclined.
+Replacing blocked ads with other ads will likely upset your customers.
+
+You can see this script in action on [sarna.net](http://www.sarna.net), which gives a gentle *Please donate Bitcoins
+if you enjoy this site* message to the visitor if ads are blocked.  The visitor is also given the opportunity to
+hide the message for a year if they do not want to continue seeing it.
+
+## Download
+
+Releases are available for download from [GitHub](https://github.com/nicjansma/adblock-detector.js).
+
+__Development:__ [`src/adblock-detector.js`](https://github.com/nicjansma/adblock-detector.js/raw/master/src/adblock-detector.js)
+    - ~3.7kb
+
+__Production:__ [`dist/adblock-detector.min.js`](https://github.com/nicjansma/adblock-detector.js/raw/master/dist/adblock-detector.min.js)
+    - ~500b (minified / gzipped)
+
+`adblock-detector.js` is also available via [bower](http://bower.io/). You can install using:
+
+    bower install adblock-detector
+
+## Usage
+
+***NOTE:*** `adblock-detector.js` requires jQuery.
+
+Include `adblock-detector.js` in your HTML:
+
+```html
+<script type="text/javascript" src="jquery.js"></script>
+<script type="text/javascript" src="adblock-detector.min.js"></script>
+```
+
+Once imported, a global `AdblockDetector` element is added to the top-level window object (if not using
+[AMD](https://github.com/amdjs/amdjs-api/wiki/AMD)).
+
+Otherwise, `adblock-detector.js` can be used as an AMD / [require.js](http://requirejs.org) module.
+
+To detect if ads were blocked on the page, you can either use `AdblockDetector.hasAdsBlocked(element)` to detect if an
+individual **ad container** has been blocked, or use `AdblockDetector.detect(...)`, which waits for the `document.ready`
+event and then checks all of the ads on the page to see if any have been blocked.
+
+To help `adblock-detector.js` determine if ads are being blocked, all of your ads should be wrapped up in a
+**container element**, such as the following:
+
+```html
+    <div class='ad-container'>
+        <script type='text/javascript' src='http://pagead2.googlesyndication.com/pagead/show_ads.js'></script>
+    </div>
+```
+
+This container element helps `AdblockDetector` find where ads should have appeared in the DOM so it can inspect them.
+
+## Examples
+
+Two complete examples are provided in the `examples/` folder:
+
+* `analytics.html` - Uses Google Analytics (Universal) to monitor which users have an ad-blocker installed by setting an Google Analytics Dimension.
+
+* `please-donate.html` - Gives a gentle plea to users who have an ad-blocker installed, requesting Bitcoins if they
+    enjoy the site.  Also gives an option to hide the nag message if the user doesn't want to see it anymore.
+
+More examples:
+
+### Determing if a single ad has been blocked
+
+After setting up your ad in a `<div class='.ad-container'>`, you could check to see if it has been blocked via the
+`hasAdsBlocked()` function.  You should wait a small period after the `document.ready` event for ads to be asynchronously
+loaded before checking (for example, 500 to 2,500 ms).
+
+```html
+    <div class='ad-container' id='ad1'>
+        <script type='text/javascript' src='http://pagead2.googlesyndication.com/pagead/show_ads.js'></script>
+    </div>
+    <script>
+        $(function() {
+            setTimeout(function() {
+                alert('Ads blocked? ' + AdblockDetector.hasAdsBlocked($('#ad1'));
+            }, 3000);
+        });
+    </script>
+```
+### Determing if a any ads have been blocked
+
+After setting up your ads in `<div class='.ad-container'>`, you can check to see if any ads have been blocked via the
+`detect()` function:
+
+```html
+    <div class='ad-container' id='ad1'>
+        <script type='text/javascript' src='http://pagead2.googlesyndication.com/pagead/show_ads.js'></script>
+    </div>
+    <script>
+        AdblockDetector.detect({
+            timeout: 3000,
+            selector: '.ad-container',
+            blocked: function(element) {
+                alert(element + ' had its ads blocked');
+            },
+            complete: function(adCount, adsBlockedCount) {
+                alert(adsBlockedCount + ' ads blocked out of ' + adCount);
+            }
+        });
+    </script>
+```
+
+### Replacing an ad with your own content
+
+After detecting that your ads have been blocked via the `detect()` function, you can replace the ad content with
+something else.  For example, you could inject a gentle **Please Donate** text suggestion instead.
+
+```html
+    <div class='ad-container' id='ad1'>
+        <script type='text/javascript' src='http://pagead2.googlesyndication.com/pagead/show_ads.js'></script>
+    </div>
+    <script>
+        AdblockDetector.detect({
+            timeout: 3000,
+            selector: '.ad-container',
+            blocked: function(element) {
+                $(element).html('Please donate Bitcoins to us at <a href="bitcoin:1PVhFgNmTNmHsCEdNA2HHH18pFNiaVLUa9">' +
+                    '1PVhFgNmTNmHsCEdNA2HHH18pFNiaVLUa9</a> if you enjoy this site.');
+            }
+        });
+    </script>
+```
+
+## Reference
+
+### `AdblockDetector.hasAdsBlocked(element)`
+
+Determines if ads are being blocked in the target element (ad container).
+
+#### Params:
+
+* `element` HTMLElement ad container to check (`HTMLElement`)
+
+#### Returns:
+
+`boolean` True if the matching ad container had its ad blocked
+
+### `AdblockDetector.detect(opts)`
+
+Waits for `document.ready`, then looks for ads matching a selector to see if any ads were blocked.
+
+#### Params:
+
+* `opts` Options (`object`)
+
+    * `opts.timeout` Timeout before document is checked (`number`, default: `3000`)
+
+    * `opts.selector` jQuery selector of ad containers (`string`, default: `'.ad-container'`)
+
+    * `opts.blocked` Function that fires when a container's ads have been blocked (`function(element)`, default: `null`)
+
+    * `opts.complete` Function that fires after all ads have been checked for being blocked
+        (`function(adCount, adsBlockedCount)`, default: `null`)
+        * `adCount` is the number of ads that matched the `selector`
+        * `adsBlockedCount` is the number of ads that were blocked
+
+## Tests
+
+`adblock-detector.js` tests are found in the `test/` directory, and must be run in your web browser:
+
+    test/test.html
+
+To run the test, you need a valid [Google AdSense](http://www.google.com/adsense/start/) publisher account.  Once
+you have an account that can serve ads, change the constant in test.html that specifies which AdSense account to use:
+
+```js
+//
+// NOTE: Modify this with a valid client ID to test
+//
+var PUB_CLIENT = "pub-123xyz";
+```
+
+The tests are run manually.  You should load the `test.html` in your browser of choice and select either the
+*Run Tests w/ NO Ad Blocker* or *Run Tests w/ Ad Blocker* buttons depending on your situation.
+
+## Version History
+
+* v0.0.1 - 2014-03-22: Initial version
diff --git a/bower.json b/bower.json
@@ -0,0 +1,28 @@
+{
+  "name": "adblock-detector",
+  "version": "0.0.1",
+  "homepage": "https://github.com/nicjansma/adblock-detector.js",
+  "authors": [
+    "Nic Jansma <nic@nicj.net>"
+  ],
+  "description": "Adblock Detector",
+  "main": "src/adblock-detector.js",
+  "keywords": [
+    "adblock",
+    "ads",
+    "adblocker"
+  ],
+  "dependencies": {
+    "jquery": ">= 1.9.0"
+  },
+  "license": "MIT",
+  "ignore": [
+    "**/.*",
+    "Gruntfile.js",
+    "deps",
+    "dist",
+    "node_modules",
+    "bower_components",
+    "test"
+  ]
+}
diff --git a/deps/jquery-1.11.0.min.js b/deps/jquery-1.11.0.min.js
diff --git a/deps/jquery.cookie.js b/deps/jquery.cookie.js
@@ -0,0 +1,40 @@
+/**
+ * jQuery Cookie plugin
+ *
+ * Copyright (c) 2010 Klaus Hartl (stilbuero.de)
+ * Dual licensed under the MIT and GPL licenses:
+ * http://www.opensource.org/licenses/mit-license.php
+ * http://www.gnu.org/licenses/gpl.html
+ *
+ */
+jQuery.cookie = function (key, value, options) {
+    // key and at least value given, set cookie...
+    if (arguments.length > 1 && String(value) !== "[object Object]") {
+        options = jQuery.extend({}, options);
+
+        if (value === null || value === undefined) {
+            options.expires = -1;
+        }
+
+        if (typeof options.expires === 'number') {
+            var days = options.expires, t = options.expires = new Date();
+            t.setDate(t.getDate() + days);
+        }
+
+        value = String(value);
+
+        return (document.cookie = [
+            encodeURIComponent(key), '=',
+            options.raw ? value : encodeURIComponent(value),
+            options.expires ? '; expires=' + options.expires.toUTCString() : '', // use expires attribute, max-age is not supported by IE
+            options.path ? '; path=' + options.path : '',
+            options.domain ? '; domain=' + options.domain : '',
+            options.secure ? '; secure' : ''
+        ].join(''));
+    }
+
+    // key and possibly options given, get cookie...
+    options = value || {};
+    var result, decode = options.raw ? function (s) { return s; } : decodeURIComponent;
+    return (result = new RegExp('(?:^|; )' + encodeURIComponent(key) + '=([^;]*)').exec(document.cookie)) ? decode(result[1]) : null;
+};