Class: CheddarGetter::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/cheddar_getter/client.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = { }) ⇒ Client

options:

:username     => required, your CheddarGetter username
:password     => required, your CheddarGetter password
:product_id   => this or product_code is required
:product_code => this or product_id is required

Raises:



16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/cheddar_getter/client.rb', line 16

def initialize(options = { })
  self.product_code = options[:product_code]
  self.product_id   = options[:product_id]
  self.username     = options[:username]
  self.password     = options[:password]
  
  raise CheddarGetter::ClientException.new(":username is required") unless self.username
  raise CheddarGetter::ClientException.new(":password is required") unless self.password
  unless self.product_code || self.product_id
    raise CheddarGetter::ClientException.new(":product_code or :product_id are required") 
  end
end

Instance Attribute Details

#password ⇒ Object

Returns the value of attribute password.



6
7
8
 
# File 'lib/cheddar_getter/client.rb', line 6

def password
  @password
end

#product_code ⇒ Object

Returns the value of attribute product_code.



6
7
8
 
# File 'lib/cheddar_getter/client.rb', line 6

def product_code
  @product_code
end

#product_id ⇒ Object

Returns the value of attribute product_id.



6
7
8
 
# File 'lib/cheddar_getter/client.rb', line 6

def product_id
  @product_id
end

#username ⇒ Object

Returns the value of attribute username.



6
7
8
 
# File 'lib/cheddar_getter/client.rb', line 6

def username
  @username
end

Class Method Details

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)

Raises:



413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/cheddar_getter/client.rb', line 413

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

Instance Method Details

#add_charge(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#add-charge

id_hash: => customer_code OR => customer_id

data:

:chargeCode  => required,
:quantity    => required,
:eachAmount  => required,
:description => not_required




345
346
347
 
# File 'lib/cheddar_getter/client.rb', line 345

def add_charge(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "add-charge", :id_hash => id_hash, :data => data)
end

#add_item_quantity(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#add-item-quantity

id_hash: 

:code => Either code or id are required (this is the customer code)
:id => Either code or id are required (this is the customer id)
:item_code => Either item code or item id are required
:item_id => Either item code or item id are required

data: (not required)

{ :quantity => treated_as_1_if_not_set }



292
293
294
295
 
# File 'lib/cheddar_getter/client.rb', line 292

def add_item_quantity(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "add-item-quantity", :id_hash => id_hash, 
             :data => data, :add_item_id => true)
end

#add_one_time_invoice(id_hash = {}, data = {}) ⇒ Object

cheddargetter.com/developers#one-time-invoice

id_hash: => customer_code OR => customer_id

data: :charges => => {

:chargeCode, 
:quantity, 
:eachAmount
:description

, => {

:chargeCode, 
:quantity, 
:eachAmount
:description

etc



381
382
383
 
# File 'lib/cheddar_getter/client.rb', line 381

def add_one_time_invoice(id_hash = {}, data = {})
  do_request(:item => :invoices, :action => 'new', :id_hash => id_hash, :data => data)
end

#cancel_subscription(id_hash = { }) ⇒ Object

cheddargetter.com/developers#cancel-subscription

id_hash: => customer_code OR => customer_id



274
275
276
 
# File 'lib/cheddar_getter/client.rb', line 274

def cancel_subscription(id_hash = { })
  do_request(:item => :customers, :action => :cancel, :id_hash => id_hash)
end

#delete_all_customers ⇒ Object

cheddargetter.com/developers#delete-all-customers



242
243
244
 
# File 'lib/cheddar_getter/client.rb', line 242

def delete_all_customers
  do_request(:item => :customers, :action => "delete-all/confirm/1")
end

#delete_charge(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#delete-charge

id_hash: => customer_code OR => customer_id

data:

:chargeId  => required,




358
359
360
 
# File 'lib/cheddar_getter/client.rb', line 358

def delete_charge(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "delete-charge", :id_hash => id_hash, :data => data)
end

#delete_customer(id_hash = { }) ⇒ Object

cheddargetter.com/developers#delete-customer

id_hash: => customer_code OR => customer_id



237
238
239
 
# File 'lib/cheddar_getter/client.rb', line 237

def delete_customer(id_hash = { })
  do_request(:item => :customers, :action => :delete, :id_hash => id_hash)
end

#edit_customer(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#update-customer-subscription

id_hash: => customer_code OR => customer_id

data:

{ 

:firstName            => not_required,
:lastName             => not_required,
:email                => not_required,
:company              => not_required,
:isVatExempt          => not_required,
:vatNumber            => not_required,
:notes                => not_required,
:firstContactDatetime => not_required,
:referer              => not_required,
:campaignTerm         => not_required,
:campaignName         => not_required,
:campaignSource       => not_required,
:campaignMedium       => not_required,
:campaignContent      => not_required,
:metaData => { #not_required
  :any_user_defined_value => not_required
},
:subscription => { #not_required
  :planCode        => not_required,
  :changeBillDate  => not_required,
  :ccNumber        => not_required_unless_plan_change_from_free_to_paid,
  :ccExpiration    => not_required_unless_plan_change_from_free_to_paid,
  :ccCardCode      => not_required_unless_plan_change_from_free_to_paid,
  :ccFirstName     => not_required_unless_plan_change_from_free_to_paid,
  :ccLastName      => not_required_unless_plan_change_from_free_to_paid,
  :ccCompany       => not_required,
  :ccCountry       => not_required,
  :ccAddress       => not_required,
  :ccCity          => not_required,
  :ccState         => not_required,
  :ccZip           => not_required_unless_plan_change_from_free_to_paid
},

}



210
211
212
 
# File 'lib/cheddar_getter/client.rb', line 210

def edit_customer(id_hash = { }, data = { })
  do_request(:item => :customers, :action => :edit, :id_hash => id_hash, :data => data)
end

#edit_customer_only(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#update-customer

id_hash: => customer_code OR => customer_id

data:

{ 

:firstName            => not_required,
:lastName             => not_required,
:email                => not_required,
:company              => not_required,
:notes                => not_required,
:metaData => { #not_required
  :any_user_defined_value => not_required
},

}



230
231
232
 
# File 'lib/cheddar_getter/client.rb', line 230

def edit_customer_only(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "edit-customer", :id_hash => id_hash, :data => data)
end

#edit_subscription(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#update-subscription

id_hash: => customer_code OR => customer_id

data:

:planCode        => not_required,
:changeBillDate  => not_required,
:ccNumber        => not_required_unless_plan_change_from_free_to_paid,
:ccExpiration    => not_required_unless_plan_change_from_free_to_paid,
:ccCardCode      => not_required_unless_plan_change_from_free_to_paid,
:ccFirstName     => not_required_unless_plan_change_from_free_to_paid,
:ccLastName      => not_required_unless_plan_change_from_free_to_paid,
:ccCompany       => not_required,
:ccCountry       => not_required,
:ccAddress       => not_required,
:ccCity          => not_required,
:ccState         => not_required,
:ccZip           => not_required_unless_plan_change_from_free_to_paid




267
268
269
 
# File 'lib/cheddar_getter/client.rb', line 267

def edit_subscription(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "edit-subscription", :id_hash => id_hash, :data => data)
end

#get_customer(id_hash = { }) ⇒ Object

cheddargetter.com/developers#single-customer

id_hash: => customer_code OR => customer_id



89
90
91
 
# File 'lib/cheddar_getter/client.rb', line 89

def get_customer(id_hash = { })
  do_request(:item => :customers, :action => :get, :id_hash => id_hash)
end

#get_customer_list(data = nil) ⇒ Object

cheddargetter.com/developers#all-customers

Any, all, or none of this data hash can be given. It just filters the returned customers

data:

:subscriptionStatus => "activeOnly" or "canceledOnly",
:planCode           => plan_code, #can take an array of plan codes
:createdAfterDate	 => date,
:createdBeforeDate  => date,
:canceledAfterDate  => date,
:canceledBeforeDate =>	date,
:orderBy	           =>	"name" (default), "company", "plan", "billingDatetime" or "createdDatetime"
:orderByDirection   =>	"asc" (default) or "desc"
:search             =>	Tcustomer name, company, email address and last four digits of credit card.




82
83
84
 
# File 'lib/cheddar_getter/client.rb', line 82

def get_customer_list(data = nil)
  do_request(:item => :customers, :action => :list, :data => data)
end

#get_customers(data = nil) ⇒ Object

cheddargetter.com/developers#all-customers

Any, all, or none of this data hash can be given. It just filters the returned customers

data:

:subscriptionStatus => "activeOnly" or "canceledOnly",
:planCode           => plan_code, #can take an array of plan codes
:createdAfterDate	 => date,
:createdBeforeDate  => date,
:canceledAfterDate  => date,
:canceledBeforeDate =>	date,
:orderBy	           =>	"name" (default), "company", "plan", "billingDatetime" or "createdDatetime"
:orderByDirection   =>	"asc" (default) or "desc"
:search             =>	Tcustomer name, company, email address and last four digits of credit card.




59
60
61
62
 
# File 'lib/cheddar_getter/client.rb', line 59

def get_customers(data = nil)
  warn 'Deprecation Warning: get_customers method is deprecated. Use get_customer_list instead'
  do_request(:item => :customers, :action => :get, :data => data)
end

#get_plan(id_hash = { }) ⇒ Object

cheddargetter.com/developers#single-plan

id_hash: => plan_code OR => plan_id



37
38
39
 
# File 'lib/cheddar_getter/client.rb', line 37

def get_plan(id_hash = { })
  do_request(:item => :plans, :action => :get, :id_hash => id_hash)
end

#get_plans ⇒ Object

cheddargetter.com/developers#all-plans



30
31
32
 
# File 'lib/cheddar_getter/client.rb', line 30

def get_plans
  do_request(:item => :plans, :action => :get)
end

#new_customer(data = { }, cookie_info = nil) ⇒ Object

cheddargetter.com/developers#add-customer

data:

{ 

:code                 => required,
:firstName            => required,
:lastName             => required,
:email                => required,
:company              => not_required,
:isVatExempt          => not_required,
:vatNumber            => not_required,
:notes                => not_required,
:firstContactDatetime => not_required,
:referer              => not_required,
:campaignTerm         => not_required,
:campaignName         => not_required,
:campaignSource       => not_required,
:campaignMedium       => not_required,
:campaignContent      => not_required,
:metaData => { #not_required
  :any_user_defined_value => not_required
},
:subscription => { #required
  :planCode        => required,
  :initialBillDate => not_required,
  :ccNumber        => required_if_not_free,
  :ccExpiration    => required_if_not_free,
  :ccCardCode      => required_if_not_free,
  :ccFirstName     => required_if_not_free,
  :ccLastName      => required_if_not_free,
  :ccCompany       => not_required,
  :ccCountry       => not_required,
  :ccAddress       => not_required,
  :ccCity          => not_required,
  :ccState         => not_required,
  :ccZip           => required_if_not_free
},
:charges => { #not required
  :user_defined => { 
    :chargeCode  => required_if_adding_a_charge,
    :quantity    => required_if_adding_a_charge,
    :eachAmount  => required_if_adding_a_charge,
    :description => not_required
  }
},
:items => { #not required
  :user_defined => { 
    :itemCode => required_if_setting_an_item,
    :quantity => required_if_setting_an_item
  }
}

}

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




158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/cheddar_getter/client.rb', line 158

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

#remove_item_quantity(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#remove-item-quantity

id_hash: 

:code => Either code or id are required (this is the customer code)
:id => Either code or id are required (this is the customer id)
:item_code => Either item code or item id are required
:item_id => Either item code or item id are required

data: (not required)

{ :quantity => treated_as_1_if_not_set }



311
312
313
314
 
# File 'lib/cheddar_getter/client.rb', line 311

def remove_item_quantity(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "remove-item-quantity", :id_hash => id_hash, 
             :data => data, :add_item_id => true)
end

#set_item_quantity(id_hash = { }, data = { }) ⇒ Object

cheddargetter.com/developers#set-item-quantity

id_hash: 

:code => Either code or id are required (this is the customer code)
:id => Either code or id are required (this is the customer id)
:item_code => Either item code or item id are required
:item_id => Either item code or item id are required

data: { :quantity => required }



328
329
330
331
 
# File 'lib/cheddar_getter/client.rb', line 328

def set_item_quantity(id_hash = { }, data = { })
  do_request(:item => :customers, :action => "set-item-quantity", :id_hash => id_hash, 
             :data => data, :add_item_id => true)
end