= LeadTune API Ruby Gem

http://github.com/leadtune/leadtune-ruby

Copyright 2010 LeadTune, LLC

Eric Wollesen (mailto:devs@leadtune.com)

For details about the LeadTune API, see: http://leadtune.com/api

== Configuration

Authentication credentials can be specified by any of several methods, as
detailed below.  Available configuration values include:

* username
* password
* organization

=== Configuration File

The configuration file can be specified when calling Prospect#new.  If no
file is specified, the gem will also look for +leadtune.yml+ in the
current directory.

==== Format

The configuration file is a YAML file, an example of which is:
 username: me@mycorp.com
 password: my_secret
 organization: MYC

=== Environment Variables

Your LeadTune username, password, and organization can be specified in the
+LEADTUNE_USERNAME+, +LEADTUNE_PASSWORD+, and +LEADTUNE_ORGANIZATION+
environment variables. <em>These values take precedence over values read
from the configuration file.</em>

=== Factors Hash

When initializing your Leadtune::Prospect, you can include your username,
password, and organization along with any factors you wish to
submit. <em>These values take precedence over values read from environment
variables, or the configuration file.</em>

=== Instance Methods

You can also set your username, password, and organization by calling the
Leadtune::Prospect object's #username=, #password=, and #organization=
methods. <em>These values take precedence over values read from
environment variables, a configuration file, or the factors hash.</em>

== Example Usage

An attempt was made to allow for an ActiveModel-like interface.

 require "rubygems"
 require "leadtune"

 prospect = Leadtune::Prospect.post({
   :username => "admin@loleads.com"        # required (See Leadtune::Config)
   :password => "secret"                   # required (See Leadtune::Config)
   :organization => "LOL",                 # required (See Leadtune::Config)
   :event => "offers_prepared",            # required
   :email => "test@example.com"            # required
   :target_buyers => ["TB-LOL", "AcmeU",]  # required
   # ... include optional factors here, see http://leadtune.com/factors for details
 })

<em>Or alternatively</em>

 prospect = Leadtune::Prospect.post do |p|
   p.event = "offers_prepared"
   p.email = "test@example.com"   
   ... and so on
 end

<em>Or even</em>

 prospect = Leadtune::Prospect.new
 prospect.event = "offers_prepared"
 prosepct.email = "test@example.com"   
 ... and so on
 prospect.post

== Automatic Environment Determination

At initialization, an attempt is made to determine your application's current
environment.  If a rack or rails production environment is detected, prospects
will be posted to LeadTune's production host.  Otherwise prospects will be
posted to LeadTune's sandbox host.  The application environment can be
overriden via the +APP_ENV+ environment variable, which takes precedence over
all other methods.