statsig 1.28.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a8876d235dc185cdc997a812ce941de80f6d5075fb151e8539b65b354419734
-  data.tar.gz: cc7fb865b12a909eb8bf188d9bc7f0e9ad07a70de6a7ac2e4911b1ceeb830281
+  metadata.gz: '093cc05e0b8f3bb7e2f0f019cf36ad33e5abc4c4349d2fb1faa056c1ff5aa341'
+  data.tar.gz: d66640f8b0c317ca018ff4ccc77d1d370af89b1c84416508631deb610236d519
 SHA512:
-  metadata.gz: c030c79c5d3b98f9f8b6fba4a2afafebe97ddb3522e4b2788c4b1ec4065bf1e3de7f1f667586a3b34bf8a457d784179fa54745a7bfb949914c33079aa8558e95
-  data.tar.gz: d85ada516a510f48e93109c01c3023c1566f3b5b8afc86c83f44b7ce6179946290e80df3c1ed899efd6cf642282e4e3fd5601987ccdaf3844b841acd8ea5af6f
+  metadata.gz: f634575320cd1ababfa25816ee8ac5fe27e34c761895b4ba6b20957363e487c295767d65e123ab7d306aa1ce2f535f55cc58570f8767790948d2647ab321150b
+  data.tar.gz: d563727b175a23afa50cb68cbaf91eb49435bae46b1a48b72d9bf0ff38febeefa86b886c34cc2632f37e357c44f96a1e2586050b41e9ac156697f4105c4f9f0b

data/lib/client_initialize_helpers.rb

@@ -42,7 +42,7 @@ module ClientInitializeHelpers
       target_app_id = @evaluator.spec_store.get_app_id_for_sdk_key(@client_sdk_key)
       config_target_apps = config_spec['targetAppIDs']
 
-      unless target_app_id.nil? || config_target_apps.nil? || config_target_apps.include?(target_app_id)
+      unless target_app_id.nil? || (!config_target_apps.nil? && config_target_apps.include?(target_app_id))
         return nil
       end
 

data/lib/config_result.rb

@@ -1,6 +1,11 @@
 # typed: true
+
+require 'sorbet-runtime'
+
 module Statsig
   class ConfigResult
+    extend T::Sig
+
     attr_accessor :name
     attr_accessor :gate_value
     attr_accessor :json_value
@@ -20,7 +25,7 @@ module Statsig
       json_value = {},
       rule_id = '',
       secondary_exposures = [],
-      config_delegate = '',
+      config_delegate = nil,
       explicit_parameters = [],
       is_experiment_group: false,
       evaluation_details: nil,
@@ -39,5 +44,39 @@ module Statsig
       @group_name = group_name
       @id_type = id_type
     end
+
+    sig { params(config_name: String, user_persisted_values: UserPersistedValues).returns(T.nilable(ConfigResult)) }
+    def self.from_user_persisted_values(config_name, user_persisted_values)
+      sticky_values = user_persisted_values[config_name]
+      return nil if sticky_values.nil?
+
+      from_hash(config_name, sticky_values)
+    end
+
+    sig { params(config_name: String, hash: Hash).returns(ConfigResult) }
+    def self.from_hash(config_name, hash)
+      new(
+        config_name,
+        hash['gate_value'],
+        hash['json_value'],
+        hash['rule_id'],
+        hash['secondary_exposures'],
+        evaluation_details: EvaluationDetails.persisted(hash['config_sync_time'], hash['init_time']),
+        group_name: hash['group_name']
+      )
+    end
+
+    sig { returns(Hash) }
+    def to_hash
+      {
+        json_value: @json_value,
+        gate_value: @gate_value,
+        rule_id: @rule_id,
+        secondary_exposures: @secondary_exposures,
+        config_sync_time: @evaluation_details.config_sync_time,
+        init_time: @init_time,
+        group_name: @group_name
+      }
+    end
   end
-end
+end

data/lib/dynamic_config.rb

@@ -26,13 +26,26 @@ class DynamicConfig
   sig { returns(String) }
   attr_accessor :id_type
 
-  sig { params(name: String, value: T::Hash[String, T.untyped], rule_id: String, group_name: T.nilable(String), id_type: String).void }
-  def initialize(name, value = {}, rule_id = '', group_name = nil, id_type = '')
+  sig { returns(T.nilable(Statsig::EvaluationDetails)) }
+  attr_accessor :evaluation_details
+
+  sig do
+    params(
+      name: String,
+      value: T::Hash[String, T.untyped],
+      rule_id: String,
+      group_name: T.nilable(String),
+      id_type: String,
+      evaluation_details: T.nilable(Statsig::EvaluationDetails)
+    ).void
+  end
+  def initialize(name, value = {}, rule_id = '', group_name = nil, id_type = '', evaluation_details = nil)
     @name = name
     @value = value
     @rule_id = rule_id
     @group_name = group_name
     @id_type = id_type
+    @evaluation_details = evaluation_details
   end
 
   sig { params(index: String, default_value: T.untyped).returns(T.untyped) }

data/lib/evaluation_details.rb

@@ -2,12 +2,13 @@
 module Statsig
 
   module EvaluationReason
-    NETWORK = "Network"
-    LOCAL_OVERRIDE = "LocalOverride"
-    UNRECOGNIZED = "Unrecognized"
-    UNINITIALIZED = "Uninitialized"
-    BOOTSTRAP = "Bootstrap"
-    DATA_ADAPTER = "DataAdapter"
+    NETWORK = 'Network'.freeze
+    LOCAL_OVERRIDE = 'LocalOverride'.freeze
+    UNRECOGNIZED = 'Unrecognized'.freeze
+    UNINITIALIZED = 'Uninitialized'.freeze
+    BOOTSTRAP = 'Bootstrap'.freeze
+    DATA_ADAPTER = 'DataAdapter'.freeze
+    PERSISTED = 'Persisted'.freeze
   end
 
   class EvaluationDetails
@@ -38,5 +39,9 @@ module Statsig
     def self.local_override(config_sync_time, init_time)
       EvaluationDetails.new(config_sync_time, init_time, EvaluationReason::LOCAL_OVERRIDE)
     end
+
+    def self.persisted(config_sync_time, init_time)
+      EvaluationDetails.new(config_sync_time, init_time, EvaluationReason::PERSISTED)
+    end
   end
-end
+end

data/lib/evaluator.rb

@@ -1,4 +1,6 @@
 # typed: false
+
+require 'sorbet-runtime'
 require 'config_result'
 require 'country_lookup'
 require 'digest'
@@ -9,21 +11,44 @@ require 'time'
 require 'ua_parser'
 require 'evaluation_details'
 require 'user_agent_parser/operating_system'
+require 'user_persistent_storage_utils'
 
 $fetch_from_server = 'fetch_from_server'
 $type_dynamic_config = 'dynamic_config'
 
 module Statsig
   class Evaluator
+    extend T::Sig
+
+    sig { returns(SpecStore) }
     attr_accessor :spec_store
 
-    def initialize(network, options, error_callback, diagnostics, error_boundary, logger)
+    sig { returns(StatsigOptions) }
+    attr_accessor :options
+
+    sig { returns(UserPersistentStorageUtils) }
+    attr_accessor :persistent_storage_utils
+
+    sig do
+      params(
+        network: Network,
+        options: StatsigOptions,
+        error_callback: T.any(Method, Proc, NilClass),
+        diagnostics: Diagnostics,
+        error_boundary: ErrorBoundary,
+        logger: StatsigLogger,
+        persistent_storage_utils: UserPersistentStorageUtils,
+      ).void
+    end
+    def initialize(network, options, error_callback, diagnostics, error_boundary, logger, persistent_storage_utils)
       @spec_store = Statsig::SpecStore.new(network, options, error_callback, diagnostics, error_boundary, logger)
       UAParser.initialize_async
       CountryLookup.initialize_async
 
       @gate_overrides = {}
       @config_overrides = {}
+      @options = options
+      @persistent_storage_utils = persistent_storage_utils
     end
 
     def maybe_restart_background_threads
@@ -52,7 +77,8 @@ module Statsig
       eval_spec(user, @spec_store.get_gate(gate_name))
     end
 
-    def get_config(user, config_name)
+    sig { params(user: StatsigUser, config_name: String, user_persisted_values: T.nilable(UserPersistedValues)).returns(ConfigResult) }
+    def get_config(user, config_name, user_persisted_values: nil)
       if @config_overrides.key?(config_name)
         id_type = @spec_store.has_config?(config_name) ? @spec_store.get_config(config_name)['idType'] : ''
         return Statsig::ConfigResult.new(
@@ -83,7 +109,26 @@ module Statsig
         )
       end
 
-      eval_spec(user, @spec_store.get_config(config_name))
+      config = @spec_store.get_config(config_name)
+
+      # If persisted values is provided and the experiment is active, return sticky values if exists.
+      if !user_persisted_values.nil? && config['isActive'] == true
+        sticky_result = Statsig::ConfigResult.from_user_persisted_values(config_name, user_persisted_values)
+        return sticky_result unless sticky_result.nil?
+
+        # If it doesn't exist, then save to persisted storage if the user was assigned to an experiment group.
+        evaluation = eval_spec(user, config)
+        if evaluation.is_experiment_group
+          @persistent_storage_utils.add_evaluation_to_user_persisted_values(user_persisted_values, config_name, evaluation)
+          @persistent_storage_utils.save_to_storage(user, config['idType'], user_persisted_values)
+        end
+      # Otherwise, remove from persisted storage
+      else
+        @persistent_storage_utils.remove_experiment_from_storage(user, config['idType'], config_name)
+        evaluation = eval_spec(user, config)
+      end
+
+      return evaluation
     end
 
     def get_layer(user, layer_name)
@@ -150,6 +195,7 @@ module Statsig
       @config_overrides[config] = value
     end
 
+    sig { params(user: StatsigUser, config: Hash).returns(ConfigResult) }
     def eval_spec(user, config)
       default_rule_id = 'default'
       exposures = []
@@ -266,7 +312,7 @@ module Statsig
       operator = condition['operator']
       additional_values = condition['additionalValues']
       additional_values = Hash.new unless additional_values.is_a? Hash
-      idType = condition['idType']
+      id_type = condition['idType']
 
       return $fetch_from_server unless type.is_a? String
       type = type.downcase
@@ -304,14 +350,14 @@ module Statsig
       when 'user_bucket'
         begin
           salt = additional_values['salt']
-          unit_id = get_unit_id(user, idType) || ''
+          unit_id = user.get_unit_id(id_type) || ''
           # there are only 1000 user buckets as opposed to 10k for gate pass %
           value = compute_user_hash("#{salt}.#{unit_id}") % 1000
         rescue
           return false
         end
       when 'unit_id'
-        value = get_unit_id(user, idType)
+        value = user.get_unit_id(id_type)
       else
         return $fetch_from_server
       end
@@ -361,7 +407,7 @@ module Statsig
       when 'none_case_sensitive'
         return !EvaluationHelpers::match_string_in_array(target, value, false, ->(a, b) { a == b })
 
-        #string
+        # string
       when 'str_starts_with_any'
         return EvaluationHelpers::match_string_in_array(target, value, true, ->(a, b) { a.start_with?(b) })
       when 'str_ends_with_any'
@@ -470,7 +516,7 @@ module Statsig
     def eval_pass_percent(user, rule, config_salt)
       return false unless config_salt.is_a?(String) && !rule['passPercentage'].nil?
       begin
-        unit_id = get_unit_id(user, rule['idType']) || ''
+        unit_id = user.get_unit_id(rule['idType']) || ''
         rule_salt = rule['salt'] || rule['id'] || ''
         hash = compute_user_hash("#{config_salt}.#{rule_salt}.#{unit_id}")
         return (hash % 10000) < (rule['passPercentage'].to_f * 100)
@@ -479,14 +525,6 @@ module Statsig
       end
     end
 
-    def get_unit_id(user, id_type)
-      if id_type.is_a?(String) && id_type.downcase != 'userid'
-        return nil unless user&.custom_ids.is_a? Hash
-        return user.custom_ids[id_type] || user.custom_ids[id_type.downcase]
-      end
-      user.user_id
-    end
-
     def compute_user_hash(user_hash)
       Digest::SHA256.digest(user_hash).unpack('Q>')[0]
     end

data/lib/id_list.rb

@@ -19,7 +19,7 @@ module Statsig
     end
 
     def self.new_empty(json)
-      self.new(json)
+      new(json)
       @size = 0
     end
 

data/lib/interfaces/user_persistent_storage.rb

@@ -0,0 +1,12 @@
+# typed: true
+module Statsig
+  module Interfaces
+    class IUserPersistentStorage
+      def load(key)
+        nil
+      end
+
+      def save(key, data) end
+    end
+  end
+end

data/lib/layer.rb

@@ -17,11 +17,25 @@ class Layer
   sig { returns(String) }
   attr_accessor :rule_id
 
-  sig { params(name: String, value: T::Hash[String, T.untyped], rule_id: String, exposure_log_func: T.any(Method, Proc, NilClass)).void }
-  def initialize(name, value = {}, rule_id = '', exposure_log_func = nil)
+  sig { returns(String) }
+  attr_accessor :group_name
+
+  sig do
+    params(
+      name: String,
+      value: T::Hash[String, T.untyped],
+      rule_id: String,
+      group_name: T.nilable(String),
+      allocated_experiment: T.nilable(String),
+      exposure_log_func: T.any(Method, Proc, NilClass)
+    ).void
+  end
+  def initialize(name, value = {}, rule_id = '', group_name = nil, allocated_experiment = nil, exposure_log_func = nil)
     @name = name
     @value = value
     @rule_id = rule_id
+    @group_name = group_name
+    @allocated_experiment = allocated_experiment
     @exposure_log_func = exposure_log_func
   end
 
@@ -58,4 +72,4 @@ class Layer
 
     @value[index]
   end
-end
+end

data/lib/network.rb

@@ -53,11 +53,42 @@ module Statsig
       end
     end
 
+    sig do
+      params(since_time: Integer)
+        .returns([T.any(HTTP::Response, NilClass), T.any(StandardError, NilClass)])
+    end
+    def download_config_specs(since_time)
+      get("download_config_specs/#{@server_secret}.json?sinceTime=#{since_time}")
+    end
+
+    class HttpMethod < T::Enum
+      enums do
+        GET = new
+        POST = new
+      end
+    end
+
+    sig do
+      params(endpoint: String, retries: Integer, backoff: Integer)
+        .returns([T.any(HTTP::Response, NilClass), T.any(StandardError, NilClass)])
+    end
+    def get(endpoint, retries = 0, backoff = 1)
+      request(HttpMethod::GET, endpoint, nil, retries, backoff)
+    end
+
     sig do
       params(endpoint: String, body: String, retries: Integer, backoff: Integer)
         .returns([T.any(HTTP::Response, NilClass), T.any(StandardError, NilClass)])
     end
-    def post_helper(endpoint, body, retries = 0, backoff = 1)
+    def post(endpoint, body, retries = 0, backoff = 1)
+      request(HttpMethod::POST, endpoint, body, retries, backoff)
+    end
+
+    sig do
+      params(method: HttpMethod, endpoint: String, body: T.nilable(String), retries: Integer, backoff: Integer)
+        .returns([T.any(HTTP::Response, NilClass), T.any(StandardError, NilClass)])
+    end
+    def request(method, endpoint, body, retries = 0, backoff = 1)
       if @local_mode
         return nil, nil
       end
@@ -73,14 +104,20 @@ module Statsig
       url = URIHelper.build_url(endpoint)
       begin
         res = @connection_pool.with do |conn|
-          conn.headers('STATSIG-CLIENT-TIME' => (Time.now.to_f * 1000).to_i.to_s).post(url, body: body)
+          request = conn.headers('STATSIG-CLIENT-TIME' => (Time.now.to_f * 1000).to_i.to_s)
+          case method
+          when HttpMethod::GET
+            request.get(url)
+          when HttpMethod::POST
+            request.post(url, body: body)
+          end
         end
       rescue StandardError => e
         ## network error retry
         return nil, e unless retries.positive?
 
         sleep backoff_adjusted
-        return post_helper(endpoint, body, retries - 1, backoff * @backoff_multiplier)
+        return request(method, endpoint, body, retries - 1, backoff * @backoff_multiplier)
       end
       return res, nil if res.status.success?
 
@@ -91,12 +128,12 @@ module Statsig
 
       ## status code retry
       sleep backoff_adjusted
-      post_helper(endpoint, body, retries - 1, backoff * @backoff_multiplier)
+      request(method, endpoint, body, retries - 1, backoff * @backoff_multiplier)
     end
 
     def check_gate(user, gate_name)
       request_body = JSON.generate({ 'user' => user&.serialize(false), 'gateName' => gate_name })
-      response, = post_helper('check_gate', request_body)
+      response, = post('check_gate', request_body)
       return JSON.parse(response.body) unless response.nil?
 
       false
@@ -106,7 +143,7 @@ module Statsig
 
     def get_config(user, dynamic_config_name)
       request_body = JSON.generate({ 'user' => user&.serialize(false), 'configName' => dynamic_config_name })
-      response, = post_helper('get_config', request_body)
+      response, = post('get_config', request_body)
       return JSON.parse(response.body) unless response.nil?
 
       nil
@@ -116,7 +153,7 @@ module Statsig
 
     def post_logs(events)
       json_body = JSON.generate({ 'events' => events, 'statsigMetadata' => Statsig.get_statsig_metadata })
-      post_helper('log_event', json_body, @post_logs_retry_limit)
+      post('log_event', json_body, @post_logs_retry_limit)
     rescue StandardError
 
     end

data/lib/spec_store.rb

@@ -4,6 +4,7 @@ require 'uri'
 require 'evaluation_details'
 require 'id_list'
 require 'concurrent-ruby'
+require 'hash_utils'
 
 module Statsig
   class SpecStore
@@ -28,7 +29,8 @@ module Statsig
         :layers => {},
         :id_lists => {},
         :experiment_to_layer => {},
-        :sdk_keys_to_app_ids => {}
+        :sdk_keys_to_app_ids => {},
+        :hashed_sdk_keys_to_app_ids => {}
       }
       @diagnostics = diagnostics
       @error_boundary = error_boundary
@@ -127,10 +129,18 @@ module Statsig
       @specs[:sdk_keys_to_app_ids].key?(sdk_key)
     end
 
+    def has_hashed_sdk_key?(hashed_sdk_key)
+      @specs[:hashed_sdk_keys_to_app_ids].key?(hashed_sdk_key)
+    end
+
     def get_app_id_for_sdk_key(sdk_key)
       if sdk_key.nil?
         return nil
       end
+      hashed_sdk_key = Statsig::HashUtils.djb2(sdk_key)
+      if has_hashed_sdk_key?(hashed_sdk_key)
+        return @specs[:hashed_sdk_keys_to_app_ids][hashed_sdk_key]
+      end
       return nil unless has_sdk_key?(sdk_key)
       @specs[:sdk_keys_to_app_ids][sdk_key]
     end
@@ -228,7 +238,7 @@ module Statsig
 
       error = nil
       begin
-        response, e = @network.post_helper('download_config_specs', JSON.generate({ 'sinceTime' => @last_config_sync_time }))
+        response, e = @network.download_config_specs(@last_config_sync_time)
         code = response&.status.to_i
         if e.is_a? NetworkError
           code = e.http_code
@@ -293,6 +303,7 @@ module Statsig
       @specs[:layers] = new_layers
       @specs[:experiment_to_layer] = new_exp_to_layer
       @specs[:sdk_keys_to_app_ids] = specs_json['sdk_keys_to_app_ids'] || {}
+      @specs[:hashed_sdk_keys_to_app_ids] = specs_json['hashed_sdk_keys_to_app_ids'] || {}
 
       unless from_adapter
         save_config_specs_to_storage_adapter(specs_string)
@@ -323,7 +334,7 @@ module Statsig
 
     def get_id_lists_from_network
       tracker = @diagnostics.track('get_id_list_sources', 'network_request')
-      response, e = @network.post_helper('get_id_lists', JSON.generate({ 'statsigMetadata' => Statsig.get_statsig_metadata }))
+      response, e = @network.post('get_id_lists', JSON.generate({ 'statsigMetadata' => Statsig.get_statsig_metadata }))
       code = response&.status.to_i
       if e.is_a? NetworkError
         code = e.http_code

data/lib/statsig.rb

@@ -26,15 +26,20 @@ module Statsig
     @shared_instance = StatsigDriver.new(secret_key, options, error_callback)
   end
 
-  sig { params(user: StatsigUser, gate_name: String).returns(T::Boolean) }
+  class CheckGateOptions < T::Struct
+    prop :disable_log_exposure, T::Boolean, default: false
+  end
+
+  sig { params(user: StatsigUser, gate_name: String, options: CheckGateOptions).returns(T::Boolean) }
   ##
   # Gets the boolean result of a gate, evaluated against the given user. An exposure event will automatically be logged for the gate.
   #
   # @param user A StatsigUser object used for the evaluation
   # @param gate_name The name of the gate being checked
-  def self.check_gate(user, gate_name)
+  # @param options Additional options for evaluating the gate
+  def self.check_gate(user, gate_name, options = CheckGateOptions.new)
     ensure_initialized
-    @shared_instance&.check_gate(user, gate_name)
+    @shared_instance&.check_gate(user, gate_name, options)
   end
 
   sig { params(user: StatsigUser, gate_name: String).returns(T::Boolean) }
@@ -45,7 +50,7 @@ module Statsig
   # @param gate_name The name of the gate being checked
   def self.check_gate_with_exposure_logging_disabled(user, gate_name)
     ensure_initialized
-    @shared_instance&.check_gate(user, gate_name, StatsigDriver::CheckGateOptions.new(log_exposure: false))
+    @shared_instance&.check_gate(user, gate_name, CheckGateOptions.new(disable_log_exposure: true))
   end
 
   sig { params(user: StatsigUser, gate_name: String).void }
@@ -59,15 +64,20 @@ module Statsig
     @shared_instance&.manually_log_gate_exposure(user, gate_name)
   end
 
-  sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
+  class GetConfigOptions < T::Struct
+    prop :disable_log_exposure, T::Boolean, default: false
+  end
+
+  sig { params(user: StatsigUser, dynamic_config_name: String, options: GetConfigOptions).returns(DynamicConfig) }
   ##
   # Get the values of a dynamic config, evaluated against the given user. An exposure event will automatically be logged for the dynamic config.
   #
   # @param user A StatsigUser object used for the evaluation
   # @param dynamic_config_name The name of the dynamic config
-  def self.get_config(user, dynamic_config_name)
+  # @param options Additional options for evaluating the config
+  def self.get_config(user, dynamic_config_name, options = GetConfigOptions.new)
     ensure_initialized
-    @shared_instance&.get_config(user, dynamic_config_name)
+    @shared_instance&.get_config(user, dynamic_config_name, options)
   end
 
   sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
@@ -78,7 +88,7 @@ module Statsig
   # @param dynamic_config_name The name of the dynamic config
   def self.get_config_with_exposure_logging_disabled(user, dynamic_config_name)
     ensure_initialized
-    @shared_instance&.get_config(user, dynamic_config_name, StatsigDriver::GetConfigOptions.new(log_exposure: false))
+    @shared_instance&.get_config(user, dynamic_config_name, GetConfigOptions.new(disable_log_exposure: true))
   end
 
   sig { params(user: StatsigUser, dynamic_config: String).void }
@@ -92,15 +102,21 @@ module Statsig
     @shared_instance&.manually_log_config_exposure(user, dynamic_config)
   end
 
-  sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
+  class GetExperimentOptions < T::Struct
+    prop :disable_log_exposure, T::Boolean, default: false
+    prop :user_persisted_values, T.nilable(T::Hash[String, Hash]), default: nil
+  end
+
+  sig { params(user: StatsigUser, experiment_name: String, options: GetExperimentOptions).returns(DynamicConfig) }
   ##
   # Get the values of an experiment, evaluated against the given user. An exposure event will automatically be logged for the experiment.
   #
   # @param user A StatsigUser object used for the evaluation
   # @param experiment_name The name of the experiment
-  def self.get_experiment(user, experiment_name)
+  # @param options Additional options for evaluating the experiment
+  def self.get_experiment(user, experiment_name, options = GetExperimentOptions.new)
     ensure_initialized
-    @shared_instance&.get_experiment(user, experiment_name)
+    @shared_instance&.get_experiment(user, experiment_name, options)
   end
 
   sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
@@ -111,7 +127,7 @@ module Statsig
   # @param experiment_name The name of the experiment
   def self.get_experiment_with_exposure_logging_disabled(user, experiment_name)
     ensure_initialized
-    @shared_instance&.get_experiment(user, experiment_name, StatsigDriver::GetExperimentOptions.new(log_exposure: false))
+    @shared_instance&.get_experiment(user, experiment_name, GetExperimentOptions.new(disable_log_exposure: true))
   end
 
   sig { params(user: StatsigUser, experiment_name: String).void }
@@ -125,16 +141,26 @@ module Statsig
     @shared_instance&.manually_log_config_exposure(user, experiment_name)
   end
 
-  sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
+  sig { params(user: StatsigUser, id_type: String).returns(UserPersistedValues) }
+  def self.get_user_persisted_values(user, id_type)
+    ensure_initialized
+    @shared_instance&.get_user_persisted_values(user, id_type)
+  end
+
+  class GetLayerOptions < T::Struct
+    prop :disable_log_exposure, T::Boolean, default: false
+  end
+
+  sig { params(user: StatsigUser, layer_name: String, options: GetLayerOptions).returns(Layer) }
   ##
   # Get the values of a layer, evaluated against the given user.
   # Exposure events will be fired when get or get_typed is called on the resulting Layer class.
   #
   # @param user A StatsigUser object used for the evaluation
   # @param layer_name The name of the layer
-  def self.get_layer(user, layer_name)
+  def self.get_layer(user, layer_name, options = GetLayerOptions.new)
     ensure_initialized
-    @shared_instance&.get_layer(user, layer_name)
+    @shared_instance&.get_layer(user, layer_name, options)
   end
 
   sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
@@ -145,7 +171,7 @@ module Statsig
   # @param layer_name The name of the layer
   def self.get_layer_with_exposure_logging_disabled(user, layer_name)
     ensure_initialized
-    @shared_instance&.get_layer(user, layer_name, StatsigDriver::GetLayerOptions.new(log_exposure: false))
+    @shared_instance&.get_layer(user, layer_name, GetLayerOptions.new(disable_log_exposure: true))
   end
 
   sig { params(user: StatsigUser, layer_name: String, parameter_name: String).void }
@@ -239,7 +265,7 @@ module Statsig
   def self.get_statsig_metadata
     {
       'sdkType' => 'ruby-server',
-      'sdkVersion' => '1.28.0',
+      'sdkVersion' => '1.29.0',
     }
   end
 
@@ -252,7 +278,6 @@ module Statsig
   end
 
   sig { params(options: T.any(StatsigOptions, NilClass)).void }
-
   def self.bind_sorbet_loggers(options)
     if options&.disable_sorbet_logging_handlers == true
       return

data/lib/statsig_driver.rb

@@ -19,7 +19,6 @@ class StatsigDriver
   extend T::Sig
 
   sig { params(secret_key: String, options: T.any(StatsigOptions, NilClass), error_callback: T.any(Method, Proc, NilClass)).void }
-
   def initialize(secret_key, options = nil, error_callback = nil)
     unless secret_key.start_with?('secret-')
       raise Statsig::ValueError.new('Invalid secret key provided. Provide your project secret key from the Statsig console')
@@ -38,20 +37,16 @@ class StatsigDriver
       @secret_key = secret_key
       @net = Statsig::Network.new(secret_key, @options)
       @logger = Statsig::StatsigLogger.new(@net, @options, @err_boundary)
-      @evaluator = Statsig::Evaluator.new(@net, @options, error_callback, @diagnostics, @err_boundary, @logger)
+      @persistent_storage_utils = Statsig::UserPersistentStorageUtils.new(@options)
+      @evaluator = Statsig::Evaluator.new(@net, @options, error_callback, @diagnostics, @err_boundary, @logger, @persistent_storage_utils)
       tracker.end(success: true)
 
       @logger.log_diagnostics_event(@diagnostics)
     }, caller: __method__.to_s)
   end
 
-  class CheckGateOptions < T::Struct
-    prop :log_exposure, T::Boolean, default: true
-  end
-
-  sig { params(user: StatsigUser, gate_name: String, options: CheckGateOptions).returns(T::Boolean) }
-
-  def check_gate(user, gate_name, options = CheckGateOptions.new)
+  sig { params(user: StatsigUser, gate_name: String, options: Statsig::CheckGateOptions).returns(T::Boolean) }
+  def check_gate(user, gate_name, options = Statsig::CheckGateOptions.new)
     @err_boundary.capture(task: lambda {
       run_with_diagnostics(task: lambda {
         user = verify_inputs(user, gate_name, "gate_name")
@@ -65,7 +60,7 @@ class StatsigDriver
           res = check_gate_fallback(user, gate_name)
           # exposure logged by the server
         else
-          if options.log_exposure
+          if !options.disable_log_exposure
             @logger.log_gate_exposure(user, res.name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details)
           end
         end
@@ -76,7 +71,6 @@ class StatsigDriver
   end
 
   sig { params(user: StatsigUser, gate_name: String).void }
-
   def manually_log_gate_exposure(user, gate_name)
     @err_boundary.capture(task: lambda {
       res = @evaluator.check_gate(user, gate_name)
@@ -85,38 +79,27 @@ class StatsigDriver
     })
   end
 
-  class GetConfigOptions < T::Struct
-    prop :log_exposure, T::Boolean, default: true
-  end
-
-  sig { params(user: StatsigUser, dynamic_config_name: String, options: GetConfigOptions).returns(DynamicConfig) }
-
-  def get_config(user, dynamic_config_name, options = GetConfigOptions.new)
+  sig { params(user: StatsigUser, dynamic_config_name: String, options: Statsig::GetConfigOptions).returns(DynamicConfig) }
+  def get_config(user, dynamic_config_name, options = Statsig::GetConfigOptions.new)
     @err_boundary.capture(task: lambda {
       run_with_diagnostics(task: lambda {
         user = verify_inputs(user, dynamic_config_name, "dynamic_config_name")
-        get_config_impl(user, dynamic_config_name, options)
+        get_config_impl(user, dynamic_config_name, options.disable_log_exposure)
       }, caller: __method__.to_s)
     }, recover: -> { DynamicConfig.new(dynamic_config_name) }, caller: __method__.to_s)
   end
 
-  class GetExperimentOptions < T::Struct
-    prop :log_exposure, T::Boolean, default: true
-  end
-
-  sig { params(user: StatsigUser, experiment_name: String, options: GetExperimentOptions).returns(DynamicConfig) }
-
-  def get_experiment(user, experiment_name, options = GetExperimentOptions.new)
+  sig { params(user: StatsigUser, experiment_name: String, options: Statsig::GetExperimentOptions).returns(DynamicConfig) }
+  def get_experiment(user, experiment_name, options = Statsig::GetExperimentOptions.new)
     @err_boundary.capture(task: lambda {
       run_with_diagnostics(task: lambda {
         user = verify_inputs(user, experiment_name, "experiment_name")
-        get_config_impl(user, experiment_name, options)
+        get_config_impl(user, experiment_name, options.disable_log_exposure, user_persisted_values: options.user_persisted_values)
       }, caller: __method__.to_s)
     }, recover: -> { DynamicConfig.new(experiment_name) }, caller: __method__.to_s)
   end
 
   sig { params(user: StatsigUser, config_name: String).void }
-
   def manually_log_config_exposure(user, config_name)
     @err_boundary.capture(task: lambda {
       res = @evaluator.get_config(user, config_name)
@@ -125,13 +108,18 @@ class StatsigDriver
     }, caller: __method__.to_s)
   end
 
-  class GetLayerOptions < T::Struct
-    prop :log_exposure, T::Boolean, default: true
-  end
+  sig { params(user: StatsigUser, id_type: String).returns(Statsig::UserPersistedValues) }
+  def get_user_persisted_values(user, id_type)
+    @err_boundary.capture(task: lambda {
+      persisted_values = @persistent_storage_utils.get_user_persisted_values(user, id_type)
+      return {} if persisted_values.nil?
 
-  sig { params(user: StatsigUser, layer_name: String, options: GetLayerOptions).returns(Layer) }
+      persisted_values
+    }, caller: __method__.to_s)
+  end
 
-  def get_layer(user, layer_name, options = GetLayerOptions.new)
+  sig { params(user: StatsigUser, layer_name: String, options: Statsig::GetLayerOptions).returns(Layer) }
+  def get_layer(user, layer_name, options = Statsig::GetLayerOptions.new)
     @err_boundary.capture(task: lambda {
       run_with_diagnostics(task: lambda {
         user = verify_inputs(user, layer_name, "layer_name")
@@ -142,27 +130,26 @@ class StatsigDriver
         end
 
         if res == $fetch_from_server
-          if res.config_delegate.empty?
+          if res.config_delegate.nil?
             return Layer.new(layer_name)
           end
           res = get_config_fallback(user, res.config_delegate)
           # exposure logged by the server
         end
 
-        exposure_log_func = options.log_exposure ? lambda { |layer, parameter_name|
+        exposure_log_func = !options.disable_log_exposure ? lambda { |layer, parameter_name|
           @logger.log_layer_exposure(user, layer, parameter_name, res)
         } : nil
-        Layer.new(res.name, res.json_value, res.rule_id, exposure_log_func)
+        Layer.new(res.name, res.json_value, res.rule_id, res.group_name, res.config_delegate, exposure_log_func)
       }, caller: __method__.to_s)
     }, recover: lambda { Layer.new(layer_name) }, caller: __method__.to_s)
   end
 
   sig { params(user: StatsigUser, layer_name: String, parameter_name: String).void }
-
   def manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
     @err_boundary.capture(task: lambda {
       res = @evaluator.get_layer(user, layer_name)
-      layer = Layer.new(layer_name, res.json_value, res.rule_id)
+      layer = Layer.new(layer_name, res.json_value, res.rule_id, res.group_name, res.config_delegate)
       context = { 'is_manual_exposure' => true }
       @logger.log_layer_exposure(user, layer, parameter_name, res, context)
     }, caller: __method__.to_s)
@@ -260,7 +247,6 @@ class StatsigDriver
   end
 
   sig { params(user: StatsigUser, config_name: String, variable_name: String).returns(StatsigUser) }
-
   def verify_inputs(user, config_name, variable_name)
     validate_user(user)
     if !config_name.is_a?(String) || config_name.empty?
@@ -272,8 +258,16 @@ class StatsigDriver
     normalize_user(user)
   end
 
-  def get_config_impl(user, config_name, options)
-    res = @evaluator.get_config(user, config_name)
+  sig do
+    params(
+      user: StatsigUser,
+      config_name: String,
+      disable_log_exposure: T::Boolean,
+      user_persisted_values: T.nilable(Statsig::UserPersistedValues)
+    ).returns(DynamicConfig)
+  end
+  def get_config_impl(user, config_name, disable_log_exposure, user_persisted_values: nil)
+    res = @evaluator.get_config(user, config_name, user_persisted_values: user_persisted_values)
     if res.nil?
       res = Statsig::ConfigResult.new(config_name)
     end
@@ -282,12 +276,12 @@ class StatsigDriver
       res = get_config_fallback(user, config_name)
       # exposure logged by the server
     else
-      if options.log_exposure
+      if !disable_log_exposure
         @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details)
       end
     end
 
-    DynamicConfig.new(res.name, res.json_value, res.rule_id, res.group_name, res.id_type)
+    DynamicConfig.new(res.name, res.json_value, res.rule_id, res.group_name, res.id_type, res.evaluation_details)
   end
 
   def validate_user(user)

data/lib/statsig_options.rb

@@ -2,6 +2,7 @@
 
 require 'sorbet-runtime'
 require_relative 'interfaces/data_store'
+require_relative 'interfaces/user_persistent_storage'
 
 ##
 # Configuration options for the Statsig SDK.
@@ -21,7 +22,7 @@ class StatsigOptions
 
   # The base url used specifically to call download_config_specs.
   # Takes precedence over api_url_base
-  sig { returns(T.any(String, NilClass)) }
+  sig { returns(String) }
   attr_accessor :api_url_download_config_specs
 
   sig { returns(T.any(Float, Integer)) }
@@ -106,10 +107,15 @@ class StatsigOptions
   # which overrides the default backoff time between retries
   attr_accessor :post_logs_retry_backoff
 
+  sig { returns(T.any(Statsig::Interfaces::IUserPersistentStorage, NilClass)) }
+  # A storage adapter for persisted values. Can be used for sticky bucketing users in experiments.
+  # Implements Statsig::Interfaces::IUserPersistentStorage.
+  attr_accessor :user_persistent_storage
+
   sig do
     params(
       environment: T.any(T::Hash[String, String], NilClass),
-      api_url_base: String,
+      api_url_base: T.nilable(String),
       api_url_download_config_specs: T.any(String, NilClass),
       rulesets_sync_interval: T.any(Float, Integer),
       idlists_sync_interval: T.any(Float, Integer),
@@ -127,13 +133,13 @@ class StatsigOptions
       disable_sorbet_logging_handlers: T::Boolean,
       network_timeout: T.any(Integer, NilClass),
       post_logs_retry_limit: Integer,
-      post_logs_retry_backoff: T.any(Method, Proc, Integer, NilClass)
+      post_logs_retry_backoff: T.any(Method, Proc, Integer, NilClass),
+      user_persistent_storage: T.any(Statsig::Interfaces::IUserPersistentStorage, NilClass)
     ).void
   end
-
   def initialize(
     environment = nil,
-    api_url_base = 'https://statsigapi.net/v1',
+    api_url_base = nil,
     api_url_download_config_specs: nil,
     rulesets_sync_interval: 10,
     idlists_sync_interval: 60,
@@ -151,10 +157,12 @@ class StatsigOptions
     disable_sorbet_logging_handlers: false,
     network_timeout: nil,
     post_logs_retry_limit: 3,
-    post_logs_retry_backoff: nil)
+    post_logs_retry_backoff: nil,
+    user_persistent_storage: nil
+  )
     @environment = environment.is_a?(Hash) ? environment : nil
-    @api_url_base = api_url_base
-    @api_url_download_config_specs = api_url_download_config_specs
+    @api_url_base = api_url_base || 'https://statsigapi.net/v1'
+    @api_url_download_config_specs = api_url_download_config_specs || api_url_base || 'https://api.statsigcdn.com/v1'
     @rulesets_sync_interval = rulesets_sync_interval
     @idlists_sync_interval = idlists_sync_interval
     @disable_rulesets_sync = disable_rulesets_sync
@@ -172,5 +180,7 @@ class StatsigOptions
     @network_timeout = network_timeout
     @post_logs_retry_limit = post_logs_retry_limit
     @post_logs_retry_backoff = post_logs_retry_backoff
+    @user_persistent_storage = user_persistent_storage
+
   end
-end
+end

data/lib/statsig_user.rb

@@ -49,7 +49,6 @@ class StatsigUser
   attr_accessor :private_attributes
 
   sig { returns(T.any(T::Hash[String, T.untyped], NilClass)) }
-
   def custom
     @custom
   end
@@ -61,7 +60,6 @@ class StatsigUser
   end
 
   sig { params(user_hash: T.any(T::Hash[T.any(String, Symbol), T.untyped], NilClass)).void }
-
   def initialize(user_hash)
     the_hash = user_hash
     begin
@@ -166,6 +164,15 @@ class StatsigUser
     }
   end
 
+  def get_unit_id(id_type)
+    if id_type.is_a?(String) && id_type.downcase != 'userid'
+      return nil unless @custom_ids.is_a? Hash
+
+      return @custom_ids[id_type] || @custom_ids[id_type.downcase]
+    end
+    @user_id
+  end
+
   private
 
   sig {
@@ -189,5 +196,4 @@ class StatsigUser
 
     nil
   end
-
-end
+end

data/lib/uri_helper.rb

@@ -17,7 +17,7 @@ class URIHelper
     sig { params(endpoint: String).returns(String) }
     def build_url(endpoint)
       api = @options.api_url_base
-      if endpoint == 'download_config_specs' && !@options.api_url_download_config_specs.nil?
+      if endpoint.include?('download_config_specs')
         api = T.must(@options.api_url_download_config_specs)
       end
       unless api.end_with?('/')

data/lib/user_persistent_storage_utils.rb

@@ -0,0 +1,106 @@
+# typed: false
+
+require 'sorbet-runtime'
+require 'statsig_options'
+
+module Statsig
+  UserPersistedValues = T.type_alias { T::Hash[String, Hash] }
+
+  class UserPersistentStorageUtils
+    extend T::Sig
+
+    sig { returns(T::Hash[String, UserPersistedValues]) }
+    attr_accessor :cache
+
+    sig { returns(T.nilable(Interfaces::IUserPersistentStorage)) }
+    attr_accessor :storage
+
+    sig { params(options: StatsigOptions).void }
+    def initialize(options)
+      @storage = options.user_persistent_storage
+      @cache = {}
+    end
+
+    sig { params(user: StatsigUser, id_type: String).returns(T.nilable(UserPersistedValues)) }
+    def get_user_persisted_values(user, id_type)
+      key = self.class.get_storage_key(user, id_type)
+      return @cache[key] unless @cache[key].nil?
+
+      return load_from_storage(key)
+    end
+
+    sig { params(key: String).returns(T.nilable(UserPersistedValues)) }
+    def load_from_storage(key)
+      return if @storage.nil?
+
+      begin
+        storage_values = @storage.load(key)
+      rescue StandardError => e
+        puts "Failed to load key (#{key}) from user_persisted_storage (#{e.message})"
+        return nil
+      end
+
+      unless storage_values.nil?
+        parsed_values = self.class.parse(storage_values)
+        unless parsed_values.nil?
+          @cache[key] = parsed_values
+          return @cache[key]
+        end
+      end
+      return nil
+    end
+
+    sig { params(user: StatsigUser, id_type: String, user_persisted_values: UserPersistedValues).void }
+    def save_to_storage(user, id_type, user_persisted_values)
+      return if @storage.nil?
+
+      key = self.class.get_storage_key(user, id_type)
+      stringified = self.class.stringify(user_persisted_values)
+      return if stringified.nil?
+
+      begin
+        @storage.save(key, stringified)
+      rescue StandardError => e
+        puts "Failed to save key (#{key}) to user_persisted_storage (#{e.message})"
+      end
+    end
+
+    sig { params(user: StatsigUser, id_type: String, config_name: String).void }
+    def remove_experiment_from_storage(user, id_type, config_name)
+      persisted_values = get_user_persisted_values(user, id_type)
+      unless persisted_values.nil?
+        persisted_values.delete(config_name)
+        save_to_storage(user, id_type, persisted_values)
+      end
+    end
+
+    sig { params(user_persisted_values: T.nilable(UserPersistedValues), config_name: String, evaluation: ConfigResult).void }
+    def add_evaluation_to_user_persisted_values(user_persisted_values, config_name, evaluation)
+      if user_persisted_values.nil?
+        user_persisted_values = {}
+      end
+      user_persisted_values[config_name] = evaluation.to_hash
+    end
+
+    private
+
+    sig { params(values_string: String).returns(T.nilable(UserPersistedValues)) }
+    def self.parse(values_string)
+      return JSON.parse(values_string)
+    rescue JSON::ParserError
+      return nil
+    end
+
+    sig { params(values_object: UserPersistedValues).returns(T.nilable(String)) }
+    def self.stringify(values_object)
+      return JSON.generate(values_object)
+    rescue StandardError
+      return nil
+    end
+
+    sig { params(user: StatsigUser, id_type: String).returns(String) }
+    def self.get_storage_key(user, id_type)
+      "#{user.get_unit_id(id_type)}:#{id_type}"
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statsig
 version: !ruby/object:Gem::Version
-  version: 1.28.0
+  version: 1.29.0
 platform: ruby
 authors:
 - Statsig, Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-03 00:00:00.000000000 Z
+date: 2023-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -333,6 +333,7 @@ files:
 - lib/hash_utils.rb
 - lib/id_list.rb
 - lib/interfaces/data_store.rb
+- lib/interfaces/user_persistent_storage.rb
 - lib/layer.rb
 - lib/network.rb
 - lib/spec_store.rb
@@ -345,6 +346,7 @@ files:
 - lib/statsig_user.rb
 - lib/ua_parser.rb
 - lib/uri_helper.rb
+- lib/user_persistent_storage_utils.rb
 homepage: https://rubygems.org/gems/statsig
 licenses:
 - ISC