growthbook 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cba2938ec675b1626d643fb7493223a54d0faf1ffc37c2bacb5a06637c0a75cd
-  data.tar.gz: bce59918f346b53182450ec2fdd92776767954712334bc5b7c0bd48d952c05ce
+  metadata.gz: d672aca084d165dd7fa2a67772e6db2bb42f80876a55758fe9dc6ace227e2388
+  data.tar.gz: 4fd7709789e804bdd1a952ccf580e8fd34f265389725ca5d3f93e5eb4e073b32
 SHA512:
-  metadata.gz: 0c4ac9f40b23c8719b9cb585d92f089144df5441c787321fd0083ae72ff954f5f8027615cc3d226dcdb7c2bfdc3dc5911ef1abd472904c026a3e24c1dd81230c
-  data.tar.gz: 735bfc1c4b82432a4a9b0664282062f43ab644309933afcddb43c9dc53cd32a278d1cf14221ad9b298a0bbdb0e2a12a8e77c4aa814d8ba3719e7840c62a4d09a
+  metadata.gz: 6b2a49f5ff71788343f3c8c20d8ea32197b94131e0a93ce5f6d76baa706cc1465b03c3eb1be4208aec5c71672d13442425d9623f56ba1162498613fa91c4f059
+  data.tar.gz: e6dab10324ad1e4673db49d5db4b1e5b7b5f97e1153a72d1b19e8607e84c068f1298499d0fd6994a33c132d750a4013d021c197d6e16a8d720c61f9bb657be10

data/lib/growthbook/conditions.rb

@@ -104,20 +104,68 @@ module Growthbook
       false
     end
 
+    def self.compare(val1, val2)
+      if val1.is_a?(Numeric) || val2.is_a?(Numeric)
+        val1 = val1.is_a?(Numeric) ? val1 : val1.to_f
+        val2 = val2.is_a?(Numeric) ? val2 : val2.to_f
+      end
+
+      return 1 if val1 > val2
+      return -1 if val1 < val2
+
+      0
+    end
+
     def self.eval_operator_condition(operator, attribute_value, condition_value)
       case operator
+      when '$veq'
+        padded_version_string(attribute_value) == padded_version_string(condition_value)
+      when '$vne'
+        padded_version_string(attribute_value) != padded_version_string(condition_value)
+      when '$vgt'
+        padded_version_string(attribute_value) > padded_version_string(condition_value)
+      when '$vgte'
+        padded_version_string(attribute_value) >= padded_version_string(condition_value)
+      when '$vlt'
+        padded_version_string(attribute_value) < padded_version_string(condition_value)
+      when '$vlte'
+        padded_version_string(attribute_value) <= padded_version_string(condition_value)
       when '$eq'
-        attribute_value == condition_value
+        begin
+          compare(attribute_value, condition_value).zero?
+        rescue StandardError
+          false
+        end
       when '$ne'
-        attribute_value != condition_value
+        begin
+          compare(attribute_value, condition_value) != 0
+        rescue StandardError
+          false
+        end
       when '$lt'
-        attribute_value < condition_value
+        begin
+          compare(attribute_value, condition_value).negative?
+        rescue StandardError
+          false
+        end
       when '$lte'
-        attribute_value <= condition_value
+        begin
+          compare(attribute_value, condition_value) <= 0
+        rescue StandardError
+          false
+        end
       when '$gt'
-        attribute_value > condition_value
+        begin
+          compare(attribute_value, condition_value).positive?
+        rescue StandardError
+          false
+        end
       when '$gte'
-        attribute_value >= condition_value
+        begin
+          compare(attribute_value, condition_value) >= 0
+        rescue StandardError
+          false
+        end
       when '$regex'
         silence_warnings do
           re = Regexp.new(condition_value)
@@ -126,9 +174,13 @@ module Growthbook
           false
         end
       when '$in'
-        condition_value.include? attribute_value
+        return false unless condition_value.is_a?(Array)
+
+        in?(attribute_value, condition_value)
       when '$nin'
-        !(condition_value.include? attribute_value)
+        return false unless condition_value.is_a?(Array)
+
+        !in?(attribute_value, condition_value)
       when '$elemMatch'
         elem_match(condition_value, attribute_value)
       when '$size'
@@ -162,6 +214,29 @@ module Growthbook
       end
     end
 
+    def self.padded_version_string(input)
+      # Remove build info and leading `v` if any
+      # Split version into parts (both core version numbers and pre-release tags)
+      # "v1.2.3-rc.1+build123" -> ["1","2","3","rc","1"]
+      parts = input.gsub(/(^v|\+.*$)/, '').split(/[-.]/)
+
+      # If it's SemVer without a pre-release, add `~` to the end
+      # ["1","0","0"] -> ["1","0","0","~"]
+      # "~" is the largest ASCII character, so this will make "1.0.0" greater than "1.0.0-beta" for example
+      parts << '~' if parts.length == 3
+
+      # Left pad each numeric part with spaces so string comparisons will work ("9">"10", but " 9"<"10")
+      parts.map do |part|
+        /^[0-9]+$/.match?(part) ? part.rjust(5, ' ') : part
+      end.join('-')
+    end
+
+    def self.in?(actual, expected)
+      return expected.include?(actual) unless actual.is_a?(Array)
+
+      (actual & expected).any?
+    end
+
     # Sets $VERBOSE for the duration of the block and back to its original
     # value afterwards. Used for testing invalid regexes.
     def self.silence_warnings

data/lib/growthbook/context.rb

@@ -2,7 +2,7 @@
 
 module Growthbook
   # Context object passed into the GrowthBook constructor.
-  class Context
+  class Context # rubocop:disable Metrics/ClassLength
     # @return [true, false] Switch to globally disable all experiments. Default true.
     attr_accessor :enabled
 
@@ -33,29 +33,49 @@ module Growthbook
     # @return [Hash[String, Any]] Forced feature values
     attr_reader :forced_features
 
+    # @return [Growthbook::StickyBucketService] Sticky bucket service for sticky bucketing
+    attr_reader :sticky_bucket_service
+
+    # @return [String] The attributes that identify users. If omitted, this will be inferred from the feature definitions
+    attr_reader :sticky_bucket_identifier_attributes
+
+    # @return [String] The attributes that are used to assign sticky buckets
+    attr_reader :sticky_bucket_assignment_docs
+
+    # @return [Boolean] If true, the context is using derived sticky bucket attributes
+    attr_reader :using_derived_sticky_bucket_attributes
+
+    # @return [Hash[String, String]] The attributes that are used to assign sticky buckets
+    attr_reader :sticky_bucket_attributes
+
     def initialize(options = {})
       @features = {}
+      @attributes = {}
       @forced_variations = {}
       @forced_features = {}
       @attributes = {}
       @enabled = true
       @impressions = {}
+      @sticky_bucket_assignment_docs = {}
+
+      features = {}
+      attributes = {}
 
       options.transform_keys(&:to_sym).each do |key, value|
         case key
         when :enabled
           @enabled = value
         when :attributes
-          self.attributes = value
+          attributes = value
         when :url
           @url = value
         when :decryption_key
           nil
         when :encrypted_features
           decrypted = decrypted_features_from_options(options)
-          self.features = decrypted unless decrypted.nil?
+          features = decrypted unless decrypted.nil?
         when :features
-          self.features = value
+          features = value
         when :forced_variations, :forcedVariations
           self.forced_variations = value
         when :forced_features
@@ -66,10 +86,18 @@ module Growthbook
           @listener = value
         when :on_feature_usage
           @on_feature_usage = value
+        when :sticky_bucket_service
+          @sticky_bucket_service = value
+        when :sticky_bucket_identifier_attributes
+          @sticky_bucket_identifier_attributes = value
         else
           warn("Unknown context option: #{key}")
         end
       end
+
+      @using_derived_sticky_bucket_attributes = !@sticky_bucket_identifier_attributes
+      self.attributes = attributes
+      self.features = features
     end
 
     def features=(features)
@@ -83,10 +111,14 @@ module Growthbook
 
         @features[k.to_s] = v
       end
+
+      refresh_sticky_buckets
     end
 
     def attributes=(attrs)
       @attributes = stringify_keys(attrs || {})
+
+      refresh_sticky_buckets
     end
 
     def forced_variations=(forced_variations)
@@ -98,6 +130,43 @@ module Growthbook
     end
 
     def eval_feature(key)
+      _eval_feature(key, Set.new)
+    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 _eval_prereqs(parent_conditions, stack)
+      parent_conditions.each do |parent_condition|
+        parent_res = _eval_feature(parent_condition['id'], stack)
+
+        return 'cyclic' if parent_res.source == 'cyclicPrerequisite'
+
+        next if Growthbook::Conditions.eval_condition({ 'value' => parent_res.value }, parent_condition['condition'])
+        return 'gate' if parent_condition['gate']
+
+        return 'fail'
+      end
+      'pass'
+    end
+
+    def _eval_feature(key, stack)
       # Forced in the context
       return get_feature_result(key.to_s, @forced_features[key.to_s], 'override', nil, nil) if @forced_features.key?(key.to_s)
 
@@ -105,7 +174,24 @@ module Growthbook
       feature = get_feature(key)
       return get_feature_result(key.to_s, nil, 'unknownFeature', nil, nil) unless feature
 
+      return get_feature_result(key.to_s, nil, 'cyclicPrerequisite', nil, nil) if stack.include?(key.to_s)
+
+      stack.add(key.to_s)
+
       feature.rules.each do |rule|
+        if rule.parent_conditions&.length&.positive?
+          prereq_res = _eval_prereqs(rule.parent_conditions, stack)
+          case prereq_res
+          when 'gate'
+            return get_feature_result(key.to_s, nil, 'prerequisite', nil, nil)
+          when 'cyclic'
+            # Warning already logged in this case
+            return get_feature_result(key.to_s, nil, 'cyclicPrerequisite', nil, nil)
+          when 'fail'
+            next
+          end
+        end
+
         # Targeting condition
         next if rule.condition && !condition_passes?(rule.condition)
 
@@ -119,6 +205,7 @@ module Growthbook
           included_in_rollout = included_in_rollout?(
             seed: seed.to_s,
             hash_attribute: hash_attribute,
+            fallback_attribute: rule.fallback_attribute,
             range: rule.range,
             coverage: rule.coverage,
             hash_version: rule.hash_version
@@ -144,26 +231,7 @@ module Growthbook
       get_feature_result(key.to_s, feature.default_value.nil? ? nil : feature.default_value, 'defaultValue', nil, nil)
     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 = '')
+    def _run(exp, feature_id = '') # rubocop:disable Metrics/AbcSize
       key = exp.key
 
       # 1. If experiment doesn't have enough variations, return immediately
@@ -193,38 +261,70 @@ module Growthbook
       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).to_s
+      hash_attribute, hash_value_raw = get_hash_attribute(exp.hash_attribute, exp.fallback_attribute)
+      hash_value = hash_value_raw.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)
+      assigned = -1
+
+      found_sticky_bucket = false
+      sticky_bucket_version_is_blocked = false
+      if sticky_bucket_service && !exp.disable_sticky_bucketing
+        sticky_bucket = _get_sticky_bucket_variation(
+          exp.key,
+          exp.bucket_version,
+          exp.min_bucket_version,
+          exp.meta,
+          exp.hash_attribute,
+          exp.fallback_attribute
+        )
+        found_sticky_bucket = sticky_bucket['variation'].to_i >= 0
+        assigned = sticky_bucket['variation'].to_i
+        sticky_bucket_version_is_blocked = sticky_bucket['versionIsBlocked']
       end
 
-      # 8. Exclude if condition is false
-      if exp.condition && !condition_passes?(exp.condition)
-        return get_experiment_result(
-          exp,
-          -1,
-          hash_used: false,
-          feature_id: feature_id
-        )
+      # Some checks are not needed if we already have a sticky bucket
+      unless found_sticky_bucket
+        # 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
+        if exp.condition && !condition_passes?(exp.condition)
+          return get_experiment_result(
+            exp,
+            -1,
+            hash_used: false,
+            feature_id: feature_id
+          )
+        end
+
+        # 8.01 Exclude if parent conditions are not met
+        if exp.parent_conditions
+          prereq_res = _eval_prereqs(exp.parent_conditions, Set.new)
+          return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if %w[gate fail cyclic].include?(prereq_res)
+        end
       end
 
       # 9. Get bucket ranges and choose variation
-      ranges = exp.ranges || Growthbook::Util.get_bucket_ranges(
-        exp.variations.length,
-        exp.coverage,
-        exp.weights
-      )
       seed = exp.seed || key || ''
       n = Growthbook::Util.get_hash(seed: seed, value: hash_value, version: exp.hash_version || 1)
       return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if n.nil?
 
-      assigned = Growthbook::Util.choose_variation(n, ranges)
+      unless found_sticky_bucket
+        ranges = exp.ranges || Growthbook::Util.get_bucket_ranges(
+          exp.variations.length,
+          exp.coverage,
+          exp.weights
+        )
+        assigned = Growthbook::Util.choose_variation(n, ranges)
+      end
+
+      # Unenroll if any prior sticky buckets are blocked by version
+      return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id, sticky_bucket_used: true) if sticky_bucket_version_is_blocked
 
       # 10. Return if not in experiment
       return get_experiment_result(exp, -1, hash_used: false, feature_id: feature_id) if assigned.negative?
@@ -236,7 +336,22 @@ module Growthbook
       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, hash_used: true, feature_id: feature_id, bucket: n)
+      result = get_experiment_result(exp, assigned, hash_used: true, feature_id: feature_id, bucket: n, sticky_bucket_used: found_sticky_bucket)
+
+      # 13.5 Persist sticky bucket
+      if sticky_bucket_service && !exp.disable_sticky_bucketing
+        assignment = {
+          _get_sticky_bucket_experiment_key(exp.key, exp.bucket_version) => result.key.to_s
+        }
+
+        data = _generate_sticky_bucket_assignment_doc(hash_attribute, hash_value, assignment)
+        doc = data['doc']
+        if doc && data['changed']
+          @sticky_bucket_assignment_docs ||= {}
+          @sticky_bucket_assignment_docs[data['key']] = doc
+          sticky_bucket_service.save_assignments(doc)
+        end
+      end
 
       # 14. Fire tracking callback
       track_experiment(exp, result)
@@ -259,15 +374,14 @@ module Growthbook
       Growthbook::Conditions.eval_condition(@attributes, condition)
     end
 
-    def get_experiment_result(experiment, variation_index = -1, hash_used: false, feature_id: '', bucket: nil)
+    def get_experiment_result(experiment, variation_index = -1, hash_used: false, feature_id: '', bucket: nil, sticky_bucket_used: false)
       in_experiment = true
       if variation_index.negative? || variation_index >= experiment.variations.length
         variation_index = 0
         in_experiment = false
       end
 
-      hash_attribute = experiment.hash_attribute || 'id'
-      hash_value = get_attribute(hash_attribute)
+      hash_attribute, hash_value = get_hash_attribute(experiment.hash_attribute, experiment.fallback_attribute)
       meta = experiment.meta ? experiment.meta[variation_index] : {}
 
       result = Growthbook::InlineExperimentResult.new(
@@ -281,7 +395,8 @@ module Growthbook
           hash_value: hash_value,
           feature_id: feature_id,
           bucket: bucket,
-          name: meta['name']
+          name: meta['name'],
+          sticky_bucket_used: sticky_bucket_used
         }
       )
 
@@ -312,7 +427,23 @@ module Growthbook
       nil
     end
 
+    def get_hash_attribute(attr, fallback_attr)
+      attr ||= 'id'
+
+      val = get_attribute(attr)
+
+      # If no match, try fallback
+      if (val.nil? || val == '') && fallback_attr && @sticky_bucket_service
+        val = get_attribute(fallback_attr)
+        attr = fallback_attr unless val.nil? || val == ''
+      end
+
+      [attr, val]
+    end
+
     def get_attribute(key)
+      return '' if key.nil?
+
       return @attributes[key.to_sym] if @attributes.key?(key.to_sym)
       return @attributes[key.to_s] if @attributes.key?(key.to_s)
 
@@ -326,10 +457,12 @@ module Growthbook
       @impressions[experiment.key] = result unless experiment.key.nil?
     end
 
-    def included_in_rollout?(seed:, hash_attribute:, hash_version:, range:, coverage:)
+    def included_in_rollout?(seed:, hash_attribute:, fallback_attribute:, hash_version:, range:, coverage:)
       return true if range.nil? && coverage.nil?
 
-      hash_value = get_attribute(hash_attribute)
+      _, hash_value_raw = get_hash_attribute(hash_attribute, fallback_attribute)
+
+      hash_value = hash_value_raw.to_s
 
       return false if hash_value.empty?
 
@@ -344,7 +477,7 @@ module Growthbook
 
     def filtered_out?(filters)
       filters.any? do |filter|
-        hash_value = get_attribute(filter['attribute'] || 'id')
+        hash_value = get_attribute(filter['attribute'] || 'id').to_s
 
         if hash_value.empty?
           false
@@ -367,5 +500,124 @@ module Growthbook
     rescue StandardError
       nil
     end
+
+    def _derive_sticky_bucket_identifier_attributes
+      attributes = Set.new
+      @features.each do |_key, feature|
+        feature.rules.each do |rule|
+          if rule.variations
+            attributes.add(rule.hash_attribute || 'id')
+            attributes.add(rule.fallback_attribute) if rule.fallback_attribute
+          end
+        end
+      end
+      attributes.to_a
+    end
+
+    def _get_sticky_bucket_attributes
+      attributes = {}
+      @sticky_bucket_identifier_attributes = _derive_sticky_bucket_identifier_attributes if @using_derived_sticky_bucket_attributes
+
+      return attributes unless @sticky_bucket_identifier_attributes
+
+      @sticky_bucket_identifier_attributes.each do |attr|
+        _, hash_value = get_hash_attribute(attr, nil)
+        attributes[attr] = hash_value if hash_value
+      end
+      attributes
+    end
+
+    def _get_sticky_bucket_assignments(attr = nil, fallback = nil)
+      merged = {}
+
+      _, hash_value = get_hash_attribute(attr, nil)
+      key = "#{attr}||#{hash_value}"
+      merged = @sticky_bucket_assignment_docs[key]['assignments'] if @sticky_bucket_assignment_docs.key?(key)
+
+      if fallback
+        _, hash_value = get_hash_attribute(fallback, nil)
+        key = "#{fallback}||#{hash_value}"
+        if @sticky_bucket_assignment_docs.key?(key)
+          @sticky_bucket_assignment_docs[key]['assignments'].each do |k, v|
+            merged[k] = v unless merged.key?(k)
+          end
+        end
+      end
+
+      merged
+    end
+
+    def _is_blocked(assignments, experiment_key, min_bucket_version)
+      return false if min_bucket_version.zero?
+
+      (0...min_bucket_version).each do |i|
+        blocked_key = _get_sticky_bucket_experiment_key(experiment_key, i)
+        return true if assignments.key?(blocked_key)
+      end
+      false
+    end
+
+    def _get_sticky_bucket_variation(experiment_key, bucket_version = nil, min_bucket_version = nil, meta = nil, hash_attribute = nil, fallback_attribute = nil)
+      bucket_version ||= 0
+      min_bucket_version ||= 0
+      meta ||= []
+
+      id = _get_sticky_bucket_experiment_key(experiment_key, bucket_version)
+
+      assignments = _get_sticky_bucket_assignments(hash_attribute, fallback_attribute)
+      if _is_blocked(assignments, experiment_key, min_bucket_version)
+        return {
+          'variation'        => -1,
+          'versionIsBlocked' => true
+        }
+      end
+
+      variation_key = assignments[id]
+      return { 'variation' => -1 } unless variation_key
+
+      variation = meta.find_index { |v| v['key'] == variation_key } || -1
+      return { 'variation' => -1 } if variation.negative?
+
+      { 'variation' => variation }
+    end
+
+    def _get_sticky_bucket_experiment_key(experiment_key, bucket_version = 0)
+      "#{experiment_key}__#{bucket_version}"
+    end
+
+    def refresh_sticky_buckets(force: false)
+      return unless @sticky_bucket_service
+
+      attributes = _get_sticky_bucket_attributes
+      return if !force && attributes == @sticky_bucket_attributes
+
+      @sticky_bucket_attributes = attributes
+      @sticky_bucket_assignment_docs = @sticky_bucket_service.get_all_assignments(attributes)
+    end
+
+    def _generate_sticky_bucket_assignment_doc(attribute_name, attribute_value, assignments)
+      key = "#{attribute_name}||#{attribute_value}"
+      existing_assignments = @sticky_bucket_assignment_docs[key]&.fetch('assignments', {})
+
+      if existing_assignments
+        new_assignments = existing_assignments.merge(assignments)
+        existing_json = existing_assignments.to_json
+        new_json = new_assignments.to_json
+        changed = existing_json != new_json
+      else
+        changed = true
+        new_assignments = assignments
+      end
+
+      {
+        'key'     => key,
+        'doc'     => {
+          'attributeName'  => attribute_name,
+          'attributeValue' => attribute_value,
+          'assignments'    => new_assignments
+        },
+        'changed' => changed
+      }
+    end
   end
 end

data/lib/growthbook/feature_rule.rb

@@ -54,6 +54,21 @@ module Growthbook
     # @return [TrackData[] , nil] Array of tracking calls to fire
     attr_reader :tracks
 
+    # @return [String, nil] The attribute to use when hash_attribute is missing (requires Sticky Bucketing)
+    attr_accessor :fallback_attribute
+
+    # @return [String, nil] When true, disables sticky bucketing
+    attr_accessor :disable_sticky_bucketing
+
+    # @return [integer] Appended to the experiment key for sticky bucketing
+    attr_accessor :bucket_version
+
+    # @return [integer] Minimum bucket version required for sticky bucketing
+    attr_accessor :min_bucket_version
+
+    # @return [Array<Hash>] Array of prerequisite flags
+    attr_accessor :parent_conditions
+
     def initialize(rule)
       @coverage = get_option(rule, :coverage)
       @force = get_option(rule, :force)
@@ -74,6 +89,16 @@ module Growthbook
 
       cond = get_option(rule, :condition)
       @condition = Growthbook::Conditions.parse_condition(cond) unless cond.nil?
+
+      @fallback_attribute = get_option(rule, :fallback_attribute) || get_option(rule, :fallbackAttribute)
+      @disable_sticky_bucketing = get_option(rule, :disable_sticky_bucketing, false) || get_option(rule, :disableStickyBucketing, false)
+      @bucket_version = get_option(rule, :bucket_version) || get_option(rule, :bucketVersion) || 0
+      @min_bucket_version = get_option(rule, :min_bucket_version) || get_option(rule, :minBucketVersion) || 0
+      @parent_conditions = get_option(rule, :parent_conditions) || get_option(rule, :parentConditions) || []
+
+      return unless @disable_sticky_bucketing
+
+      @fallback_attribute = nil
     end
 
     # @return [Growthbook::InlineExperiment, nil]
@@ -83,6 +108,7 @@ module Growthbook
       Growthbook::InlineExperiment.new(
         key: @key || feature_key,
         variations: @variations,
+        condition: @condition,
         coverage: @coverage,
         weights: @weights,
         hash_attribute: @hash_attribute,
@@ -93,7 +119,11 @@ module Growthbook
         filters: @filters,
         name: @name,
         phase: @phase,
-        seed: @seed
+        seed: @seed,
+        fallback_attribute: @fallback_attribute,
+        disable_sticky_bucketing: @disable_sticky_bucketing,
+        bucket_version: @bucket_version,
+        min_bucket_version: @min_bucket_version
       )
     end
 
@@ -109,32 +139,37 @@ module Growthbook
 
     def to_json(*_args)
       {
-        '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
+        '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,
+        'fallbackAttribute'      => @fallback_attribute,
+        'disableStickyBucketing' => @disable_sticky_bucketing,
+        'bucketVersion'          => @bucket_version,
+        'minBucketVersion'       => @min_bucket_version,
+        'parentConditions'       => @parent_conditions
       }.compact
     end
 
     private
 
-    def get_option(hash, key)
+    def get_option(hash, key, default = nil)
       return hash[key.to_sym] if hash.key?(key.to_sym)
       return hash[key.to_s] if hash.key?(key.to_s)
 
-      nil
+      default
     end
   end
 end

data/lib/growthbook/inline_experiment.rb

@@ -51,6 +51,21 @@ module Growthbook
     # @return [String, nil] Id of the current experiment phase
     attr_accessor :phase
 
+    # @return [String, nil] The attribute to use when hash_attribute is missing (requires Sticky Bucketing)
+    attr_accessor :fallback_attribute
+
+    # @return [bool, nil] When true, disables sticky bucketing
+    attr_accessor :disable_sticky_bucketing
+
+    # @return [integer] Appended to the experiment key for sticky bucketing
+    attr_accessor :bucket_version
+
+    # @return [integer] Minimum bucket version required for sticky bucketing
+    attr_accessor :min_bucket_version
+
+    # @return [Array<Hash>] Array of prerequisite flags
+    attr_accessor :parent_conditions
+
     def initialize(options = {})
       @key = get_option(options, :key, '').to_s
       @variations = get_option(options, :variations, [])
@@ -68,6 +83,15 @@ module Growthbook
       @seed = get_option(options, :seed)
       @name = get_option(options, :name)
       @phase = get_option(options, :phase)
+      @fallback_attribute = get_option(options, :fallback_attribute) || get_option(options, :fallbackAttribute)
+      @disable_sticky_bucketing = get_option(options, :disable_sticky_bucketing, false) || get_option(options, :disableStickyBucketing, false)
+      @bucket_version = get_option(options, :bucket_version) || get_option(options, :bucketVersion) || 0
+      @min_bucket_version = get_option(options, :min_bucket_version) || get_option(options, :minBucketVersion) || 0
+      @parent_conditions = get_option(options, :parent_conditions) || get_option(options, :parentConditions) || []
+
+      return unless @disable_sticky_bucketing
+
+      @fallback_attribute = nil
     end
 
     def to_json(*_args)
@@ -88,6 +112,12 @@ module Growthbook
       res['seed'] = @seed
       res['name'] = @name
       res['phase'] = @phase
+      res['fallbackAttribute'] = @fallback_attribute unless @fallback_attribute.nil?
+      res['disableStickyBucketing'] = @disable_sticky_bucketing if @disable_sticky_bucketing
+      res['bucketVersion'] = @bucket_version if @bucket_version != 0
+      res['minBucketVersion'] = @min_bucket_version if @min_bucket_version != 0
+      res['parentConditions'] = @parent_conditions unless @parent_conditions.empty?
+
       res.compact
     end
 

data/lib/growthbook/inline_experiment_result.rb

@@ -36,6 +36,9 @@ module Growthbook
     # @return [Boolean]  Used for holdout groups
     attr_accessor :passthrough
 
+    # @return [Boolean]  When true, sticky bucketing was used to assign a variation
+    attr_accessor :sticky_bucket_used
+
     def initialize(options = {})
       @key = options[:key]
       @in_experiment = options[:in_experiment]
@@ -48,6 +51,7 @@ module Growthbook
       @bucket = options[:bucket]
       @name = options[:name]
       @passthrough = options[:passthrough]
+      @sticky_bucket_used = options[:sticky_bucket_used]
     end
 
     # If the variation was randomly assigned based on user attribute hashes
@@ -56,6 +60,10 @@ module Growthbook
       @hash_used
     end
 
+    def sticky_bucket_used?
+      @sticky_bucket_used || false
+    end
+
     # Whether or not the user is in the experiment
     # @return [Bool]
     def in_experiment?
@@ -64,17 +72,18 @@ module Growthbook
 
     def to_json(*_args)
       {
-        'inExperiment'  => @in_experiment,
-        'variationId'   => @variation_id,
-        'value'         => @value,
-        'hashUsed'      => @hash_used,
-        'hashAttribute' => @hash_attribute,
-        'hashValue'     => @hash_value,
-        'featureId'     => @feature_id.to_s,
-        'key'           => @key.to_s,
-        'bucket'        => @bucket,
-        'name'          => @name,
-        'passthrough'   => @passthrough
+        'inExperiment'     => @in_experiment,
+        'variationId'      => @variation_id,
+        'value'            => @value,
+        'hashUsed'         => @hash_used,
+        'hashAttribute'    => @hash_attribute,
+        'hashValue'        => @hash_value,
+        'featureId'        => @feature_id.to_s,
+        'key'              => @key.to_s,
+        'bucket'           => @bucket,
+        'name'             => @name,
+        'passthrough'      => @passthrough,
+        'stickyBucketUsed' => @sticky_bucket_used
       }.compact
     end
   end

data/lib/growthbook/sticky_bucket_service.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Growthbook
+  # Extendable class that can be used as the tracking callback
+  class StickyBucketService
+    def get_assignments(_attribute_name, _attribute_value)
+      nil
+    end
+
+    def save_assignments(_doc)
+      nil
+    end
+
+    def get_key(attribute_name, attribute_value)
+      "#{attribute_name}||#{attribute_value}"
+    end
+
+    def get_all_assignments(attributes)
+      docs = {}
+      attributes.each do |attribute_name, attribute_value|
+        doc = get_assignments(attribute_name, attribute_value)
+        docs[get_key(attribute_name, attribute_value)] = doc if doc
+      end
+      docs
+    end
+  end
+
+  # Sample implementation (not meant for production use)
+  class InMemoryStickyBucketService < StickyBucketService
+    attr_accessor :assignments
+
+    def initialize
+      super
+      @assignments = {}
+    end
+
+    def get_assignments(attribute_name, attribute_value)
+      @assignments[get_key(attribute_name, attribute_value)]
+    end
+
+    def save_assignments(doc)
+      @assignments[get_key(doc['attributeName'], doc['attributeValue'])] = doc
+    end
+  end
+end

data/lib/growthbook.rb

@@ -17,3 +17,4 @@ require 'growthbook/inline_experiment_result'
 require 'growthbook/tracking_callback'
 require 'growthbook/util'
 require 'growthbook/feature_usage_callback'
+require 'growthbook/sticky_bucket_service'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: growthbook
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - GrowthBook
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-13 00:00:00.000000000 Z
+date: 2024-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -98,6 +98,7 @@ files:
 - lib/growthbook/fnv.rb
 - lib/growthbook/inline_experiment.rb
 - lib/growthbook/inline_experiment_result.rb
+- lib/growthbook/sticky_bucket_service.rb
 - lib/growthbook/tracking_callback.rb
 - lib/growthbook/util.rb
 homepage: https://github.com/growthbook/growthbook-ruby