Project

clever_tap

0.02
No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
Gem providing easy access to the CleverTap API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.14
~> 10.0

Runtime

<= 0.14.0, >= 0.8
>= 0
 Project Readme

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