Skip to content
Browse files

Adding documentation + support for additional search engines

  • Loading branch information...
1 parent 6f3ffa2 commit 54280c0161a35f8aaffcb5487cbe5042fc552205 Kali Donovan committed Oct 7, 2011
Showing with 89 additions and 12 deletions.
  1. +61 −0 README.md
  2. +28 −12 lib/rack-referrals.rb
View
61 README.md
@@ -0,0 +1,61 @@
+Rack/Referrals
+=============
+
+Rack/referrals is a rack middleware that extracts information from each request about the referring website. Specifically, it parses the HTTP-REFERER header and tells you if the request came from a known search engine (and if so, what the search terms were).
+
+
+Purpose
+-------
+
+Ever wanted to know if the page is being viewed by a user who got there via a search engine? If so, ever wanted to show them a link like "Interested in <search term>? Click here to browse related widgets"?
+
+Yeah, this'll help.
+
+
+Installation
+------------
+
+Quick and easy:
+
+ gem install rack-referrals
+
+
+Example Usage (Rails 3 App)
+-------------------------
+
+Just add it to your middleware stack:
+
+ class Application < Rails::Application
+ ...
+ config.middleware.use Rack::Referrals
+ ...
+ end
+
+
+Getting Fancy
+-------------
+
+This knows about a number of search engines by default (Google, Yahoo, Bing, check the <code>DEFAULT_ENGINES</code> constant in <code>lib/rack-referrals.rb</code> for the current list).
+
+You can add on support for additional search engines (by passing the <code>:additional_engines</code> parameter):
+
+ class Application < Rails::Application
+ ...
+ config.middleware.use Rack::Referrals.new :additional_engines => {
+ :my_engine_name => [/domain_regular_expression/, 'search-term-parameter'],
+ :another_name => [/domain_regular_expression/, 'search-term-parameter'],
+ }
+ ...
+ end
+
+You can also just completely clear the default ones and use _only_ those you define (with the <code>:engines</code> parameter):
+
+ class Application < Rails::Application
+ ...
+ config.middleware.use Rack::Referrals.new :engines => {
+ :only_engine_i_like => [/domain_regular_expression/, 'search-term-parameter']
+ }
+ ...
+ end
+
+In either case, <code>domain_regular_expression</p> is a regular expression used to identify this search engine, like <code>/^https?:\/\/(www\.)?google.*/</code>, and <code>search-term-parameter</code> is the parameter that the search engine uses to store the user's search (for Google, that's <code>q</code>).
View
40 lib/rack-referrals.rb
@@ -1,26 +1,42 @@
require "rack-referrals/version"
module Rack
+
+ #
+ # Rack Middleware for extracting information from the HTTP-REFERER header.
+ # Specifically, it populates +env['referring.search_engine']+ and
+ # +env['referring.search_phrase']+ if it detects a request came from a known
+ # search engine.
+ #
class Referrals
DEFAULT_ENGINES = {
- :google => [/^http:\/\/(www\.)?google.*/, 'q'],
- :yahoo => [/^http:\/\/search\.yahoo.*/, 'p'],
- :msn => [/^http:\/\/search\.msn.*/, 'q'],
- :aol => [/^http:\/\/search\.aol.*/, 'userQuery'],
- :altavista => [/^http:\/\/(www\.)?altavista.*/, 'q'],
- :feedster => [/^http:\/\/(www\.)?feedster.*/, 'q'],
- :lycos => [/^http:\/\/search\.lycos.*/, 'query'],
- :alltheweb => [/^http:\/\/(www\.)?alltheweb.*/, 'q']
+ # Tested myself
+ :google => [/^https?:\/\/(www\.)?google.*/, 'q'],
+ :yahoo => [/^https?:\/\/([^\.]+.)?search\.yahoo.*/, 'p'],
+ :bing => [/^https?:\/\/search\.bing.*/, 'q'],
+ :biadu => [/^https?:\/\/(www\.)?baidu.*/, 'wd'],
+ :rambler => [/^https?:\/\/([^\.]+.)?rambler.ru/, 'query'],
+ :yandex => [/^https?:\/\/(www\.)?yandex.ru/, 'text'],
+
+ # Borrowed from https://github.com/squeejee/search_sniffer
+ :msn => [/^https?:\/\/search\.msn.*/, 'q'],
+ :aol => [/^https?:\/\/(www\.)?\.aol.*/, 'query'],
+ :altavista => [/^https?:\/\/(www\.)?altavista.*/, 'q'],
+ :feedster => [/^https?:\/\/(www\.)?feedster.*/, 'q'],
+ :lycos => [/^https?:\/\/search\.lycos.*/, 'query'],
+ :alltheweb => [/^https?:\/\/(www\.)?alltheweb.*/, 'q']
+
+ # Want to add support for more? A good place to start would be this list (note that they
+ # give example domains, though, not anything we can use to construct a reliable reg exp):
+ # http://code.google.com/apis/analytics/docs/tracking/gaTrackingTraffic.html#searchEngine
}
def initialize(app, opts = {})
@app = app
- # require 'ruby-debug'
- # debugger
-
- @engines = opts[:engines] ? opts[:engines] : DEFAULT_ENGINES.merge(opts[:additional_engines] || {})
+ @engines = opts[:engines]
+ @engines ||= DEFAULT_ENGINES.merge(opts[:additional_engines] || {})
end
def call(env)

0 comments on commit 54280c0

Please sign in to comment.
Something went wrong with that request. Please try again.