Pixelator

Pixelator is a Ruby on Rails plugin that allows you to easily and asyncronously add tracking pixels (and other bits of html) to your code.

Prerequisites

requires jquery-rails
requires underscore.js

Usage

Install the gem

gem 'pixelator', :git => [email protected]:howaboutwe/pixelator.git

Run the generator

rails g pixelator

The generator will create 2 files for you:

config/initializers/pixelator.rb
config/pixels.yml It will also add pixelator_core to your application.js file:

//= require 'pixelator_core'

Add to you code

config/pixels.yml

pixels.yml contains a hash with the top level keys being types of pixels, such as 'all', 'landing','sign_up', etc.

You define the keys.

Each key, has an array of pixels, which specify:

name - name of pixel for auditing purposes
type - img, js, iframe
snippet - snippet of html that will be run through an underscore template

For example, a google analytics snippet that is to be shown on all pages and uses the google_analytics key in Pixelator.context to set the GA account number would look like:

all:
  - name: google_analytics
    type: javascript
    snippet: |
      <script type="text/javascript">
      try {
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', '<%= google_analytics %>']);
        _gaq.push(['_trackPageview']);

        (function() {
         var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
         ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
         var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
         })();
      } catch(err) {}
      </script>

optionally, you can include a 'partner'

Layout/Views

In the head of your layout, add:

    = javascript_include_tag "/pixelator/data"
    = render partial: 'shared/pixelator_head'

In the bottom of your layout, add:

= render partial: 'shared/pixelator', pixel_types: ['all']

To add the Pixelator to different page, such as landing, do:

= render partial: 'shared/pixelator', pixel_types: ['landing'] If using the partial, you could also set the pixel types in the controller with @pixel_types = ['stuff'] Note: this will **always* add 'all' to the array or

    var pixelator = new Pixelator(PIXEL_DATA, '#{@scope}');
    _.each(#{@pixel_types}, function(p) {
    pixelator.run(p);
    });

TODO

Expand example of how to set pixel context in controller and use in pixels.yml with ERB syntax.
Add documentation about head pixels
JS Pixel data - should not include head and should be on Pixelator obj
JS flag for turning on/off
Turn off but still log each pixel that would be run
run can take an array
change partner to scope
explain partner/scope
Add Travis CI
Add documentation about context

Maintainers

Created by the HowAboutWe.com dev team.

How About We
Rebecca Miller-Webster, HowAboutWe.com
Marco Carag, HowAboutWe.com
Brendan Barr, HowAboutWe.com