lab628-ruby

This is the official Lab628 ruby integration library.

Installation

Add to your Gemfile:

gem 'lab628'

Initialization

Configure a single access key globally (e.g. for Rails in config/initializers/lab628.rb):

Lab628.api_key = 'your api key'
Lab628.secret = 'your shared secret'

API keys and secrets are available in the Access Keys section of the Lab628 dashboard.

An instance can be used to supply or override these globals.

tracker = Lab628.new(api_key: 'your api key', secret: 'your shared secret')

This is useful if you use multiple keys.

See also: sync configuration.

Tracking activities

You can track any hash:

Lab628.activity(user_id: 7, topic: 'excitement')

The hash will be converted to JSON. Ruby objects in the hash that don't correspond to JSON types will be converted to strings via .to_s.

You can also track an activity in JSON form:

Lab628.activity("{\"this\":\"json\",\"is\":[\"already\",\"encoded\"]}")

The same method can be used on instances:

Lab628.new(api_key: 'key', secret: 'secret').activity(user_id: 7, topic: 'excitement')

Querying activities

Query using a hash expressed in the Lab628 query language (documentation):

Lab628.query(
    query: [
        { l628_timestamp: '$last_day' },
        { page: 'checkout' }
    ],
    summary: [
        { cart_size: 'avg' },
        { total_price: 'sum' }
    ]
)

The method returns a response in hash form:

{
    "total" => 152,
    "results" => [
        {
            "event" => "checkout",
            "page" => "checkout",
            "user_id" => "74338979973",
            "region" => "us",
            "cart_size" => 4,
            "total_price" => 128,
            "event_depth" => 1
        },
        ...
    ],
    "summary" => {
        "cart_size" => {
            "avg" => 5.2272727272727275
        },
        "total_price" => {
            "sum" => 6382.0
        }
    }
}

As with activity, the query method can also be used on Lab628 instances.

Asynchronous activity tracking

Set the sync mode on the Lab628 class or an instance:

Lab628.sync = :job
async_tracker = Lab628.new(api_key: 'key', secret: 'secret', sync: :job)

Available modes:

• :inline (default): tracking is performed synchronously, blocking until a response is received.
  • The activity method returns true or false based on request success.
• :job: an ActiveJob for tracking is placed on the :lab628 queue.
  • You must independently include one of these gems:
    • activejob, included in Rails 4.2+
    • activejob_backport, for Rails 4.0 and 4.1
  • The activity method returns the ActiveJob instance.
• :thread: tracking is performed in a concurrent thread using Thread.new.
  • The activity method returns the Thread instance.

Contribution

Test for your current Ruby version with:

bundle
bundle exec rake

Test for all supported environments using WWTD, which requires all Ruby versions in the Travis file to be installed via RVM.

We are open to discontinuing support for older Ruby versions, if required by significant fixes or new features.