additionalData for interactions, returnAbGroup for recommendation endpoints

Author: OndraFiedler

README.md

@@ -29,7 +29,7 @@ Or install it yourself as:
 require 'recombee_api_client'
 include RecombeeApiClient
 
-client = RecombeeClient('--my-database-id--', '--my-secret-token--')
+client = RecombeeClient('--my-database-id--', '--db-private-token--')
 
 # Generate some random purchases of items by users
 NUM = 100
@@ -71,7 +71,7 @@ include RecombeeApiClient
 NUM = 100
 PROBABILITY_PURCHASED = 0.1
 
-client = RecombeeClient('--my-database-id--', '--my-secret-token--')
+client = RecombeeClient('--my-database-id--', '--db-private-token--')
 client.send(ResetDatabase.new) # Clear everything from the database
 
 # We will use computers as items in this example

lib/recombee_api_client.rb

@@ -18,7 +18,7 @@ class RecombeeClient
     include HTTParty
 
     BATCH_MAX_SIZE = 10000
-    USER_AGENT = {'User-Agent' => 'recombee-ruby-api-client/2.2.0'}
+    USER_AGENT = {'User-Agent' => 'recombee-ruby-api-client/2.3.0'}
 
     ##
     #   - +account+ -> Name of your account at Recombee

lib/recombee_api_client/api/add_bookmark.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a bookmark of a given item made by a given user.
   #
   class AddBookmark < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -23,6 +23,7 @@ class AddBookmark < ApiRequest
   #   - +timestamp+ -> UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
   #   - +cascadeCreate+ -> Sets whether the given user/item should be created if not present in the database.
   #   - +recommId+ -> If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -31,11 +32,12 @@ def initialize(user_id, item_id, optional = {})
       @timestamp = optional['timestamp']
       @cascade_create = optional['cascadeCreate']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId","additionalData"].include? par
       end
     end
 
@@ -52,6 +54,7 @@ def body_parameters
       p['timestamp'] = @optional['timestamp'] if @optional.include? 'timestamp'
       p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
 

lib/recombee_api_client/api/add_cart_addition.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a cart addition of a given item made by a given user.
   #
   class AddCartAddition < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -25,6 +25,7 @@ class AddCartAddition < ApiRequest
   #   - +amount+ -> Amount (number) added to cart. The default is 1. For example if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal to 2.
   #   - +price+ -> Price of the added item. If `amount` is greater than 1, sum of prices of all the items should be given.
   #   - +recommId+ -> If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -35,11 +36,12 @@ def initialize(user_id, item_id, optional = {})
       @amount = optional['amount']
       @price = optional['price']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","recommId","additionalData"].include? par
       end
     end
 
@@ -58,6 +60,7 @@ def body_parameters
       p['amount'] = @optional['amount'] if @optional.include? 'amount'
       p['price'] = @optional['price'] if @optional.include? 'price'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
 

lib/recombee_api_client/api/add_detail_view.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a detail view of a given item made by a given user.
   #
   class AddDetailView < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :duration, :cascade_create, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :duration, :cascade_create, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -24,6 +24,7 @@ class AddDetailView < ApiRequest
   #   - +duration+ -> Duration of the view
   #   - +cascadeCreate+ -> Sets whether the given user/item should be created if not present in the database.
   #   - +recommId+ -> If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -33,11 +34,12 @@ def initialize(user_id, item_id, optional = {})
       @duration = optional['duration']
       @cascade_create = optional['cascadeCreate']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","duration","cascadeCreate","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","duration","cascadeCreate","recommId","additionalData"].include? par
       end
     end
 
@@ -55,6 +57,7 @@ def body_parameters
       p['duration'] = @optional['duration'] if @optional.include? 'duration'
       p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
 

lib/recombee_api_client/api/add_purchase.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a purchase of a given item made by a given user.
   #
   class AddPurchase < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :profit, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :cascade_create, :amount, :price, :profit, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -26,6 +26,7 @@ class AddPurchase < ApiRequest
   #   - +price+ -> Price paid by the user for the item. If `amount` is greater than 1, sum of prices of all the items should be given.
   #   - +profit+ -> Your profit from the purchased item. The profit is natural in e-commerce domain (for example if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30), but is applicable also in other domains (for example at a news company it may be income from displayed advertisement on article page). If `amount` is greater than 1, sum of profit of all the items should be given.
   #   - +recommId+ -> If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, optional = {})
       @user_id = user_id
@@ -37,11 +38,12 @@ def initialize(user_id, item_id, optional = {})
       @price = optional['price']
       @profit = optional['profit']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","profit","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","amount","price","profit","recommId","additionalData"].include? par
       end
     end
 
@@ -61,6 +63,7 @@ def body_parameters
       p['price'] = @optional['price'] if @optional.include? 'price'
       p['profit'] = @optional['profit'] if @optional.include? 'profit'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
 

lib/recombee_api_client/api/add_rating.rb

@@ -10,7 +10,7 @@ module RecombeeApiClient
   #Adds a rating of given item made by a given user.
   #
   class AddRating < ApiRequest
-    attr_reader :user_id, :item_id, :timestamp, :rating, :cascade_create, :recomm_id
+    attr_reader :user_id, :item_id, :timestamp, :rating, :cascade_create, :recomm_id, :additional_data
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -24,6 +24,7 @@ class AddRating < ApiRequest
   #   - +timestamp+ -> UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
   #   - +cascadeCreate+ -> Sets whether the given user/item should be created if not present in the database.
   #   - +recommId+ -> If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.
+  #   - +additionalData+ -> A dictionary of additional data for the interaction.
   #
     def initialize(user_id, item_id, rating, optional = {})
       @user_id = user_id
@@ -33,11 +34,12 @@ def initialize(user_id, item_id, rating, optional = {})
       @timestamp = optional['timestamp']
       @cascade_create = optional['cascadeCreate']
       @recomm_id = optional['recommId']
+      @additional_data = optional['additionalData']
       @optional = optional
       @timeout = 1000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["timestamp","cascadeCreate","recommId","additionalData"].include? par
       end
     end
 
@@ -55,6 +57,7 @@ def body_parameters
       p['timestamp'] = @optional['timestamp'] if @optional.include? 'timestamp'
       p['cascadeCreate'] = @optional['cascadeCreate'] if @optional.include? 'cascadeCreate'
       p['recommId'] = @optional['recommId'] if @optional.include? 'recommId'
+      p['additionalData'] = @optional['additionalData'] if @optional.include? 'additionalData'
       p
     end
 

lib/recombee_api_client/api/recommend_items_to_item.rb

@@ -11,8 +11,10 @@ module RecombeeApiClient
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
   #
+  #The returned items are sorted by relevancy (first item being the most relevant).
+  #
   class RecommendItemsToItem < ApiRequest
-    attr_reader :item_id, :target_user_id, :count, :user_impact, :filter, :booster, :cascade_create, :scenario, :return_properties, :included_properties, :diversity, :min_relevance, :rotation_rate, :rotation_time, :expert_settings
+    attr_reader :item_id, :target_user_id, :count, :user_impact, :filter, :booster, :cascade_create, :scenario, :return_properties, :included_properties, :diversity, :min_relevance, :rotation_rate, :rotation_time, :expert_settings, :return_ab_group
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -112,6 +114,8 @@ class RecommendItemsToItem < ApiRequest
   #
   #   - +expertSettings+ -> Dictionary of custom options.
   #
+  #   - +returnAbGroup+ -> If there is a custom AB-testing running, return name of group to which the request belongs.
+  #
   #
     def initialize(item_id, target_user_id, count, optional = {})
       @item_id = item_id
@@ -130,11 +134,12 @@ def initialize(item_id, target_user_id, count, optional = {})
       @rotation_rate = optional['rotationRate']
       @rotation_time = optional['rotationTime']
       @expert_settings = optional['expertSettings']
+      @return_ab_group = optional['returnAbGroup']
       @optional = optional
       @timeout = 3000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["userImpact","filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","minRelevance","rotationRate","rotationTime","expertSettings"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["userImpact","filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","minRelevance","rotationRate","rotationTime","expertSettings","returnAbGroup"].include? par
       end
     end
 
@@ -160,6 +165,7 @@ def body_parameters
       p['rotationRate'] = @optional['rotationRate'] if @optional.include? 'rotationRate'
       p['rotationTime'] = @optional['rotationTime'] if @optional.include? 'rotationTime'
       p['expertSettings'] = @optional['expertSettings'] if @optional.include? 'expertSettings'
+      p['returnAbGroup'] = @optional['returnAbGroup'] if @optional.include? 'returnAbGroup'
       p
     end
 

lib/recombee_api_client/api/recommend_items_to_user.rb

@@ -11,8 +11,10 @@ module RecombeeApiClient
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
   #
+  #The returned items are sorted by relevancy (first item being the most relevant).
+  #
   class RecommendItemsToUser < ApiRequest
-    attr_reader :user_id, :count, :filter, :booster, :cascade_create, :scenario, :return_properties, :included_properties, :diversity, :min_relevance, :rotation_rate, :rotation_time, :expert_settings
+    attr_reader :user_id, :count, :filter, :booster, :cascade_create, :scenario, :return_properties, :included_properties, :diversity, :min_relevance, :rotation_rate, :rotation_time, :expert_settings, :return_ab_group
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -92,6 +94,8 @@ class RecommendItemsToUser < ApiRequest
   #
   #   - +expertSettings+ -> Dictionary of custom options.
   #
+  #   - +returnAbGroup+ -> If there is a custom AB-testing running, return name of group to which the request belongs.
+  #
   #
     def initialize(user_id, count, optional = {})
       @user_id = user_id
@@ -108,11 +112,12 @@ def initialize(user_id, count, optional = {})
       @rotation_rate = optional['rotationRate']
       @rotation_time = optional['rotationTime']
       @expert_settings = optional['expertSettings']
+      @return_ab_group = optional['returnAbGroup']
       @optional = optional
       @timeout = 3000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","minRelevance","rotationRate","rotationTime","expertSettings"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","minRelevance","rotationRate","rotationTime","expertSettings","returnAbGroup"].include? par
       end
     end
 
@@ -136,6 +141,7 @@ def body_parameters
       p['rotationRate'] = @optional['rotationRate'] if @optional.include? 'rotationRate'
       p['rotationTime'] = @optional['rotationTime'] if @optional.include? 'rotationTime'
       p['expertSettings'] = @optional['expertSettings'] if @optional.include? 'expertSettings'
+      p['returnAbGroup'] = @optional['returnAbGroup'] if @optional.include? 'returnAbGroup'
       p
     end
 

lib/recombee_api_client/api/recommend_users_to_item.rb

@@ -11,8 +11,10 @@ module RecombeeApiClient
   #
   #It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
   #
+  #The returned users are sorted by predicted interest in the item (first user being the most interested).
+  #
   class RecommendUsersToItem < ApiRequest
-    attr_reader :item_id, :count, :filter, :booster, :cascade_create, :scenario, :return_properties, :included_properties, :diversity, :expert_settings
+    attr_reader :item_id, :count, :filter, :booster, :cascade_create, :scenario, :return_properties, :included_properties, :diversity, :expert_settings, :return_ab_group
     attr_accessor :timeout
     attr_accessor :ensure_https
 
@@ -80,6 +82,8 @@ class RecommendUsersToItem < ApiRequest
   #
   #   - +expertSettings+ -> Dictionary of custom options.
   #
+  #   - +returnAbGroup+ -> If there is a custom AB-testing running, return name of group to which the request belongs.
+  #
   #
     def initialize(item_id, count, optional = {})
       @item_id = item_id
@@ -93,11 +97,12 @@ def initialize(item_id, count, optional = {})
       @included_properties = optional['includedProperties']
       @diversity = optional['diversity']
       @expert_settings = optional['expertSettings']
+      @return_ab_group = optional['returnAbGroup']
       @optional = optional
       @timeout = 50000
       @ensure_https = false
       @optional.each do |par, _|
-        fail UnknownOptionalParameter.new(par) unless ["filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","expertSettings"].include? par
+        fail UnknownOptionalParameter.new(par) unless ["filter","booster","cascadeCreate","scenario","returnProperties","includedProperties","diversity","expertSettings","returnAbGroup"].include? par
       end
     end
 
@@ -118,6 +123,7 @@ def body_parameters
       p['includedProperties'] = @optional['includedProperties'] if @optional.include? 'includedProperties'
       p['diversity'] = @optional['diversity'] if @optional.include? 'diversity'
       p['expertSettings'] = @optional['expertSettings'] if @optional.include? 'expertSettings'
+      p['returnAbGroup'] = @optional['returnAbGroup'] if @optional.include? 'returnAbGroup'
       p
     end