tamber 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ff3f3dba7a668c6253df8294dfb0e52ed8142c0
-  data.tar.gz: 92d0beaa0f356f2f2b2bc5565539bdc95aaf6e22
+  metadata.gz: af8fed11bb5f401f45c1c884abfaca26fb830959
+  data.tar.gz: e623a12f3d1b68e53c8813ab18b9007f141dd4e2
 SHA512:
-  metadata.gz: 7683fbdcb694288bac09b9641c5406c27c067f74fe41ed5b27691e399e77a81eaceecd4b685413d6bc3797329f331cfd7f142e741149ec509029d42d5f45de1e
-  data.tar.gz: dc82af318fd12f93b80b0b9fdbab01476cd4b1ab24e919f278362e22cb94f8c1230d1783a281f40db8b64915b27eb08240ee3f9bf53cf9d8a587ca7c0ade816e
+  metadata.gz: 887b3119d229994872f2686c20f0622e4b683ea25d829a79d8773b24a276f043ff04031030d7a3f58637f73ff63b611c561987783fbca5d8e7f48f77c7030232
+  data.tar.gz: 38428805fbce8ccdde489cd7d95c80dd2145d7d8b333b3f0657598913f9b6761e76a62f710646ffe53414c43eab2ccdce42c137ab9fa39a5ba82774f72fcb138

data/.gitignore

@@ -0,0 +1,6 @@
+/tamber-*.gem
+/Gemfile.lock
+.rvmrc
+Gemfile.lock
+tags
+.ruby-version

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+
+before_install:
+  - gem update bundler # -v 1.7.14 if a specific version is needed
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - jruby-19mode

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Tamber, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,223 @@
+# Tamber API Client for Ruby  [![Build Status](https://travis-ci.org/tamber/tamber-ruby.svg?branch=master)](https://travis-ci.org/tamber/tamber-ruby)
+
+Recommendation engines for developers, easy as π. Build blazing fast, head-scratchingly accurate hosted recommendation engines in minutes.
+
+The Tamber iOS SDK makes it easy to track events (user-item interactions) and get recommendations for your users inside your iOS app. 
+
+[Get a free api key][homepage] to get started.
+
+## Documentation
+
+See [full API documentation][reference].
+
+## Installation
+
+To use the Tamber Ruby bindings, you should run:
+
+```
+gem install tamber
+```
+
+If you want to build the gem from source:
+
+```
+gem build tamber.gemspec
+```
+
+## Compatibility
+
+We are compatible with Ruby 1.9.3 and above.
+
+
+## Usage
+
+If you are just getting started, check out the [Quick Start][quickstart] guide for instructions on how to get setup.
+
+*We recommend tracking events from the client-side so that Tamber can learn from clicks/views, guest users, and contextual data. Use our [iOS][tamber-ios], [Node][tamber-node], or [javascript][tamber-js] SDKs to start tracking.* 
+
+Of course, you can also track events from your backend.
+
+### Track Events
+
+```rb
+require 'tamber'
+Tamber.project_key = 'your_project_key'
+
+begin
+  Tamber::Event.track(
+    user: 'user_rlox8k927z7p',
+    behavior: 'like'
+    item:  'item_wmt4fn6o4zlk',
+    context: ["homepage", "featured_section"]
+  )
+rescue TamberError => error
+  puts error.message
+end
+```
+
+
+### Get Recommendations
+
+Once you have tracked enough events and created your engine, it's time to put personalized recommendations in your app.
+
+The primary method of discovery in Tamber is the `Discover.next` method, which returns the optimal set of items that the user should be shown next.
+
+#### For You
+
+To put personalized recommendations on your homepage, or in any recommended section, just call `Discover.next` with the number of recommendations you want to display (if you are calling server-side, also set the `user`).
+
+```rb
+Tamber.project_key = 'your_project_key'
+
+begin
+  d = Tamber::Discover.next(
+    user: 'user_rlox8k927z7p',
+    number: 10
+  )
+  d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+```
+
+##### `continuation`
+
+`Discover.next` is optimized for the exact moment and context of the user at the time of request, so standard pagination is not possible. Instead, `Discover.next` uses automatic continuation to allow you to 'show more' or implement infinite scrolling. 
+
+When you want to add more recommendations to those currently displayed to the user, just set the `continuation` field to `true`. Tamber will automatically generate the set of items that should be appended to the current user-session's list. The `Discover.next` user-session is reset when `Discover.next` is called without `continuation`.
+
+```rb
+Tamber.project_key = 'your_project_key'
+
+begin
+  d = Tamber::Discover.next(
+    user: 'user_rlox8k927z7p',
+    number: 10,
+    continuation: true
+  )
+  d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+```
+
+#### Up Next
+
+Keep users engaged by creating a path of discovery as they navigate from item to item. Just add the id of the item that the user is navigating to / looking at.
+
+```rb
+begin
+  d = Tamber::Discover.next(
+    user: 'user_rlox8k927z7p',
+    item: 'item_wmt4fn6o4zlk',
+    number: 14
+  )
+  d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+```
+
+If you are tracking events in your backend and want to track `clicked` or `viewed` events when users request the next page, you can also get `next` for the user-item pair by adding the `get_recs` field to your `Event.track` call.
+
+```rb
+begin
+  e = Tamber::Event.track(
+    user: 'user_rlox8k927z7p',
+    behavior: 'clicked'
+    item:  'item_wmt4fn6o4zlk',
+    get_recs: {
+      number: 14
+    }
+  )
+  e.recommended.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+```
+
+#### Trending
+
+Help your users keep their fingers on the pulse of your platform by showing them the hottest, most popular, newest, or most up-and-coming items.
+
+```rb
+begin
+  d = Tamber::Discover.hot() // the hottest (trending) items
+  d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+end
+
+begin
+  d = Tamber::Discover.popular() // the hottest (trending) items
+end
+
+# BETA endpoints
+begin
+  d = Tamber::Discover.uac() // the most up-and-coming items
+end
+
+begin
+  d = Tamber::Discover.new() // the newest items
+end
+```
+
+#### Build Your Own Features
+
+Tamber allows you to use lower-level methods to get lists of recommended items, similar item matches, and similar items for a given user with which you can build your own discovery experiences. Importantly, these methods return raw recommendation data and are not intended to be pushed directly to users.
+
+```rb
+begin
+  Tamber::Discover.recommended(user: 'user_rlox8k927z7p').each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+
+begin
+  Tamber::Discover.similar(item: 'item_wmt4fn6o4zlk').each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+
+begin
+  Tamber::Discover.recommendedSimilar(
+    user: 'user_rlox8k927z7p',
+    item: 'item_wmt4fn6o4zlk'
+  ).each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+rescue TamberError => error
+  puts error.message
+end
+```
+
+### Sync Items (optional)
+
+Keep Tamber in sync with your item data in order to use recommendation filtering. Just call `Item.update` wherever you create and update items in your backend. If you have a Database module, we recommend adding this method there.
+
+```rb
+require 'tamber'
+Tamber.project_key = 'your_project_key'
+
+begin
+  Tamber::Item.update(
+    id: 'item_wmt4fn6o4zlk',
+    updates: {
+      add: {
+        properties: {
+          'available_large': false,
+          'stock': 89
+        }
+      }
+    }
+  )
+rescue TamberError => error
+  puts error.message
+end
+```
+
+See [Tests](https://github.com/tamber/tamber-ruby/tree/master/test) for more examples.
+
+[homepage]: https://tamber.com
+[quickstart]: https://tamber.com/docs/start/
+[reference]: https://tamber.com/docs/api
+[dashboard]: https://dashboard.tamber.com/
+[tamber-ios]: https://github.com/tamber/tamber-ios
+[tamber-node]: https://github.com/tamber/tamber-node
+[tamber-js]: https://github.com/tamber/tamber.js

data/README.rdoc

@@ -0,0 +1,196 @@
+= Tamber API Client for Ruby {<img src="https://travis-ci.org/tamber/tamber-ruby.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/tamber/tamber-ruby]
+
+Recommendation engines for developers, easy as π. Build blazing fast, head-scratchingly accurate hosted recommendation engines in minutes.
+
+The Tamber iOS SDK makes it easy to track events (user-item interactions) and get recommendations for your users inside your iOS app. 
+
+{Get a free api key}[https://tamber.com] to get started.
+
+== Documentation
+
+See {full API documentation}[https://tamber.com/docs/api].
+
+== Installation
+
+To use the Tamber Ruby bindings, you should run:
+
+  gem install tamber
+
+If you want to build the gem from source:
+
+  gem build tamber.gemspec
+
+
+== Compatibility
+
+We are compatible with Ruby 1.9.3 and above.
+
+
+== Usage
+
+If you are just getting started, check out the {Quick Start}[https://tamber.com/docs/start/] guide for instructions on how to get setup.
+
+*We recommend tracking events from the client-side so that Tamber can learn from clicks/views, guest users, and contextual data. Use our {iOS}[https://github.com/tamber/tamber-ios], {Node}[https://github.com/tamber/tamber-node], or {javascript}[https://github.com/tamber/tamber.js] SDKs to start tracking.* 
+
+Of course, you can also track events from your backend.
+
+=== Track Events
+
+  require 'tamber'
+  Tamber.project_key = 'your_project_key'
+
+  begin
+    Tamber::Event.track(
+      user: 'user_rlox8k927z7p',
+      behavior: 'like'
+      item:  'item_wmt4fn6o4zlk',
+      context: ["homepage", "featured_section"]
+    )
+  rescue TamberError => error
+    puts error.message
+  end
+
+
+=== Get Recommendations
+
+Once you have tracked enough events and created your engine, it's time to put personalized recommendations in your app.
+
+The primary method of discovery in Tamber is the `Discover.next` method, which returns the optimal set of items that the user should be shown next.
+
+==== For You
+
+To put personalized recommendations on your homepage, or in any recommended section, just call `Discover.next` with the number of recommendations you want to display (if you are calling server-side, also set the `user`).
+
+  Tamber.project_key = 'your_project_key'
+
+  begin
+    d = Tamber::Discover.next(
+      user: 'user_rlox8k927z7p',
+      number: 10
+    )
+    d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+===== `continuation`
+
+`Discover.next` is optimized for the exact moment and context of the user at the time of request, so standard pagination is not possible. Instead, `Discover.next` uses automatic continuation to allow you to 'show more' or implement infinite scrolling. 
+
+When you want to add more recommendations to those currently displayed to the user, just set the `continuation` field to `true`. Tamber will automatically generate the set of items that should be appended to the current user-session's list. The `Discover.next` user-session is reset when `Discover.next` is called without `continuation`.
+
+Tamber.project_key = 'your_project_key'
+
+  begin
+    d = Tamber::Discover.next(
+      user: 'user_rlox8k927z7p',
+      number: 10,
+      continuation: true
+    )
+    d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+==== Up Next
+
+Keep users engaged by creating a path of discovery as they navigate from item to item. Just add the id of the item that the user is navigating to / looking at.
+
+  begin
+    d = Tamber::Discover.next(
+      user: 'user_rlox8k927z7p',
+      item: 'item_wmt4fn6o4zlk',
+      number: 14
+    )
+    d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+If you are tracking events in your backend and want to track `clicked` or `viewed` events when users request the next page, you can also get `next` for the user-item pair by adding the `get_recs` field to your `Event.track` call.
+
+  begin
+    e = Tamber::Event.track(
+      user: 'user_rlox8k927z7p',
+      behavior: 'clicked'
+      item:  'item_wmt4fn6o4zlk',
+      get_recs: {
+        number: 14
+      }
+    )
+    e.recommended.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+==== Trending
+
+Help your users keep their fingers on the pulse of your platform by showing them the hottest, most popular, newest, or most up-and-coming items.
+
+  begin
+    d = Tamber::Discover.hot() // the hottest (trending) items
+    d.each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  end
+
+  begin
+    d = Tamber::Discover.popular() // the hottest (trending) items
+  end
+
+  // BETA endpoints
+  begin
+    d = Tamber::Discover.uac() // the most up-and-coming items
+  end
+
+  begin
+    d = Tamber::Discover.new() // the newest items
+  end
+
+==== Build Your Own Features
+
+Tamber allows you to use lower-level methods to get lists of recommended items, similar item matches, and similar items for a given user with which you can build your own discovery experiences. Importantly, these methods return raw recommendation data and are not intended to be pushed directly to users.
+
+  begin
+    Tamber::Discover.recommended(user: 'user_rlox8k927z7p').each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+  begin
+    Tamber::Discover.similar(item: 'item_wmt4fn6o4zlk').each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+  begin
+    Tamber::Discover.recommendedSimilar(
+      user: 'user_rlox8k927z7p',
+      item: 'item_wmt4fn6o4zlk'
+    ).each { |rec| puts "item: #{rec.item}, score: #{rec.score}"}
+  rescue TamberError => error
+    puts error.message
+  end
+
+=== Sync Items (optional)
+
+Keep Tamber in sync with your item data in order to use recommendation filtering. Just call `Item.update` wherever you create and update items in your backend. If you have a Database module, we recommend adding this method there.
+
+  require 'tamber'
+  Tamber.project_key = 'your_project_key'
+
+  begin
+    Tamber::Item.update(
+      id: 'item_wmt4fn6o4zlk',
+      updates: {
+        add: {
+          properties: {
+            'available_large': false,
+            'stock': 89
+          }
+        }
+      }
+    )
+  rescue TamberError => error
+    puts error.message
+  end
+
+See {Tests}[https://github.com/tamber/tamber-ruby/tree/master/test] for more examples.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.pattern = './test/*_test.rb'
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.7