growthbook 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28649218e25654a513fd965aeed205a4208341c265ea9e06d1b2f6efe9a4b1eb
-  data.tar.gz: 165ef4c260ec96a6c77b47acdfdd218039a7067156b0669d7b44adbf4c30382b
+  metadata.gz: 95b90dcba429217cc585f4ea2007e3d7aab0f3489dc93ee41d7fa72b847b7f53
+  data.tar.gz: 363c48f172798a02d899cfdc6ffb692ab1f85b45cf205e0d4c5dc6339c86c83a
 SHA512:
-  metadata.gz: aa1bd7678e81a58d64a51a4f9d035c76cb9ee75ae91584b17c6ff92338e543be58935da3542f77c6e3c6d1cc5fcf030eb804a09d547fd8533511474d6c638f4a
-  data.tar.gz: 9600cc883324faa2c7dcbbf4aa26e8469f0952057f3cf4b449c38cb59c0e6cd37eea246943f99750f3d54a1259fdebb622a14ec4b951a957cecf8bd924d107c0
+  metadata.gz: 6b8c950602e92cb66a644e6780827410d3c2e5eb71078adb95b469fbbe1c9b7f9925a6d3cf5917c345b9a5d04feabf21198d0349a57d5c597e7dca92f004bf43
+  data.tar.gz: ded0ea4cc0913bf8d93f8f61a34b622579d7346dfe02f121d011e82b11920e7703c192e8afb6331c2ac0d5245a435473e54707907e6116e46d4b4b01a5a3c394

data/lib/growthbook/conditions.rb

@@ -3,6 +3,8 @@
 require 'json'
 
 module Growthbook
+  # internal use only
+  # Utils for condition evaluation
   class Conditions
     # Evaluate a targeting conditions hash against an attributes hash
     # Both attributes and conditions only have string keys (no symbols)
@@ -25,7 +27,7 @@ module Growthbook
       when Array
         return condition.map { |v| parse_condition(v) }
       when Hash
-        return condition.map { |k, v| [k.to_s, parse_condition(v)] }.to_h
+        return condition.to_h { |k, v| [k.to_s, parse_condition(v)] }
       end
 
       condition
@@ -47,7 +49,7 @@ module Growthbook
       true
     end
 
-    def self.is_operator_object(obj)
+    def self.operator_object?(obj)
       obj.each do |key, _value|
         return false if key[0] != '$'
       end
@@ -58,7 +60,7 @@ module Growthbook
       return 'string' if attribute_value.is_a? String
       return 'number' if attribute_value.is_a? Integer
       return 'number' if attribute_value.is_a? Float
-      return 'boolean' if attribute_value == true || attribute_value == false
+      return 'boolean' if [true, false].include?(attribute_value)
       return 'array' if attribute_value.is_a? Array
       return 'null' if attribute_value.nil?
 
@@ -70,18 +72,16 @@ module Growthbook
       current = attributes
 
       parts.each do |value|
-        if current && current.is_a?(Hash) && current.key?(value)
-          current = current[value]
-        else
-          return nil
-        end
+        return nil unless current.is_a?(Hash) && current&.key?(value)
+
+        current = current[value]
       end
 
       current
     end
 
     def self.eval_condition_value(condition_value, attribute_value)
-      if condition_value.is_a?(Hash) && is_operator_object(condition_value)
+      if condition_value.is_a?(Hash) && operator_object?(condition_value)
         condition_value.each do |key, value|
           return false unless eval_operator_condition(key, attribute_value, value)
         end
@@ -94,7 +94,7 @@ module Growthbook
       return false unless attribute_value.is_a? Array
 
       attribute_value.each do |item|
-        if is_operator_object(condition)
+        if operator_object?(condition)
           return true if eval_condition_value(condition, item)
         elsif eval_condition(item, condition)
           return true
@@ -147,10 +147,10 @@ module Growthbook
         true
       when '$exists'
         exists = !attribute_value.nil?
-        if !condition_value
-          !exists
-        else
+        if condition_value
           exists
+        else
+          !exists
         end
       when '$type'
         condition_value == get_type(attribute_value)

data/lib/growthbook/context.rb

@@ -1,9 +1,30 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Context object passed into the GrowthBook constructor.
   class Context
-    attr_accessor :enabled, :url, :qa_mode, :listener
-    attr_reader :attributes, :features, :impressions, :forced_variations, :forced_features
+    # @return [true, false] Switch to globally disable all experiments. Default true.
+    attr_accessor :enabled
+
+    # @return [String] The URL of the current page
+    attr_accessor :url
+
+    # @return [true, false, nil] If true, random assignment is disabled and only explicitly forced variations are used.
+    attr_accessor :qa_mode
+
+    # @return [Listener] An object that responds to some tracking methods that take experiment and result as arguments.
+    attr_accessor :listener
+
+    # @return [Hash] Map of user attributes that are used to assign variations
+    attr_reader :attributes
+
+    # @return [Hash] Feature definitions (usually pulled from an API or cache)
+    attr_reader :features
+
+    # @return [Hash] Force specific experiments to always assign a specific variation (used for QA)
+    attr_reader :forced_variations
+
+    attr_reader :impressions, :forced_features
 
     def initialize(options = {})
       @features = {}
@@ -62,9 +83,7 @@ module Growthbook
 
     def eval_feature(key)
       # Forced in the context
-      if @forced_features.key?(key.to_s)
-        return get_feature_result(@forced_features[key.to_s], 'override') 
-      end
+      return get_feature_result(@forced_features[key.to_s], 'override') if @forced_features.key?(key.to_s)
 
       # Return if we can't find the feature definition
       feature = get_feature(key)
@@ -74,24 +93,28 @@ module Growthbook
         # Targeting condition
         next if rule.condition && !condition_passes(rule.condition)
 
-        # Rollout or forced value rule
-        if rule.is_force?
-          unless rule.coverage.nil?
-            hash_value = get_attribute(rule.hash_attribute || 'id')
-            next if hash_value.length.zero?
+        # If there are filters for who is included (e.g. namespaces)
+        next if rule.filters && filtered_out?(rule.filters)
+
+        # If this is a percentage rollout, skip if not included
+        if rule.force?
+          seed = rule.seed || key
+          hash_attribute = rule.hash_attribute || 'id'
+          included_in_rollout = included_in_rollout?(
+            seed: seed, hash_attribute: hash_attribute, range: rule.range,
+            coverage: rule.coverage, hash_version: rule.hash_version
+          )
+          next unless included_in_rollout
 
-            n = Growthbook::Util.hash(hash_value + key)
-            next if n > rule.coverage
-          end
           return get_feature_result(rule.force, 'force')
         end
         # Experiment rule
-        next unless rule.is_experiment?
+        next unless rule.experiment?
 
         exp = rule.to_experiment(key)
-        result = run(exp)
+        result = _run(exp, key)
 
-        next unless result.in_experiment
+        next unless result.in_experiment && !result.passthrough
 
         return get_feature_result(result.value, 'experiment', exp, result)
       end
@@ -101,57 +124,94 @@ module Growthbook
     end
 
     def run(exp)
+      _run(exp)
+    end
+
+    def on?(key)
+      eval_feature(key).on
+    end
+
+    def off?(key)
+      eval_feature(key).off
+    end
+
+    def feature_value(key, fallback = nil)
+      value = eval_feature(key).value
+      value.nil? ? fallback : value
+    end
+
+    private
+
+    def _run(exp, feature_id = '')
       key = exp.key
 
       # 1. If experiment doesn't have enough variations, return immediately
-      return get_experiment_result(exp) if exp.variations.length < 2
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if exp.variations.length < 2
 
       # 2. If context is disabled, return immediately
-      return get_experiment_result(exp) unless @enabled
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) unless @enabled
 
       # 3. If forced via URL querystring
       if @url
-        qsOverride = Util.get_query_string_override(key, @url, exp.variations.length)
-        return get_experiment_result(exp, qsOverride) unless qsOverride.nil?
+        qs_override = Util.get_query_string_override(key, @url, exp.variations.length)
+        return get_experiment_result(exp, qs_override, hash_used: false, feature_id: feature_id) unless qs_override.nil?
       end
 
       # 4. If variation is forced in the context, return the forced value
-      return get_experiment_result(exp, @forced_variations[key.to_s]) if @forced_variations.key?(key.to_s)
+      if @forced_variations.key?(key.to_s)
+        return get_experiment_result(
+          exp,
+          @forced_variations[key.to_s],
+          hash_used: false,
+          feature_id: feature_id
+        )
+      end
 
       # 5. Exclude if not active
-      return get_experiment_result(exp) unless exp.active
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) unless exp.active
 
       # 6. Get hash_attribute/value and return if empty
       hash_attribute = exp.hash_attribute || 'id'
-      hash_value = get_attribute(hash_attribute)
-      return get_experiment_result(exp) if hash_value.length.zero?
-
-      # 7. Exclude if user not in namespace
-      return get_experiment_result(exp) if exp.namespace && !Growthbook::Util.in_namespace(hash_value, exp.namespace)
+      hash_value = get_attribute(hash_attribute).to_s
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if hash_value.empty?
+
+      # 7. Exclude if user is filtered out (used to be called "namespace")
+      if exp.filters
+        return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if filtered_out?(exp.filters)
+      elsif exp.namespace && !Growthbook::Util.in_namespace(hash_value, exp.namespace)
+        return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id)
+      end
 
       # 8. Exclude if condition is false
-      return get_experiment_result(exp) if exp.condition && !condition_passes(exp.condition)
+      if exp.condition && !condition_passes(exp.condition)
+        return get_experiment_result(
+          exp,
+          -1,
+          hash_used: false,
+          feature_id: feature_id
+        )
+      end
 
-      # 9. Calculate bucket ranges and choose one
-      ranges = Growthbook::Util.get_bucket_ranges(
+      # 9. Get bucket ranges and choose variation
+      ranges = exp.ranges || Growthbook::Util.get_bucket_ranges(
         exp.variations.length,
         exp.coverage,
         exp.weights
       )
-      n = Growthbook::Util.hash(hash_value + key)
+      n = Growthbook::Util.hash(seed: exp.seed || key, value: hash_value, version: exp.hash_version || 1)
       assigned = Growthbook::Util.choose_variation(n, ranges)
 
       # 10. Return if not in experiment
-      return get_experiment_result(exp) if assigned.negative?
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if assigned.negative?
 
       # 11. Experiment has a forced variation
-      return get_experiment_result(exp, exp.force) unless exp.force.nil?
+      return get_experiment_result(exp, exp.force, hash_used: false, feature_id: feature_id) unless exp.force.nil?
 
       # 12. Exclude if in QA mode
-      return get_experiment_result(exp) if @qa_mode
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if @qa_mode
 
       # 13. Build the result object
-      result = get_experiment_result(exp, assigned, true)
+      result = get_experiment_result(exp, assigned, hash_used: true, feature_id: feature_id, bucket: n)
 
       # 14. Fire tracking callback
       track_experiment(exp, result)
@@ -160,21 +220,6 @@ module Growthbook
       result
     end
 
-    def on?(key)
-      eval_feature(key).on
-    end
-
-    def off?(key)
-      eval_feature(key).off
-    end
-
-    def feature_value(key, fallback = nil)
-      value = eval_feature(key).value
-      value.nil? ? fallback : value
-    end
-
-    private
-
     def stringify_keys(hash)
       new_hash = {}
       hash.each do |key, value|
@@ -187,7 +232,7 @@ module Growthbook
       Growthbook::Conditions.eval_condition(@attributes, condition)
     end
 
-    def get_experiment_result(experiment, variation_index = -1, hash_used = false)
+    def get_experiment_result(experiment, variation_index = -1, hash_used: false, feature_id: '', bucket: nil)
       in_experiment = true
       if variation_index.negative? || variation_index >= experiment.variations.length
         variation_index = 0
@@ -196,9 +241,17 @@ module Growthbook
 
       hash_attribute = experiment.hash_attribute || 'id'
       hash_value = get_attribute(hash_attribute)
+      meta = experiment.meta ? experiment.meta[variation_index] : {}
 
-      Growthbook::InlineExperimentResult.new(hash_used, in_experiment, variation_index,
-                                             experiment.variations[variation_index], hash_attribute, hash_value)
+      result = Growthbook::InlineExperimentResult.new(
+        { key: meta['key'] || variation_index, in_experiment: in_experiment, variation_id: variation_index,
+          value: experiment.variations[variation_index], hash_used: hash_used, hash_attribute: hash_attribute,
+          hash_value: hash_value, feature_id: feature_id, bucket: bucket, name: meta['name'] }
+      )
+
+      result.passthrough = true if meta['passthrough']
+
+      result
     end
 
     def get_feature_result(value, source, experiment = nil, experiment_result = nil)
@@ -220,10 +273,37 @@ module Growthbook
     end
 
     def track_experiment(experiment, result)
-      if @listener && @listener.respond_to?(:on_experiment_viewed)
-        @listener.on_experiment_viewed(experiment, result)
-      end
+      @listener.on_experiment_viewed(experiment, result) if @listener.respond_to?(:on_experiment_viewed)
       @impressions[experiment.key] = result
     end
+
+    def included_in_rollout?(seed:, hash_attribute:, hash_version:, range:, coverage:)
+      return true if range.nil? && coverage.nil?
+
+      hash_value = get_attribute(hash_attribute)
+
+      return false if hash_value.empty?
+
+      n = Growthbook::Util.hash(seed: seed, value: hash_value, version: hash_version || 1)
+
+      return Growthbook::Util.in_range?(n, range) if range
+      return n <= coverage if coverage
+
+      true
+    end
+
+    def filtered_out?(filters)
+      filters.any? do |filter|
+        hash_value = get_attribute(filter['attribute'] || 'id')
+
+        if hash_value.empty?
+          false
+        else
+          n = Growthbook::Util.hash(seed: filter['seed'], value: hash_value, version: filter['hashVersion'] || 2)
+
+          filter['ranges'].none? { |range| Growthbook::Util.in_range?(n, range) }
+        end
+      end
+    end
   end
 end

data/lib/growthbook/feature.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # The feature with a generic value type.
   class Feature
     # @return [Any , nil]
     attr_reader :default_value
@@ -9,9 +10,9 @@ module Growthbook
     attr_reader :rules
 
     def initialize(feature)
-      @default_value = getOption(feature, :defaultValue)
+      @default_value = get_option(feature, :defaultValue)
 
-      rules = getOption(feature, :rules)
+      rules = get_option(feature, :rules)
 
       @rules = []
       rules&.each do |rule|
@@ -31,7 +32,7 @@ module Growthbook
 
     private
 
-    def getOption(hash, key)
+    def get_option(hash, key)
       return hash[key.to_sym] if hash.key?(key.to_sym)
       return hash[key.to_s] if hash.key?(key.to_s)
 

data/lib/growthbook/feature_result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Result of a feature evaluation
   class FeatureResult
     # The assigned value of the feature
     # @return [Any, nil]
@@ -19,11 +20,11 @@ module Growthbook
     attr_reader :source
 
     # The experiment used to decide the feature value
-    # @return [Growthbook.Experiment, nil]
+    # @return [Growthbook::InlineExperiment, nil]
     attr_reader :experiment
 
     # The result of the experiment
-    # @return [Growthbook.ExperimentResult, nil]
+    # @return [Growthbook::InlineExperimentResult, nil]
     attr_reader :experiment_result
 
     def initialize(

data/lib/growthbook/feature_rule.rb

@@ -1,37 +1,82 @@
 # frozen_string_literal: true
 
 module Growthbook
+  # Internal class that overrides the default value of a Feature based on a set of requirements.
   class FeatureRule
-    # @return [Hash , nil]
+    # @return [Hash , nil] Optional targeting condition
     attr_reader :condition
-    # @return [Float , nil]
+
+    # @return [Float , nil] What percent of users should be included in the experiment (between 0 and 1, inclusive)
     attr_reader :coverage
-    # @return [T , nil]
+
+    # @return [T , nil] Immediately force a specific value (ignore every other option besides condition and coverage)
     attr_reader :force
-    # @return [T[] , nil]
+
+    # @return [T[] , nil] Run an experiment (A/B test) and randomly choose between these variations
     attr_reader :variations
-    # @return [String , nil]
+
+    # @return [String , nil] The globally unique tracking key for the experiment (default to the feature key)
     attr_reader :key
-    # @return [Float[] , nil]
+
+    # @return [Float[] , nil] How to weight traffic between variations. Must add to 1.
     attr_reader :weights
-    # @return [Array , nil]
+
+    # @return [String , nil] Adds the experiment to a namespace
     attr_reader :namespace
-    # @return [String , nil]
+
+    # @return [String , nil] What user attribute should be used to assign variations (defaults to id)
     attr_reader :hash_attribute
 
+    # @return [Integer , nil] The hash version to use (default to 1)
+    attr_reader :hash_version
+
+    # @return [BucketRange , nil] A more precise version of coverage
+    attr_reader :range
+
+    # @return [BucketRanges[] , nil] Ranges for experiment variations
+    attr_reader :ranges
+
+    # @return [VariationMeta[] , nil] Meta info about the experiment variations
+    attr_reader :meta
+
+    # @return [Filter[] , nil] Array of filters to apply to the rule
+    attr_reader :filters
+
+    # @return [String , nil]  Seed to use for hashing
+    attr_reader :seed
+
+    # @return [String , nil] Human-readable name for the experiment
+    attr_reader :name
+
+    # @return [String , nil] The phase id of the experiment
+    attr_reader :phase
+
+    # @return [TrackData[] , nil] Array of tracking calls to fire
+    attr_reader :tracks
+
     def initialize(rule)
-      @coverage = getOption(rule, :coverage)
-      @force = getOption(rule, :force)
-      @variations = getOption(rule, :variations)
-      @key = getOption(rule, :key)
-      @weights = getOption(rule, :weights)
-      @namespace = getOption(rule, :namespace)
-      @hash_attribute = getOption(rule, :hash_attribute) || getOption(rule, :hashAttribute)
-
-      cond = getOption(rule, :condition)
+      @coverage = get_option(rule, :coverage)
+      @force = get_option(rule, :force)
+      @variations = get_option(rule, :variations)
+      @key = get_option(rule, :key)
+      @weights = get_option(rule, :weights)
+      @namespace = get_option(rule, :namespace)
+      @hash_attribute = get_option(rule, :hash_attribute) || get_option(rule, :hashAttribute)
+      @hash_version = get_option(rule, :hash_version) || get_option(rule, :hashVersion)
+      @range = get_option(rule, :range)
+      @ranges = get_option(rule, :ranges)
+      @meta = get_option(rule, :meta)
+      @filters = get_option(rule, :filters)
+      @seed = get_option(rule, :seed)
+      @name = get_option(rule, :name)
+      @phase = get_option(rule, :phase)
+      @tracks = get_option(rule, :tracks)
+
+      cond = get_option(rule, :condition)
       @condition = Growthbook::Conditions.parse_condition(cond) unless cond.nil?
     end
 
+    # @return [Growthbook::InlineExperiment, nil]
     def to_experiment(feature_key)
       return nil unless @variations
 
@@ -41,34 +86,49 @@ module Growthbook
         coverage: @coverage,
         weights: @weights,
         hash_attribute: @hash_attribute,
-        namespace: @namespace
+        hash_version: @hash_version,
+        namespace: @namespace,
+        meta: @meta,
+        ranges: @ranges,
+        filters: @filters,
+        name: @name,
+        phase: @phase,
+        seed: @seed
       )
     end
 
-    def is_experiment?
+    def experiment?
       !!@variations
     end
 
-    def is_force?
-      !is_experiment? && !@force.nil?
+    def force?
+      !experiment? && !@force.nil?
     end
 
     def to_json(*_args)
-      res = {}
-      res['condition'] = @condition unless @condition.nil?
-      res['coverage'] = @coverage unless @coverage.nil?
-      res['force'] = @force unless @force.nil?
-      res['variations'] = @variations unless @variations.nil?
-      res['key'] = @key unless @key.nil?
-      res['weights'] = @weights unless @weights.nil?
-      res['namespace'] = @namespace unless @namespace.nil?
-      res['hashAttribute'] = @hash_attribute unless @hash_attribute.nil?
-      res
+      {
+        'condition'     => @condition,
+        'coverage'      => @coverage,
+        'force'         => @force,
+        'variations'    => @variations,
+        'key'           => @key,
+        'weights'       => @weights,
+        'namespace'     => @namespace,
+        'hashAttribute' => @hash_attribute,
+        'range'         => @range,
+        'ranges'        => @ranges,
+        'meta'          => @meta,
+        'filters'       => @filters,
+        'seed'          => @seed,
+        'name'          => @name,
+        'phase'         => @phase,
+        'tracks'        => @tracks
+      }.compact
     end
 
     private
 
-    def getOption(hash, key)
+    def get_option(hash, key)
       return hash[key.to_sym] if hash.key?(key.to_sym)
       return hash[key.to_s] if hash.key?(key.to_s)