# Waze GeoRedirect

`GeoRedirect` is a Rack middleware that can be configured to
redirect incoming clients to different hosts based on their
geo-location data.

For instance, we use it for [our advertisers site](http://biz.waze.com/)
to redirect users to:

* [biz.waze.co.il](http://biz.waze.co.il) for Israel-incoming traffic.
* [biz.waze.com](http://biz.waze.com) for US and Canada incoming traffic.
* [biz-world.waze.com](http://biz-world.waze.com/) for any other sources.

The server stores a session variable with the server it decided on, for future traffic from the same client.

In addition, you can override these redirects by adding `?redirect=1` to any URL, and by that forcing the server to host from the current domain (and saving that domain to the user's session variable).

## Installation

Add this line to your application's Gemfile:

    gem 'geo_redirect'

And then execute:

    $ bundle


## Usage

These usage instructions were written for Rails products, although I'm pretty sure you could use the gem with any other Rack-based solution.

You'll need to add this to your `production.rb`:

	  Rails.application.middleware.use GeoRedirect::Middleware

This will make sure `GeoRedirect` runs before your application gets rolling.

The middleware requires two additional files to be present:

### 1. Configuration YML

This should be a YML file representing your redirection rules.

Here's a template that we use for the setup described above:

```
:us:
  :host: 'biz.waze.com'
  :countries: ['US', 'CA']

:il:
  :host: 'biz.waze.co.il'
  :countries: ['IL']

:world: &default
  :host: 'biz-world.waze.com'

:default: *default
```

Note that:

1. Every main item is a location, and must have a `host` configured.
2. A location can have a `countries` array. This will cause a redirect to this location for users from that country code. For available country codes, see [ISO 3166 Country Codes list](http://www.maxmind.com/en/iso3166) from MaxMind (the Geo IP provider `GeoRedirect` uses).
3. There must be a `default` location that would be used in case the client can't be geo-located.

### 2. GeoIP Countries database

`GeoRedirect` uses the [`geoip`](http://geoip.rubyforge.org/) gem for its geo-location functionality. In particular, it requires the `GeoLite country` free database from [MaxMind](http://www.maxmind.com/).

You can download the database file [directly from MaxMind](http://geolite.maxmind.com/download/geoip/database/GeoLiteCountry/GeoIP.dat.gz) and unzip it into `db/` in your project, **or** you could use the following `rake` task designed just for that:

	$ rake georedirect:fetch_db

### Custom paths

The default paths for these files are:

1. `config/georedirect.yml`
2. `db/GeoIP.dat`

If that doesn't suit you, you can customize these when adding `GeoRedirect` to your project:

	  Rails.application.middleware.use GeoRedirect::Middleware {
	  	:db => 'db/geo_database.dat',
	  	:config => 'geo_cfg.yml'
	  }

## Known Issues

A couple issues I know about but haven't had the time to fix:

1. Cross-domain session var is required. In particular, if your stubborn user goes to more than 1 server with `?redirect=1`, all of these servers will never redirect them again (until the session is expired).
2. When a client accesses your site from an unknown hostname (one that was not configured in the `yml` file) with `?redirect=1`, they will stay in that hostname for the current session, but in the future would be redirected to the configured default hostname (because it was saved on their session var).


## Contributing

1. Fork it!
2. Create your feature branch! (`git checkout -b my-new-feature`)
3. Commit your changes! (`git commit -am 'Add some feature'`)
4. Push to the branch! (`git push origin my-new-feature`)
5. Create new Pull Request!