README.md

impressionist

A lightweight plugin that logs impressions per action or manually per model

What does this thing do?

Logs an impression... and I use that term loosely. It can log page impressions
(technically action impressions), but it is not limited to that. You can log
impressions multiple times per request. And you can also attach it to a model.
The goal of this project is to provide customizable stats that are immediately
accessible in your application as opposed to using Google Analytics and pulling
data using their API. You can attach custom messages to impressions. No
reporting yet.. this thingy just creates the data.

Make your models impressionable. This allows you to attach impressions to
an AR model instance. Impressionist will automatically log the Model name
(based on action_name) and the id (based on params[:id]), but in order to
get the count of impressions (example: @widget.impression_count), you will
need to make your model impressionalble

class Widget < ActiveRecord::Base
is_impressionable
end

Log an impression per model instance in your controller. Note that it is
not necessary to specify "impressionist" (usage #1) in the top of you
controller if you are using this method. If you add "impressionist" to the
top of your controller and also use this method in your action, it will
result in 2 impressions being logged (but associated with one request_hash)

def show
@widget = Widget.find
impressionist(@widget,message:"wtf is a widget?") #message is optional
end

Get unique impression count from a model. This groups impressions by
request_hash, so if you logged multiple impressions per request, it will
only count them one time. This unique impression count will not filter out
unique users, only unique requests

Get the unique impression count from a model filtered by IP address. This
in turn will give you impressions with unique request_hash, since rows with
the same request_hash will have the same IP address.

@widget.impressionist_count(:filter=>:ip_address)

Get the unique impression count from a model filtered by session hash. Same
as #6 regarding request hash. This may be more desirable than filtering by
IP address depending on your situation, since filtering by IP may ignore
visitors that use the same IP. The downside to this filtering is that a
user could clear session data in their browser and skew the results.

@widget.impressionist_count(:filter=>:session_hash)

Get total impression count. This may return more than 1 impression per http
request, depending on how you are logging impressions

@widget.impressionist_count(:filter=>:all)

Logging impressions for authenticated users happens automatically. If you have
a current_user helper or use @current_user in your before_filter to set your
authenticated user, current_user.id will be written to the user_id field in the
impressions table.

Adding a counter cache

Impressionist makes it easy to add a counter_cache column to your model. The
most basic configuration looks like:

is_impressionable :counter_cache => true

This will automatically increment the impressions_count column in the
included model. Note: You'll need to add that column to your model. If you'd
like specific a different column name, you can:

What if I only want to record unique impressions?

Maybe you only care about unique impressions and would like to avoid
unnecessary database records. You can specify conditions for recording
impressions in your controller:

# only record impression if the request has a unique combination of type, id, and session
impressionist :unique => [:impressionable_type, :impressionable_id, :session_hash]
# only record impression if the request has a unique combination of controller, action, and session
impressionist :unique => [:controller_name, :action_name, :session_hash]
# only record impression if session is unique
impressionist :unique => [:session_hash]