optimizely-sdk 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8eff682f4c4c99808f246f2828a4e34e276e54b
-  data.tar.gz: 1c4de8ae37ce421199a1d66ea67c5e9ba78e1c41
+  metadata.gz: 164c4cd46301497d6ad393c5ed49093f9e72d337
+  data.tar.gz: b52ca87752dc4aa840e53c4be5ce7583604eb044
 SHA512:
-  metadata.gz: 32ad714501f8b55a48201653de322c2f47e33634d323bb653909307cfc289ceff833ba44508b823ecfe0a4ade94cae2aac8ecca5bd2d6ee350d1ec82977a2a69
-  data.tar.gz: 96297561d1ee0a395d35f8b9878ac71b2c097583442bf7327b01db773ef13b32a5aa223c288beeb10f1da75ff4d713baf511286a150bf5a38cd5ea5e5bf2c1cd
+  metadata.gz: dbdcbe648b51889c656578e8962c737380b0ab255be1941c5df48bdef9740c8e5e2d0aa2fd814f697e24197b36aaa8759f3882211059f7e2be55facfbd13e5e6
+  data.tar.gz: 064f914a6ddc35ae884b7d3563e7791da2d48030e292796422df5e5191a6de920959dfeca0d0a7bde6646f1ac6a1581526f0ed08df50084eb8da7d73f16b08aa

data/lib/optimizely.rb

@@ -14,7 +14,7 @@
 #    limitations under the License.
 #
 require_relative 'optimizely/audience'
-require_relative 'optimizely/bucketer'
+require_relative 'optimizely/decision_service'
 require_relative 'optimizely/error_handler'
 require_relative 'optimizely/event_builder'
 require_relative 'optimizely/event_dispatcher'
@@ -28,29 +28,31 @@ module Optimizely
   class Project
 
     # Boolean representing if the instance represents a usable Optimizely Project
-    attr_reader   :is_valid
+    attr_reader :is_valid
 
-    attr_accessor :config
-    attr_accessor :bucketer
-    attr_accessor :event_builder
-    attr_accessor :event_dispatcher
-    attr_accessor :logger
-    attr_accessor :error_handler
+    attr_reader :config
+    attr_reader :decision_service
+    attr_reader :error_handler
+    attr_reader :event_builder
+    attr_reader :event_dispatcher
+    attr_reader :logger
 
-    def initialize(datafile, event_dispatcher = nil, logger = nil, error_handler = nil, skip_json_validation = false)
+    def initialize(datafile, event_dispatcher = nil, logger = nil, error_handler = nil, skip_json_validation = false, user_profile_service = nil)
       # Constructor for Projects.
       #
       # datafile - JSON string representing the project.
       # event_dispatcher - Provides a dispatch_event method which if given a URL and params sends a request to it.
-      # logger - Optional param which provides a log method to log messages. By default nothing would be logged.
-      # error_handler - Optional param which provides a handle_error method to handle exceptions.
+      # logger - Optional component which provides a log method to log messages. By default nothing would be logged.
+      # error_handler - Optional component which provides a handle_error method to handle exceptions.
       #                 By default all exceptions will be suppressed.
+      # user_profile_service - Optional component which provides methods to store and retreive user profiles.
       # skip_json_validation - Optional boolean param to skip JSON schema validation of the provided datafile.
 
       @is_valid = true
       @logger = logger || NoOpLogger.new
       @error_handler = error_handler || NoOpErrorHandler.new
       @event_dispatcher = event_dispatcher || EventDispatcher.new
+      @user_profile_service = user_profile_service
 
       begin
         validate_instantiation_options(datafile, skip_json_validation)
@@ -77,7 +79,7 @@ module Optimizely
         return
       end
 
-      @bucketer = Bucketer.new(@config)
+      @decision_service = DecisionService.new(@config, @user_profile_service)
       @event_builder = EventBuilderV2.new(@config)
     end
 
@@ -135,24 +137,13 @@ module Optimizely
         return nil
       end
 
-      unless preconditions_valid?(experiment_key, attributes)
+      unless user_inputs_valid?(attributes)
         @logger.log(Logger::INFO, "Not activating user '#{user_id}.")
         return nil
       end
 
-      variation_id = @bucketer.get_forced_variation_id(experiment_key, user_id)
+      variation_id = @decision_service.get_variation(experiment_key, user_id, attributes)
 
-      unless variation_id.nil?
-        return @config.get_variation_key_from_id(experiment_key, variation_id)
-      end
-
-      unless Audience.user_in_experiment?(@config, experiment_key, attributes)
-        @logger.log(Logger::INFO,
-                    "User '#{user_id}' does not meet the conditions to be in experiment '#{experiment_key}'.")
-        return nil
-      end
-
-      variation_id = @bucketer.bucket(experiment_key, user_id)
       unless variation_id.nil?
         return @config.get_variation_key_from_id(experiment_key, variation_id)
       end
@@ -240,25 +231,6 @@ module Optimizely
       valid_experiments
     end
 
-    def preconditions_valid?(experiment_key, attributes = nil, event_tags = nil)
-      # Validates preconditions for bucketing a user.
-      #
-      # experiment_key - String key for an experiment.
-      # user_id - String ID of user.
-      # attributes - Hash of user attributes.
-      #
-      # Returns boolean representing whether all preconditions are valid.
-
-      return false unless user_inputs_valid?(attributes, event_tags)
-
-      unless @config.experiment_running?(experiment_key)
-        @logger.log(Logger::INFO, "Experiment '#{experiment_key}' is not running.")
-        return false
-      end
-
-      true
-    end
-
     def user_inputs_valid?(attributes = nil, event_tags = nil)
       # Helper method to validate user inputs.
       #

data/lib/optimizely/bucketer.rb

@@ -101,36 +101,6 @@ module Optimizely
       nil
     end
 
-    def get_forced_variation_id(experiment_key, user_id)
-      # Determine if a user is forced into a variation for the given experiment and return the id of that variation.
-      #
-      # experiment_key - Key representing the experiment for which user is to be bucketed.
-      # user_id - ID for the user.
-      #
-      # Returns variation ID in which the user with ID user_id is forced into. Nil if no variation.
-
-      forced_variations = @config.get_forced_variations(experiment_key)
-
-      return nil unless forced_variations
-
-      forced_variation_key = forced_variations[user_id]
-
-      return nil unless forced_variation_key
-
-      forced_variation_id = @config.get_variation_id_from_key(experiment_key, forced_variation_key)
-
-      unless forced_variation_id
-        @config.logger.log(
-          Logger::INFO,
-          "Variation key '#{forced_variation_key}' is not in datafile. Not activating user '#{user_id}'."
-        )
-        return nil
-      end
-
-      @config.logger.log(Logger::INFO, "User '#{user_id}' is forced in variation '#{forced_variation_key}'.")
-      forced_variation_id
-    end
-
     private
 
     def find_bucket(bucket_value, traffic_allocations)

data/lib/optimizely/decision_service.rb

@@ -0,0 +1,190 @@
+#
+#    Copyright 2017, Optimizely and contributors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+require_relative './bucketer'
+
+module Optimizely
+  class DecisionService
+    # Optimizely's decision service that determines into which variation of an experiment a user will be allocated.
+    #
+    # The decision service contains all logic relating to how a user bucketing decisions is made.
+    # This includes all of the following (in order):
+    #
+    # 1. Checking experiment status
+    # 2. Checking whitelisting
+    # 3. Checking user profile service for past bucketing decisions (sticky bucketing)
+    # 3. Checking audience targeting
+    # 4. Using Murmurhash3 to bucket the user
+
+    attr_reader :bucketer
+    attr_reader :config
+
+    def initialize(config, user_profile_service = nil)
+      @config = config
+      @user_profile_service = user_profile_service
+      @bucketer = Bucketer.new(@config)
+    end
+
+    def get_variation(experiment_key, user_id, attributes = nil)
+      # Determines variation into which user will be bucketed.
+      #
+      # experiment_key - Experiment for which visitor variation needs to be determined
+      # user_id - String ID for user
+      # attributes - Hash representing user attributes
+      #
+      # Returns variation ID where visitor will be bucketed (nil if experiment is inactive or user does not meet audience conditions)
+
+      # Check to make sure experiment is active
+      unless @config.experiment_running?(experiment_key)
+        @config.logger.log(Logger::INFO, "Experiment '#{experiment_key}' is not running.")
+        return nil
+      end
+
+      experiment_id = @config.get_experiment_id(experiment_key)
+
+      # Check if user is in a forced variation
+      forced_variation_id = get_forced_variation_id(experiment_key, user_id)
+      return forced_variation_id if forced_variation_id
+
+      # Check for saved bucketing decisions
+      user_profile = get_user_profile(user_id)
+      saved_variation_id = get_saved_variation_id(experiment_id, user_profile)
+      if saved_variation_id
+        @config.logger.log(
+          Logger::INFO,
+          "Returning previously activated variation ID #{saved_variation_id} of experiment '#{experiment_key}' for user '#{user_id}' from user profile."
+        )
+        return saved_variation_id
+      end
+
+      # Check audience conditions
+      unless Audience.user_in_experiment?(@config, experiment_key, attributes)
+        @config.logger.log(
+          Logger::INFO,
+          "User '#{user_id}' does not meet the conditions to be in experiment '#{experiment_key}'."
+        )
+        return nil
+      end
+
+      # Bucket normally
+      variation_id = @bucketer.bucket(experiment_key, user_id)
+
+      # Persist bucketing decision
+      save_user_profile(user_profile, experiment_id, variation_id)
+      variation_id
+    end
+
+    private
+    
+    def get_forced_variation_id(experiment_key, user_id)
+      # Determine if a user is forced into a variation for the given experiment and return the ID of that variation
+      #
+      # experiment_key - Key representing the experiment for which user is to be bucketed
+      # user_id - ID for the user
+      #
+      # Returns variation ID into which user_id is forced (nil if no variation)
+
+      forced_variations = @config.get_forced_variations(experiment_key)
+
+      return nil unless forced_variations
+
+      forced_variation_key = forced_variations[user_id]
+
+      return nil unless forced_variation_key
+
+      forced_variation_id = @config.get_variation_id_from_key(experiment_key, forced_variation_key)
+
+      unless forced_variation_id
+        @config.logger.log(
+          Logger::INFO,
+          "User '#{user_id}' is whitelisted into variation '#{forced_variation_key}', which is not in the datafile."
+        )
+        return nil
+      end
+
+      @config.logger.log(
+        Logger::INFO,
+        "User '#{user_id}' is whitelisted into variation '#{forced_variation_key}' of experiment '#{experiment_key}'."
+      )
+      forced_variation_id
+    end
+
+    def get_saved_variation_id(experiment_id, user_profile)
+      # Retrieve variation ID of stored bucketing decision for a given experiment from a given user profile
+      #
+      # experiment_id - String experiment ID
+      # user_profile - Hash user profile
+      #
+      # Returns string variation ID (nil if no decision is found)
+      return nil unless user_profile[:experiment_bucket_map]
+
+      decision = user_profile[:experiment_bucket_map][experiment_id]
+      return nil unless decision
+      variation_id = decision[:variation_id]
+      return variation_id if @config.variation_id_exists?(experiment_id, variation_id)
+
+      @config.logger.log(
+        Logger::INFO,
+        "User '#{user_profile['user_id']}' was previously bucketed into variation ID '#{variation_id}' for experiment '#{experiment_id}', but no matching variation was found. Re-bucketing user."
+      )
+      nil
+    end
+
+    def get_user_profile(user_id)
+      # Determine if a user is forced into a variation for the given experiment and return the ID of that variation
+      #
+      # user_id - String ID for the user
+      #
+      # Returns Hash stored user profile (or a default one if lookup fails or user profile service not provided) 
+
+      user_profile = {
+        :user_id => user_id,
+        :experiment_bucket_map => {}
+      }
+
+      return user_profile unless @user_profile_service
+
+      begin
+        user_profile = @user_profile_service.lookup(user_id) || user_profile
+      rescue => e
+        @config.logger.log(Logger::ERROR, "Error while looking up user profile for user ID '#{user_id}': #{e}.")
+      end
+
+      user_profile
+    end
+
+
+    def save_user_profile(user_profile, experiment_id, variation_id)
+      # Save a given bucketing decision to a given user profile
+      #
+      # user_profile - Hash user profile
+      # experiment_id - String experiment ID
+      # variation_id - String variation ID
+
+      return unless @user_profile_service
+
+      user_id = user_profile[:user_id]
+      begin
+        user_profile[:experiment_bucket_map][experiment_id] = {
+          :variation_id => variation_id
+        }
+        @user_profile_service.save(user_profile)
+        @config.logger.log(Logger::INFO, "Saved variation ID #{variation_id} of experiment ID #{experiment_id} for user '#{user_id}'.")
+      rescue => e
+        @config.logger.log(Logger::ERROR, "Error while saving user profile for user ID '#{user_id}': #{e}.")
+      end
+    end
+  end
+end

data/lib/optimizely/event_builder.rb

@@ -42,7 +42,7 @@ module Optimizely
 
   class BaseEventBuilder
     attr_reader :config
-    attr_accessor :params
+    attr_reader :params
 
     def initialize(config)
       @config = config

data/lib/optimizely/project_config.rb

@@ -294,6 +294,29 @@ module Optimizely
       @parsing_succeeded
     end
 
+    def variation_id_exists?(experiment_id, variation_id)
+      # Determines if a given experiment ID / variation ID pair exists in the datafile
+      #
+      # experiment_id - String experiment ID
+      # variation_id - String variation ID
+      #
+      # Returns true if variation is in datafile
+
+      experiment_key = get_experiment_key(experiment_id)
+      variation_id_map = @variation_id_map[experiment_key]
+      if variation_id_map
+        variation = variation_id_map[variation_id]
+        return true if variation
+        @logger.log Logger::ERROR, "Variation ID '#{variation_id}' is not in datafile."
+        @error_handler.handle_error InvalidVariationError
+        return false
+      end
+
+      @logger.log Logger::ERROR, "Experiment ID '#{experiment_id}' is not in datafile."
+      @error_handler.handle_error InvalidExperimentError
+      false
+    end
+
     private
 
     def generate_key_map(array, key)

data/lib/optimizely/user_profile_service.rb

@@ -0,0 +1,36 @@
+#
+#    Copyright 2017, Optimizely and contributors
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+#
+
+module Optimizely
+  class BaseUserProfileService
+    # Class encapsulating user profile service functionality.
+    # Override with your own implementation for storing and retrieving user profiles.
+
+    def lookup(user_id)
+      # Retrieve the Hash user profile associated with a given user ID.
+      #
+      # user_id - String user ID
+      #
+      # Returns Hash user profile.
+    end
+
+    def save(user_profile)
+      # Saves a given user profile.
+      #
+      # user_profile - Hash user profile.
+    end
+  end
+end

data/lib/optimizely/version.rb

@@ -14,5 +14,5 @@
 #    limitations under the License.
 #
 module Optimizely
-  VERSION = '1.2.0'.freeze
+  VERSION = '1.3.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: optimizely-sdk
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Andrew Delikat
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-05 00:00:00.000000000 Z
+date: 2017-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -121,6 +121,7 @@ files:
 - lib/optimizely/audience.rb
 - lib/optimizely/bucketer.rb
 - lib/optimizely/condition.rb
+- lib/optimizely/decision_service.rb
 - lib/optimizely/error_handler.rb
 - lib/optimizely/event_builder.rb
 - lib/optimizely/event_dispatcher.rb
@@ -132,6 +133,7 @@ files:
 - lib/optimizely/logger.rb
 - lib/optimizely/params.rb
 - lib/optimizely/project_config.rb
+- lib/optimizely/user_profile_service.rb
 - lib/optimizely/version.rb
 homepage: https://www.optimizely.com/
 licenses:
@@ -153,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: Ruby SDK for Optimizely's testing framework