cheddargetter_client_ruby 0.2.1 → 0.3.0

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/cheddargetter_client_ruby.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{cheddargetter_client_ruby}
-  s.version = "0.2.1"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Expected Behavior"]
-  s.date = %q{2010-12-11}
+  s.date = %q{2011-01-13}
   s.description = %q{A CheddarGetter API wrapper for Ruby}
   s.email = %q{support@expectedbehavior.com}
   s.extra_rdoc_files = [

data/lib/cheddar_getter/client.rb

@@ -120,7 +120,27 @@ module CheddarGetter
     #    }
     #  }
     #}
-    def new_customer(data = { })
+    #
+    #Pass in the cookie info hash if you have been using the 
+    #set_marketing_cookie method to track marketing metrics.
+    #Info from the marketing cookie will be passed along to 
+    #Cheddar Getter in the new_customer call.
+    #
+    #cookie_info (optional):
+    #
+    #{
+    #  :cookies => required
+    #  :cookie_name => not_required
+    #}
+    def new_customer(data = { }, cookie_info = nil)
+      if cookie_info
+        cookie_name = cookie_info[:cookie_name] || DEFAULT_COOKIE_NAME
+        cookie_data = (YAML.load(cookie_info[:cookies][cookie_name] || "") rescue nil) || { }
+        [:firstContactDatetime, :referer, :campaignTerm, :campaignName, 
+         :campaignSource, :campaignMedium, :campaignContent].each do |key|
+          data[key] ||= cookie_data[key] if cookie_data[key]
+        end
+      end
       do_request(:item => :customers, :action => :new, :data => data)
     end
     
@@ -303,6 +323,138 @@ module CheddarGetter
       do_request(:item => :customers, :action => "add-charge", :id_hash => id_hash, :data => data)
     end
     
+    #http://support.cheddargetter.com/faqs/marketing-metrics/marketing-metrics
+    #
+    #Convenience wrapper of setcookie() for setting a persistent cookie 
+    #containing marketing metrics compatible with CheddarGetter's marketing metrics tracking.
+	  #Running this method on every request to your marketing site sets or refines the marketing 
+    #cookie data over time.
+    #If you are using this method, you can pass in the cookies to the new_customer call, 
+    #which will automatically add the data to the customer record.  
+    #
+    #Sample usage for your controller:
+    # 
+    #  before_filter :update_cheddar_getter_cookie
+    #  def update_cheddar_getter_cookie
+    #    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    #  end
+    #
+    #options:
+    #
+    #{
+    #  :cookies     => required,
+    #  :request     => required,
+    #  :cookie_name => not_required (default 'CGMK'),
+    #  :expires     => not_required (default 2 years),
+    #  :path        => not_required (default '/'),
+    #  :domain      => not_required (default nil),
+    #  :secure      => not_required (default false),
+    #  :httponly    => not_required (default false)
+    #}
+    def self.set_marketing_cookie(options = { })
+      default_options = { 
+        :cookie_name => DEFAULT_COOKIE_NAME,
+        :expires => Time.now + 60*60*24*365*2,
+        :path => '/',
+        :domain => nil,
+        :secure => false,
+        :httponly => false
+      }
+      
+      options = default_options.merge(options)
+      cookies = options[:cookies]
+      raise CheddarGetter::ClientException.new("The option :cookies is required") unless cookies
+      request = options[:request]
+      raise CheddarGetter::ClientException.new("The option :request is required") unless request
+      
+      utm_params = { 
+        :utm_term     => :campaignTerm, 
+        :utm_campaign => :campaignName, 
+        :utm_source   => :campaignSource, 
+        :utm_medium   => :campaignMedium, 
+        :utm_content  => :campaignContent 
+      }
+      
+      # get the existing cookie information, if any
+      cookie_data = (YAML.load(cookies[options[:cookie_name]] || "") rescue nil)
+      cookie_data = nil unless cookie_data.kind_of?(Hash)
+
+      # no cookie yet -- set the first contact date and referer in the cookie
+      # (only first request)
+      if !cookie_data
+        # when did this lead first find us? (right now!)
+        # we'll use this to determine the customer "vintage"
+        cookie_data = { :firstContactDatetime => Time.now.strftime("%Y-%m-%dT%H:%M:%S%z") }
+
+        # if there's a __utma cookie, we can get a more accurate time
+        # which helps us get better data from visitors who first found us
+        # before we started setting our own cookie
+        if cookies['__utma']
+          domain_hash, visitor_id, initial_visit, previous_visit, current_visit, visit_counter =
+            cookies['__utma'].split('.')
+        
+          initial_visit = initial_visit.to_i
+          if initial_visit != 0
+            cookie_data[:firstContactDatetime] = Time.at(initial_visit).strftime("%Y-%m-%dT%H:%M:%S%z") 
+          end
+        end
+
+        #set the raw referer (defaults to 'direct')
+        cookie_data[:referer] = 'direct'
+        cookie_data[:referer] = request.env['HTTP_REFERER'] unless request.env['HTTP_REFERER'].blank?
+
+        # if there's some utm vars
+        # When tagging your inbound links for google analytics 
+        #   http://www.google.com/support/analytics/bin/answer.py?answer=55518
+        # our cookie will also benenfit by the added params
+        utm_params.each { |k, v| cookie_data[v] = request.params[k] unless request.params[k].blank? }
+        
+        cookies[options[:cookie_name]] = { 
+          :value => cookie_data.to_yaml,
+          :path => options[:path],
+          :domain => options[:domain],
+          :expires => options[:expires],
+          :secure => options[:secure],
+          :httponly => options[:httponly]
+        }
+
+      # cookie is already set but maybe we can refine it with __utmz data
+		  # (second and subsequent requests)
+      elsif cookies['__utmz']
+        return if cookie_data.size >= 3 #already has enough info
+
+        domain_hash, timestamp, session_number, campaign_number, campaign_data =
+          cookies['__utmz'].split('.')
+
+        return if campaign_data.blank?
+        campaign_data = (Hash[*campaign_data.split(/\||=/)] rescue { })
+
+        # see if it's a google adwords lead 
+        # in this case, we only get the keyword
+        if ! campaign_data["utmgclid"].blank? 
+          cookie_data[:campaignSource] = 'google';
+          cookie_data[:campaignMedium] = 'ppc';
+          cookie_data[:campaignTerm]   = campaign_data["utmctr"] unless campaign_data["utmctr"].blank?
+        else
+          cookieData[:campaignSource]  = campaign_data["utmcsr"] unless campaign_data["utmcsr"].blank?
+          cookieData[:campaignName]    = campaign_data["utmccn"] unless campaign_data["utmccn"].blank?
+          cookieData[:campaignMedium]  = campaign_data["utmcmd"] unless campaign_data["utmcmd"].blank?
+          cookieData[:campaignTerm]    = campaign_data["utmctr"] unless campaign_data["utmctr"].blank?
+          cookieData[:campaignContent] = campaign_data["utmcct"] unless campaign_data["utmcct"].blank?
+        end
+        
+        cookies[options[:cookie_name]] = { 
+          :value => cookie_data.to_yaml,
+          :path => options[:path],
+          :domain => options[:domain],
+          :expires => options[:expires],
+          :secure => options[:secure],
+          :httponly => options[:httponly]
+        }
+      end
+    end
+    
+    
     private
     def get_identifier_string(type, id_hash)
       code = type ? "#{type}_code".to_sym : :code
@@ -356,9 +508,13 @@ module CheddarGetter
       :createdAfterDate => :year_month_day,
       :createdBeforeDate => :year_month_day,
       :canceledAfterDate => :year_month_day,
-      :canceledBeforeDate => :year_month_day
+      :canceledBeforeDate => :year_month_day,
+      :firstContactDatetime => :datetime,
+      :changeBillDate => :datetime
     }
     
+    DEFAULT_COOKIE_NAME = 'CGMK'
+    
     def deep_fix_request_data!(data)
       if data.is_a?(Array)
         data.each do |v|
@@ -372,7 +528,8 @@ module CheddarGetter
             data[k] = case type
                         when :month_year then v.respond_to?(:strftime) ? v.strftime("%m/%Y") : v
                         when :boolean then v ? "1" : "0"
-                        when :year_month_day then v.respond_to?(:strftime) ? v.strftime("%Y/%m/%d") : v
+                        when :year_month_day then v.respond_to?(:strftime) ? v.strftime("%Y-%m-%d") : v
+                        when :datetime then v.respond_to?(:strftime) ? v.strftime("%Y-%m-%dT%H:%M:%S%z") : v
                         else v
                         end
           end

data/lib/cheddar_getter/response.rb

@@ -171,7 +171,7 @@ module CheddarGetter
     #
     #code must be provided if this response contains more than one customer.
     def customer_outstanding_invoices(code = nil)
-      now = DateTime.now
+      now = Time.now
       customer_invoices(code).reject do |i| 
         i[:paidTransactionId] || i[:billingDatetime] > now
       end
@@ -282,7 +282,7 @@ module CheddarGetter
             data[k] = case type
                         when :integer then v.to_i
                         when :float then v.to_f
-                        when :datetime then DateTime.parse(v) rescue v
+                        when :datetime then Time.parse(v) rescue v
                         when :date then Date.parse(v) rescue v
                         when :boolean then v.to_i != 0
                         else v

data/test/test_cheddargetter_client_ruby.rb

@@ -40,6 +40,7 @@ class TestCheddargetterClientRuby < Test::Unit::TestCase
       :firstName            => "First",
       :lastName             => "Last",
       :email                => "email@example.com",
+      :firstContactDatetime => Time.now,
       :subscription => { 
         :planCode        => "TEST_PLAN_2",
         :ccNumber        => "4111111111111111",
@@ -873,4 +874,109 @@ class TestCheddargetterClientRuby < Test::Unit::TestCase
     assert_equal ["Credit card type is not accepted"], result.error_messages
   end
   
+  should "test setting the marketing cookie" do 
+    cn = CheddarGetter::Client::DEFAULT_COOKIE_NAME
+    fake_request_class = Struct.new(:env, :params)
+    assert_raises(CheddarGetter::ClientException) { CheddarGetter::Client.set_marketing_cookie }
+    assert_raises(CheddarGetter::ClientException) { CheddarGetter::Client.set_marketing_cookie(:cookies => { }) }
+    
+    request = fake_request_class.new({'HTTP_REFERER' => 'woot'}, { :utm_term => 'hi' })
+    time = Time.now
+    cookies = { "__utma" => " . .#{time.to_i}. . . "}
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+
+    assert_equal '/', cookies[cn][:path]
+    assert_equal nil, cookies[cn][:domain]
+    assert_equal false, cookies[cn][:secure]
+    assert_equal false, cookies[cn][:httponly]
+    cookie_data = YAML.load(cookies[cn][:value])
+    assert_equal 3, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    assert_equal "hi", cookie_data[:campaignTerm]
+    
+    cookies[cn] = cookies[cn][:value]
+    cookies['__utmz'] = " . . . .utmgclid=value|utmctr=bye"
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    cookie_data = YAML.load(cookies[cn]) #was not manipulated
+    assert_equal 3, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    assert_equal "hi", cookie_data[:campaignTerm]
+    
+    cookie_data.delete(:campaignTerm)
+    cookies[cn] = cookie_data.to_yaml
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    cookie_data = YAML.load(cookies[cn][:value])
+    assert_equal 5, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    assert_equal "bye", cookie_data[:campaignTerm]
+    assert_equal "google", cookie_data[:campaignSource]
+    assert_equal "ppc", cookie_data[:campaignMedium]
+    
+    cookie_data.delete(:campaignTerm)
+    cookie_data.delete(:campaignSource)
+    cookie_data.delete(:campaignMedium)
+    cookies['__utmz'] = " . . . ."
+    cookies[cn] = cookie_data.to_yaml
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    cookie_data = YAML.load(cookies[cn]) #was not manipulated
+    assert_equal 2, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    
+    cookies['__utmz'] = " . . . .utmgclid=value"
+    cookies[cn] = cookie_data.to_yaml
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    cookie_data = YAML.load(cookies[cn][:value])
+    assert_equal 4, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    assert_equal "google", cookie_data[:campaignSource]
+    assert_equal "ppc", cookie_data[:campaignMedium]
+    
+    cookie_data.delete(:campaignTerm)
+    cookie_data.delete(:campaignSource)
+    cookie_data.delete(:campaignMedium)
+    cookies['__utmz'] = " . . . . "
+    cookies[cn] = cookie_data.to_yaml
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    cookie_data = YAML.load(cookies[cn][:value])
+    assert_equal 2, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    
+    cookies[cn] = "stuff"
+    CheddarGetter::Client.set_marketing_cookie(:cookies => cookies, :request => request)
+    cookie_data = YAML.load(cookies[cn][:value])
+    assert_equal 3, cookie_data.size
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), cookie_data[:firstContactDatetime]
+    assert_equal "woot", cookie_data[:referer]
+    assert_equal "hi", cookie_data[:campaignTerm]    
+  end
+  
+  should "create a customer with marketing data" do
+    result = CG.delete_all_customers
+    assert_equal true, result.valid?
+    
+    time = Time.now
+    
+    cookies = { CheddarGetter::Client::DEFAULT_COOKIE_NAME => ({ 
+        :firstContactDatetime => time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        :referer => 'direct',
+        :campaignTerm => "incorrect"
+      }.to_yaml) }
+  
+    result = CG.new_customer({ :campaignTerm => "correct"}.merge(free_new_user_hash(1)),
+                             { :cookies => cookies })
+    assert_equal 1, result.customers.size
+    assert_equal "1", result.customer[:code]
+    assert_equal "Free Plan Test", result.customer_plan[:name]
+    assert_equal time.strftime("%Y-%m-%dT%H:%M:%S%z"), 
+      result.customer[:firstContactDatetime].strftime("%Y-%m-%dT%H:%M:%S%z")
+    assert_equal 'direct', result.customer[:referer]
+    assert_equal 'correct', result.customer[:campaignTerm]
+  end
+  
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cheddargetter_client_ruby
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Expected Behavior
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-11 00:00:00 -05:00
+date: 2011-01-13 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency