Attune

A client for the Attune ranking API. Built using the excellent faraday library.

Installation

Add this line to your application's Gemfile:

gem 'attune'

And then execute:

$ bundle

Usage

Example rails usage

Requests are performed through a client object

client = Attune::Client.new

Visitors to the application should be tagged with an anonymous user id

class ApplicationController
  before_filter do
    session[:attune_id] ||= attune_client.anonymous.create.id
  end

  private
  def attune_client
    @attune_client ||= Attune.client
  end
end

The user id can be bound to a customer id at login

class SessionsController
  # ...

  def create
    # ...
    attune_customer = Attune::Model::Customer.new(customer: current_user.id)
    attune_client.anonymous.update(session[:attune_id], attune_customer)
  end
end

The client can then perform rankings

class ProductsController
  def index
    @products = sorted(Product.all)
  end

  private
  def sorted products
    ranking_params = Attune::Model::RankingParams.new
    ranking_params.anonymous = session[:attune_id]
    ranking_params.view = request.fullpath
    ranking_params.entity_type = 'products'
    ranking_params.user_agent = request.env["HTTP_USER_AGENT"]
    ranking_params.ids = products.map(&:id)
    scope = Attune::Model::ScopeEntry.new
    scope.name = 'category'
    scope.value = 'pants'
    ranking_params.scope = [scope]
    ranking = attune_client.entities.get_rankings(ranking_params)
    products.sort_by do |product|
      ranking.ranking.index(product.id.to_s)
    end
  end
end

The client provides a way to request a new auth_token through the API

client = Attune::Client.new
auth_token = client.get_auth_token('my-client-id', 'my-client-secret')

Also see Blacklist examples for examples of our blacklist API.

Configuration

Attune can be configured globally

Attune.configure do |c|
  c.auth_token = "my-secure-auth-token"
  c.endpoint = "http://example.com/"
  c.timeout  = 5
end

Settings can also be overridden on a client object

client = Attune::Client.new(auth_token: "my-secure-auth-token", timeout: 2)

See the documentation for Attune::Configurable and the default configuration for more details.

Testing

For testing and development, the ranking API can be simulated using.

Attune.test_mode!

In this mode no API calls will be made, and rankings will be returned in their original order. Calling .test_mode! is equivalent to setting disabled to true and exception_handler to :mock.

Contributing

  1. Fork it ( http://github.com/attune-api/attune-ruby/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request