Skip to content
Ruby gem providing access to the CleverTap API
Ruby Shell
Branch: master
Clone or download
betasve Merge pull request #13 from betasve/pub_gem
Change gemspec before publishing to RubyGems.org
Latest commit 182cb6b Apr 13, 2018

README.md

clevertap-ruby

Module providing access to the CleverTap API

Install

Add to your Gemfile

gem 'clever_tap', github: 'tradeo/clevertap-ruby'

Usage

Configure the client

Create an instance of CleverTap object: Available in v0.2.0 but will be depricated as of v1.0.0

CLEVER_TAP = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')

You can add configuration settings as parameters like above and/or using a block.

CLEVER_TAP = CleverTap.new do |config|
  config.account_id = '<your account ID>' # mandatory
  config.passcode = '<your passcode>' # mandatory
  config.identity_field = 'ID' # default value "identity"

  config.configure_faraday do |faraday_config| # optional
    faraday_config.adapter :httpclient # default adapter "net_http"
  end
end

As of v0.3.0 the new way of setting up CleverTap is:

CleverTap.setup do |config|
  # Default ID could be reset later
  # case by case when uploading Profile/Event
  config.identity_field = 'ID'

  config.account_id = 'the-account-id'
  config.account_passcode = 'the-passcode'
end

Then creating a shared instance to use trough the app (v0.3.0 and above)

clevertap = CleverTap::Client.new

# You can add callbacks for successfull and failed calls as so:
clevertap.on_successful_upload do |response|
  # log the response as response.to_s
  # response is of type CleverTap::Response
  # having methods `success` (true or false)
  # and `failures` (empty if success == true)
  # contains hash with errors returned from CleverTap endpoint
end

clevertap.on_failed_upload do |response|
  ...
end

Upload a profile

.upload_profile accepts as a first argument an object responding to #to_h and #[].

profile = {
  'identity' => '666',
  'Name' => 'John Bravo'
}

client = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
response = client.upload_profile(profile)

response.success # => true / false
response.status # => 'success' / 'partial' / 'fail'
response.errors # => [ {  }, ...]

Date field used as a time stamp is optional. If it's missing the current time stamp will be send instead. The value should respond to .to_i and return epoch time.

profile = CleverTap::Profile.new(
  data: { 'ID' => 1, 'Name' => 'John Doe' }, # MANDATORY, expects to receive a hash containing the identity field specified in `CleverTap.setup`, or below
  identity_field: 'field_name' | false,      # optional
  fbid: '34322423',                          # optional, facebook id, can replace original identity
  gpid: '34322423',                          # optional, google plus id, can replace original identity
  objectId: '0f5d5fff698245f1ac5f192c',      # optional, uniq CleverTap identifier
  timestamp_field: 'Created At',             # optional, has to be present in the `data` hash, else it throws
  custom_timestamp: 1468308340               # optional, custom time stamp if user needs to set a particular timestamp, not presented in the object, takes precedence
)

clever_tap.upload(profile)
clever_tap.upload(profiles) # works as well with [CleverTap::Profile]

Upload an event

Available in v0.2.0 but will be depricated as of v1.0.0 .upload_event accepts as a first argument an object responding to #to_h and #[] and a second parameter keyword argument name: <name>.

event = {
  'identity' => '666',
  'Name' => 'Jonh Bravo',
  'Cookie ID' => '424242'
}

client = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
response = client.upload_event(event, name: 'registration')

response.success # => true / false
response.status # => 'success' / 'partial' / 'fail'
response.errors # => [ {  }, ...]

As of v0.3.0 the new way of uploading Event(s) is:

event = CleverTap::Event.new(
  data: { 'ID' => 1, 'Field' => 'Value' } # MANDATORY, expects to receive a hash containing the identity field specified in `CleverTap.setup`, or below
  name: 'Event Name',                     # MANDATORY
  identity_field: 'field_name' | false,   # optional, has to be present in the `data` hash, else it throws
  fbid: '34322423',                       # optional, facebook id, can replace original identity
  gpid: '34322423',                       # optional, google plus id, can replace original identity
  objectId: '0f5d5fff698245f1ac5f192c',   # optional, uniq CleverTap identifier, can replace identity
  timestamp_field: 'Open Time',           # optional, has to be present in the `data` hash, else it throws
  custom_timestamp: 1468308340,           # optional, custom time stamp if user needs to set a particular timestamp, not presented in the object
)

clevertap.upload(event)
clevertap.upload(events) # Works as well with [CleverTap::Event]

Send requests as Dry Run

Passing parameter dry_run: true to upload methods you can test the data submitted for a validation errors. The record won't be persisted.

Available in v0.2.0 but will be depricated as of v1.0.0

  client = CleverTap.new(account_id: '<your account ID>', passcode: '<your passcode>')
  client.upload_profile(profile, dry_run: true)

As of v0.3.0 the new way of using a Dry Run is :

clevertap.upload(event, dry_run: true)

Handle the response

The CleverTap response object has the following interface:

  1. #status - "success" / "partial" / "fail"
  2. #success - true when is the status is "success" and false otherwise
  3. #errors - it's actually unprocessed synonym returned when the request is successful(code 200), but will contains the failed records even when the code is different than 200.
  4. #code - codes from 200-500. When it's 200, errors can contains a validation error codes. When it's -1 the error is custom and more info can be found in the message. More info about the codes can find CleverTap Docs

More documentation you can find in the specs

You can’t perform that action at this time.