promoted-ruby-client 0.1.18 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c49d0a2668c2ac163b2fb9bbfb13fcff75d6a4f558b8e62b633bc590d094c269
-  data.tar.gz: c0bc6218512f2883bd2fcbdfc60d4f5a9da05b93a9872bd60c1ce65bbd1d6ec9
+  metadata.gz: e4cc088a08f160f3a238022f030e042df9a583fdbe22310b007027a9b908b406
+  data.tar.gz: 3b9434274cef7986cceea4876170b9061d873bfa533f0047adff546fd1f20d77
 SHA512:
-  metadata.gz: d92f40acf137305cbce1c2e66d3f9b40d9ed5d58f97fc84b0beb2a9ecc7a47671316c012c36279bdbed401f8d1f81001dcbf352f70507593c48d14cbd829e6b1
-  data.tar.gz: 0fddc62d1ea650b98653b8f05680d15e9245d0259c835408113c4b4dbab4baa16360735755656d7fec42466e2254bf3fd69e7187f3dbc44e97f1b435b94afbab
+  metadata.gz: b9b3a44c22c7bbbb632024b21aa6062253f2cd9e6f3cba73f015eccb1f4fa3a91bfc14cfdabee57a64510ae53a16fe2f01e30f645002b1dc40ea511f8854e54b
+  data.tar.gz: d20bb330c762ea83cf75246a256a20d250d1d3b0e2b1af7fa7ca8d2f5840671505a10584c2d8c3f30fa040daf7d10bbdcd5859454dd822c7898b711e300257eb

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    promoted-ruby-client (0.1.18)
+    promoted-ruby-client (0.1.22)
       concurrent-ruby (~> 1)
       faraday (>= 0.9.0)
       faraday_middleware (>= 0.9.0)

data/README.md

@@ -49,6 +49,7 @@ Name | Type | Description
 ```:perform_checks``` | Boolean | Whether or not to perform detailed input validation, defaults to true but may be disabled for performance
 ```:logger``` | Ruby Logger-compatible logger | Defaults to nil (no logging). Example: ```Logger.new(STDERR, :progname => 'promotedai')```
 ```:shadow_traffic_delivery_percent``` | Number between 0 and 1 | % of ```prepare_for_logging``` traffic that gets directed to Delivery API as "shadow traffic". Defaults to 0 (no shadow traffic).
+```:send_shadow_traffic_for_control``` | Boolean | If true, the ```deliver``` method will send shadow traffic for users in the CONTROL arm of an experiment. Defaults to true.
 ```:default_request_headers``` | Hash | Additional headers to send on the request beyond ```x-api-key```. Defaults to {}
 ```:default_only_log``` | Boolean | If true, the ```deliver``` method will not direct traffic to Delivery API but rather return a request suitable for logging. Defaults to false.
 ```:should_apply_treatment_func``` | Proc | Called during delivery, accepts an experiment and returns a Boolean indicating whether the request should be considered part of the control group (false) or in the experiment (true). If nil, the default behavior of checking the experiement ```:arm``` is applied.
@@ -62,6 +63,7 @@ Field Name | Type | Optional? | Description
 ---------- | ---- | --------- | -----------
 ```:user_id``` | String | Yes | The platform user id, cleared from Promoted logs.
 ```:log_user_id``` | String | Yes | A different user id (presumably a UUID) disconnected from the platform user id, good for working with unauthenticated users or implementing right-to-be-forgotten.
+```:is_internal_user``` | Boolean | Yes | If this user is a test user or not, defaults to false.
 
 ---
 ### CohortMembership
@@ -93,8 +95,76 @@ Field Name | Type | Optional? | Description
 ```:insertion_id``` | String | Yes | Generated by the SDK (*do not set*)
 ```:request_id``` | String | Yes | Generated by the SDK when needed (*do not set*)
 ```:content_id``` | String | No | Identifier for the content to be shown, must be set.
+```:retrieval_rank``` | Number | Yes | Optional original ranking of this content item.
+```:retrieval_score``` | Number | Yes | Optional original quality score of this content item.
 ```:properties``` | Properties | Yes | Any additional custom properties to associate. For v1 integrations, it is fine not to fill in all the properties.
+---
+### Size
+User's screen dimensions.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:width``` | Integer | No | Screen width
+```:height``` | Integer | No | Screen height
+---
 
+### Screen
+State of the screen including scaling.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:size``` | Size | Yes | Screen size
+```:scale``` | Float | Yes | Current screen scaling factor
+---
+
+### ClientHints
+Alternative to user-agent strings. See https://raw.githubusercontent.com/snowplow/iglu-central/master/schemas/org.ietf/http_client_hints/jsonschema/1-0-0
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:is_mobile``` | Boolean | Yes | Mobile flag
+```:brand``` | Array of ClientBrandHint | Yes |
+```:architecture``` | String | Yes |
+```:model``` | String | Yes |
+```:platform``` | String | Yes |
+```:platform_version``` | String | Yes |
+```:ua_full_version``` | String | Yes |
+
+---
+### ClientBrandHint
+See https://raw.githubusercontent.com/snowplow/iglu-central/master/schemas/org.ietf/http_client_hints/jsonschema/1-0-0
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:brand``` | String | Yes | Mobile flag
+```:version``` | String | Yes |
+
+---
+### Location
+Information about the user's location.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:latitude``` | Float | No | Location latitude
+```:longitude``` | Float | No | Location longitude
+```:accuracy_in_meters``` | Integer | Yes | Location accuracy if available
+---
+
+### Browser
+Information about the user's browser.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_agent``` | String | Yes | Browser user agent string
+```:viewport_size``` | Size | Yes | Size of the browser viewport
+```:client_hints``` | ClientHints | Yes | HTTP client hints structure
+---
+### Device
+Information about the user's device.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:device_type``` | one of (`UNKNOWN_DEVICE_TYPE`, `DESKTOP`, `MOBILE`, `TABLET`) | Yes | Type of device
+```:brand``` | String | Yes | "Apple, "google", Samsung", etc.
+```:manufacturer``` | String | Yes | "Apple", "HTC", Motorola", "HUAWEI", etc.
+```:identifier``` | String | Yes | Android: android.os.Build.MODEL; iOS: iPhoneXX,YY, etc.
+```:screen``` | Screen | Yes | Screen dimensions
+```:ip_address``` | String | Yes | Originating IP address
+```:location``` | Location | Yes | Location information
+```:browser``` | Browser | Yes | Browser information
 ---
 ### Paging
 #### TODO
@@ -108,6 +178,7 @@ Field Name | Type | Optional? | Description
 ```:use_case``` | String | Yes | One of the use case values, i.e. 'FEED' (see [constants.rb](https://github.com/promotedai/promoted-ruby-client/blob/main/lib/promoted/ruby/client/constants.rb)).
 ```:properties``` | Properties | Yes | Any additional custom properties to associate.
 ```:paging``` | Paging | Yes | Paging parameters (see TODO)
+```:device``` | Device | Yes | Device information (as available)
 ---
 ### MetricsRequest
 Input to ```prepare_for_logging```
@@ -142,6 +213,8 @@ Field Name | Type | Optional? | Description
 ---------- | ---- | --------- | -----------
 ```:insertion``` | [] of Insertion | No | The insertions, which are from Delivery API (when ```deliver``` was called, i.e. we weren't either only-log or part of an experiment) or the input insertions (when the other conditions don't hold).
 ```:log_request``` | LogRequest | Yes | A message suitable for logging to Metrics API via ```send_log_request```. If the call to ```deliver``` was made (i.e. the request was not part of the CONTROL arm of an experiment or marked to only log), ```:log_request``` will not be set, as you can assume logging was performed on the server-side by Promoted.
+```:client_request_id``` | String | Yes | Client-generated request id sent to Delivery API and may be useful for logging and debugging.
+```:execution_server``` | one of 'API' or 'SDK' | Yes | Indicates if response insertions on a delivery request came from the API or the SDK.
 ---
 
 ### PromotedClient

data/dev.md

@@ -4,5 +4,5 @@
 2. Get credentials for deployment from 1password.
 3. Modify `promoted-ruby-client.gemspec`'s push block.
 4. Run `gem build promoted-ruby-client.gemspec` to generate `gem`.
-5. Run (using new output) `gem push promoted-ruby-client-0.1.18.gem`
+5. Run (using new output) `gem push promoted-ruby-client-0.1.22.gem`
 6. Update README with new version.

data/lib/promoted/ruby/client/constants.rb

@@ -32,6 +32,13 @@ module Promoted
       CLIENT_TYPE = {'UNKNOWN_REQUEST_CLIENT' => 'UNKNOWN_REQUEST_CLIENT',
                      'PLATFORM_SERVER' => 'PLATFORM_SERVER',
                      'PLATFORM_CLIENT' => 'PLATFORM_CLIENT'}
+
+      EXECUTION_SERVER = {'API' => 'API', 'SDK' => 'SDK'}
+
+      DEVICE_TYPE = {'UNKNOWN_DEVICE_TYPE' => 'UNKNOWN_DEVICE_TYPE',
+                     'DESKTOP' => 'DESKTOP',
+                     'MOBILE' => 'MOBILE',
+                     'TABLET' => 'TABLET'}
     end
   end
 end

data/lib/promoted/ruby/client/pager.rb

@@ -11,13 +11,13 @@ module Promoted
         end
         
         class Pager
-            def validate_paging (insertions, paging)
+            def validate_paging(insertions, paging)
               if paging && paging[:offset] && paging[:offset] >= insertions.length
                 raise InvalidPagingError.new("Invalid page offset (insertion size #{insertions.length}, offset #{paging[:offset]})", [])
               end
             end
 
-            def apply_paging (insertions, insertion_page_type, paging = nil)
+            def apply_paging(insertions, insertion_page_type, paging = nil)
               begin
                 validate_paging(insertions, paging)
               rescue InvalidPagingError => err
@@ -47,7 +47,7 @@ module Promoted
                 size = insertions.length
               end
 
-              final_insertion_size = [size, insertions.length].min
+              final_insertion_size = [size, insertions.length - index].min
               insertion_page = Array.new(final_insertion_size)
               0.upto(final_insertion_size - 1) {|i|
                 insertion = insertions[index]
@@ -63,5 +63,5 @@ module Promoted
             end
         end
       end
-   end
+    end
 end

data/lib/promoted/ruby/client/request_builder.rb

@@ -2,7 +2,7 @@ module Promoted
   module Ruby
     module Client
       class RequestBuilder
-        attr_reader   :session_id, :only_log, :experiment, :client_info,
+        attr_reader   :session_id, :only_log, :experiment, :client_info, :device,
                       :view_id, :insertion, :to_compact_delivery_properties_func,
                       :request_id, :full_insertion, :use_case, :request, :to_compact_metrics_properties_func
 
@@ -24,6 +24,7 @@ module Promoted
           @session_id              = request[:session_id]
           @platform_id             = request[:platform_id]
           @client_info             = request[:client_info] || {}
+          @device                  = request[:device] || {}
           @view_id                 = request[:view_id]
           @use_case                = Promoted::Ruby::Client::USE_CASES[request[:use_case]] || Promoted::Ruby::Client::USE_CASES['UNKNOWN_USE_CASE']
           @full_insertion          = args[:full_insertion]
@@ -56,7 +57,8 @@ module Promoted
           params = {
             user_info: user_info,
             timing: timing,
-            client_info: @client_info.merge({ :client_type => Promoted::Ruby::Client::CLIENT_TYPE['PLATFORM_SERVER'] }),
+            client_info: merge_client_info_defaults,
+            device: @device,
             platform_id: @platform_id,
             view_id: @view_id,
             session_id: @session_id,
@@ -64,7 +66,7 @@ module Promoted
             search_query: request[:search_query],
             properties: request[:properties],
             paging: request[:paging],
-            client_request_id: request[:client_request_id]
+            client_request_id: client_request_id
           }
           params[:insertion] = insertions_with_compact_props(@to_compact_delivery_properties_func)
 
@@ -76,7 +78,7 @@ module Promoted
         # to the responses.
         def fill_details_from_response response_insertions
           if !response_insertions then
-            response_insertions = full_insertion
+            response_insertions = []
           end
 
           props = @full_insertion.each_with_object({}) do |insertion, hash|
@@ -102,7 +104,8 @@ module Promoted
           params = {
             user_info: user_info,
             timing: timing,
-            client_info: @client_info
+            client_info: merge_client_info_defaults,
+            device: @device
           }
 
           if @experiment
@@ -175,7 +178,6 @@ module Promoted
             insertion_obj                = Hash[insertion_obj]
             insertion_obj[:user_info]    = user_info
             insertion_obj[:timing]       = timing
-            insertion_obj[:insertion_id] = @id_generator.newID
             insertion_obj[:request_id]   = request_id
             insertion_obj[:position]     = offset + index
             insertion_obj                = compact_one_insertion(insertion_obj, @to_compact_metrics_properties_func)
@@ -184,14 +186,31 @@ module Promoted
           @insertion
         end
 
+        def add_missing_insertion_ids! insertions
+          insertions.each do |insertion|
+            insertion[:insertion_id] = @id_generator.newID if not insertion[:insertion_id]
+          end
+        end
+
+        def client_request_id
+          request[:client_request_id]
+        end
+
         private
 
+        def merge_client_info_defaults
+          return @client_info.merge({
+            :client_type => Promoted::Ruby::Client::CLIENT_TYPE['PLATFORM_SERVER'],
+            :traffic_type => Promoted::Ruby::Client::TRAFFIC_TYPE['PRODUCTION']
+          })
+        end
+        
         def add_missing_ids_on_insertions! request, insertions
           insertions.each do |insertion|
-            insertion[:insertion_id] = @id_generator.newID if not insertion[:insertion_id]
             insertion[:session_id] = request[:session_id] if request[:session_id]
             insertion[:request_id] = request[:request_id] if request[:request_id]
           end
+          add_missing_insertion_ids! insertions
         end
 
         # A list of the response Insertions.  This client expects lists to be truncated

data/lib/promoted/ruby/client/validator.rb

@@ -14,6 +14,10 @@ module Promoted
                         {
                             :name => :log_user_id,
                             :type => String
+                        },
+                        {
+                            :name => :is_internal_user,
+                            :type => [TrueClass, FalseClass]
                         }
                     ]
                 )
@@ -133,7 +137,6 @@ module Promoted
                 req[:full_insertion].each do |insertion_hash|
                   raise ValidationError.new("Insertion.requestId should not be set") if insertion_hash[:request_id]
                   raise ValidationError.new("'Insertion.insertionId should not be set") if insertion_hash[:insertion_id]
-                  raise ValidationError.new("Insertion.deliveryScore should not be set") if insertion_hash[:delivery_score]
                 end
             end
             
@@ -147,7 +150,11 @@ module Promoted
 
                     # If a field is provided as non-nil, it should be of the correct type.
                     if field[:type] && obj.has_key?(field[:name]) && obj[field[:name]] != nil then
-                        raise ValidationError.new(field[:name].to_s + " should be a " + field[:type].to_s) if !obj[field[:name]].is_a?(field[:type])
+                        if field[:type].is_a?(Array) then
+                            raise ValidationError.new(field[:name].to_s + " should be one of " + field[:type].to_s) if !field[:type].include?(obj[field[:name]].class)
+                        else
+                            raise ValidationError.new(field[:name].to_s + " should be a " + field[:type].to_s) if !obj[field[:name]].is_a?(field[:type])
+                        end
                     end
                 }
             end

data/lib/promoted/ruby/client/version.rb

@@ -1,7 +1,7 @@
 module Promoted
   module Ruby
     module Client
-      VERSION = "0.1.18"
+      VERSION = "0.1.22"
     end
   end
 end

data/lib/promoted/ruby/client.rb

@@ -19,7 +19,8 @@ module Promoted
         class Error < StandardError; end
 
         attr_reader :perform_checks, :default_only_log, :delivery_timeout_millis, :metrics_timeout_millis, :should_apply_treatment_func,
-                    :default_request_headers, :http_client, :logger, :shadow_traffic_delivery_percent, :async_shadow_traffic
+                    :default_request_headers, :http_client, :logger, :shadow_traffic_delivery_percent, :async_shadow_traffic,
+                    :send_shadow_traffic_for_control
                     
         attr_accessor :request_logging_on, :enabled
         
@@ -39,7 +40,7 @@ module Promoted
 
         ##
         # Create and configure a new Promoted client.
-        def initialize (params={})
+        def initialize(params={})
           @perform_checks = true
           if params[:perform_checks] != nil
             @perform_checks = params[:perform_checks]
@@ -79,6 +80,11 @@ module Promoted
             @async_shadow_traffic = params[:async_shadow_traffic] || false
           end
 
+          @send_shadow_traffic_for_control = true
+          if params[:send_shadow_traffic_for_control] != nil
+            @send_shadow_traffic_for_control = params[:send_shadow_traffic_for_control] || false
+          end
+
           @pool = nil
           if @async_shadow_traffic
             # Thread pool to process delivery of shadow traffic. Will silently drop excess requests beyond the queue
@@ -161,9 +167,8 @@ module Promoted
             cohort_membership_to_log = delivery_request_builder.new_cohort_membership_to_log
 
             if should_apply_treatment(cohort_membership_to_log)
-              delivery_request_params = delivery_request_builder.delivery_request_params
-  
-              # Call Delivery API
+              # Call Delivery API to get insertions to use
+              delivery_request_params = delivery_request_builder.delivery_request_params  
               begin
                 response = send_request(delivery_request_params, @delivery_endpoint, @delivery_timeout_millis, @delivery_api_key, headers)
               rescue  StandardError => err
@@ -172,17 +177,20 @@ module Promoted
                 deliver_err = true
                 @logger.error("Error calling delivery: " + err.message) if @logger
               end
-              
-              insertions_from_delivery = (response != nil && !deliver_err);
-              response_insertions = delivery_request_builder.fill_details_from_response(
-                response ? response[:insertion] : [])
+            elsif @send_shadow_traffic_for_control
+              # Call Delivery API to send shadow traffic. This will create the request params with traffic type set.
+              deliver_shadow_traffic args, headers
             end
+
+            insertions_from_delivery = (response != nil && !deliver_err);
+            response_insertions = delivery_request_builder.fill_details_from_response(
+              response && response[:insertion] || [])
           end
   
           request_to_log = nil
           if !insertions_from_delivery then
             request_to_log = delivery_request_builder.request
-            response_insertions = @pager.apply_paging(delivery_request_builder.full_insertion, Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'], delivery_request_builder.request[:paging])
+            response_insertions = build_sdk_response_insertions(delivery_request_builder)
           end
 
           log_req = nil
@@ -210,7 +218,9 @@ module Promoted
 
           client_response = {
             insertion: response_insertions,
-            log_request: log_req
+            log_request: log_req,
+            execution_server: insertions_from_delivery ? Promoted::Ruby::Client::EXECUTION_SERVER['API'] : Promoted::Ruby::Client::EXECUTION_SERVER['SDK'],
+            client_request_id: delivery_request_builder.client_request_id
           }
           return client_response
         end
@@ -264,6 +274,14 @@ module Promoted
 
         private
 
+        ##
+        # Creates response insertions for SDK-side delivery, when we don't get response insertions from Delivery API.
+        def build_sdk_response_insertions delivery_request_builder
+          response_insertions = @pager.apply_paging(delivery_request_builder.full_insertion, Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'], delivery_request_builder.request[:paging])
+          delivery_request_builder.add_missing_insertion_ids! response_insertions
+          return response_insertions
+        end
+        
         def do_warmup
           if !@delivery_endpoint
             # Warmup only supported when delivery is enabled.
@@ -316,7 +334,7 @@ module Promoted
 
             ellapsed_time = Time.now - start_time
             @logger.debug("Sync send_request completed in #{ellapsed_time.to_f * 1000} ms") if @logger
-        end
+          end
 
           return resp
         end
@@ -355,7 +373,7 @@ module Promoted
           
           if !@async_shadow_traffic
             ellapsed_time = Time.now - start_time
-            insertions = response ? response[:insertion] : []
+            insertions = response && response[:insertion] || []
             @logger.info("Shadow traffic call completed in #{ellapsed_time.to_f * 1000} ms with #{insertions.length} insertions") if @logger
           end
         end

data/promoted-ruby-client.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/promotedai/promoted-ruby-client'
   spec.license       = 'MIT'
 
+  spec.metadata["allowed_push_host"] = "https://rubygems.org/"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/promotedai/promoted-ruby-client"
   spec.metadata["changelog_uri"] = "https://github.com/promotedai/promoted-ruby-client/blob/master/CHANGELOG.md"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promoted-ruby-client
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.22
 platform: ruby
 authors:
 - scottmcmaster
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-03 00:00:00.000000000 Z
+date: 2021-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -150,6 +150,7 @@ homepage: https://github.com/promotedai/promoted-ruby-client
 licenses:
 - MIT
 metadata:
+  allowed_push_host: https://rubygems.org/
   homepage_uri: https://github.com/promotedai/promoted-ruby-client
   source_code_uri: https://github.com/promotedai/promoted-ruby-client
   changelog_uri: https://github.com/promotedai/promoted-ruby-client/blob/master/CHANGELOG.md
@@ -168,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.24
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: A Ruby Client to contact Promoted APIs.