amplitude-experiment 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f40750aa31cc9abd90da453ed66d9c8af7ab7732d4887b248e47b9a878a159a7
-  data.tar.gz: 87064809c68b48a71ec4769f36fb797fc6757b763626ceb9e6a5e5a1d5656049
+  metadata.gz: d1474764e3ae979eb8f3799a76f42513ff707a7307d7dc2eae9d9d6da4bef36f
+  data.tar.gz: 889f7ba4cc9860523c7a5b6854b19e75b54ac8ae6330414007142779cbe7f2f3
 SHA512:
-  metadata.gz: c235e7a780773a4ea5873a1139917fdb3929b4bb27139a02a960f040c863226cc01f0ac3188fc4628c45897d2823c41ba383dc1d9f517f15b69c671d971b6397
-  data.tar.gz: cd4d84c2d088dfc265910c7a57147f9d54ef34d747959d172ff1623b21f96b85f1ff409bdde06900aedec6a15941e19b2a0d83da5f0ff8d8e09b4dc1027f08d4
+  metadata.gz: 705c6b31291bf96b3f9ea93ea3c166aa8e61f28b80bf0253261d42374895e1b8f923b3536b9308a3cd03b2ba9f7d4654abdfd2e2894fe19a802d3f658b454e3a
+  data.tar.gz: ff192b072846e12ede79277411bde7e38075be600707138a8a25090c6e325425aa1ed72c10b09fdda9c9a1e1c4dcb409c32f06ed26e3b36a27b4db0127ceeecc

data/lib/amplitude-experiment.rb

@@ -9,10 +9,15 @@ require 'experiment/remote/client'
 require 'experiment/remote/fetch_options'
 require 'experiment/local/client'
 require 'experiment/local/config'
+require 'experiment/local/evaluate_options'
 require 'experiment/local/assignment/assignment'
 require 'experiment/local/assignment/assignment_filter'
 require 'experiment/local/assignment/assignment_service'
 require 'experiment/local/assignment/assignment_config'
+require 'experiment/local/exposure/exposure'
+require 'experiment/local/exposure/exposure_filter'
+require 'experiment/local/exposure/exposure_service'
+require 'experiment/local/exposure/exposure_config'
 require 'experiment/util/lru_cache'
 require 'experiment/util/hash'
 require 'experiment/util/user'

data/lib/experiment/local/assignment/assignment.rb

@@ -1,6 +1,7 @@
 module AmplitudeExperiment
   DAY_MILLIS = 86_400_000
   # Assignment
+  # @deprecated Assignment tracking is deprecated. Use Exposure with ExposureService instead.
   class Assignment
     attr_accessor :user, :results, :timestamp
 

data/lib/experiment/local/assignment/assignment_config.rb

@@ -1,5 +1,6 @@
 module AmplitudeExperiment
   # AssignmentConfig
+  # @deprecated Assignment tracking is deprecated. Use ExposureConfig with ExposureService instead.
   class AssignmentConfig < AmplitudeAnalytics::Config
     attr_accessor :api_key, :cache_capacity
 

data/lib/experiment/local/assignment/assignment_filter.rb

@@ -1,5 +1,6 @@
 module AmplitudeExperiment
   # AssignmentFilter
+  # @deprecated Assignment tracking is deprecated. Use ExposureFilter with ExposureService instead.
   class AssignmentFilter
     def initialize(size, ttl_millis = DAY_MILLIS)
       @cache = LRUCache.new(size, ttl_millis)

data/lib/experiment/local/assignment/assignment_service.rb

@@ -1,6 +1,7 @@
 require_relative '../../../amplitude'
 module AmplitudeExperiment
   # AssignmentService
+  # @deprecated Assignment tracking is deprecated. Use ExposureService with Exposure tracking instead.
   class AssignmentService
     def initialize(amplitude, assignment_filter)
       @amplitude = amplitude

data/lib/experiment/local/client.rb

@@ -26,6 +26,10 @@ module AmplitudeExperiment
       @assignment_service = nil
       @assignment_service = AssignmentService.new(AmplitudeAnalytics::Amplitude.new(config.assignment_config.api_key, configuration: config.assignment_config), AssignmentFilter.new(config.assignment_config.cache_capacity)) if config&.assignment_config
 
+      # Exposure service is always instantiated, using deployment key if no api key provided
+      @exposure_service = nil
+      @exposure_service = ExposureService.new(AmplitudeAnalytics::Amplitude.new(config.exposure_config.api_key, configuration: config.exposure_config), ExposureFilter.new(config.exposure_config.cache_capacity)) if config&.exposure_config
+
       @cohort_storage = InMemoryCohortStorage.new
       @flag_config_storage = InMemoryFlagConfigStorage.new
       @flag_config_fetcher = LocalEvaluationFetcher.new(@api_key, @logger, @config.server_url)
@@ -53,6 +57,7 @@ module AmplitudeExperiment
       AmplitudeExperiment.filter_default_variants(variants)
     end
 
+    # TODO: ruby backwards compatibility for evaluate_v2 to be looked at again
     # Locally evaluates flag variants for a user.
     #  This function will only evaluate flags for the keys specified in the flag_keys argument. If flag_keys is
     #  missing or None, all flags are evaluated. This function differs from evaluate as it will return a default
@@ -60,8 +65,9 @@ module AmplitudeExperiment
     #
     # @param [User] user The user to evaluate
     # @param [String[]] flag_keys The flags to evaluate with the user, if empty all flags are evaluated
+    # @param [EvaluateOptions] options Optional evaluation options
     # @return [Hash[String, Variant]] The evaluated variants
-    def evaluate_v2(user, flag_keys = [])
+    def evaluate_v2(user, flag_keys = [], options = nil)
       flags = @flag_config_storage.flag_configs
       return {} if flags.nil?
 
@@ -74,6 +80,8 @@ module AmplitudeExperiment
       result = @engine.evaluate(context, sorted_flags)
       @logger.debug("[Experiment] evaluate - result: #{result}") if @config.debug
       variants = AmplitudeExperiment.evaluation_variants_json_to_variants(result)
+      @exposure_service&.track(Exposure.new(user, variants)) if options&.tracks_exposure == true
+      # @deprecated Assignment tracking is deprecated. Use ExposureService with Exposure tracking instead.
       @assignment_service&.track(Assignment.new(user, variants))
       variants
     end

data/lib/experiment/local/config.rb

@@ -35,9 +35,14 @@ module AmplitudeExperiment
     attr_accessor :flag_config_polling_interval_millis
 
     # Configuration for automatically tracking assignment events after an evaluation.
+    # @deprecated use exposure_config instead
     # @return [AssignmentConfig] the config instance
     attr_accessor :assignment_config
 
+    # Configuration for automatically tracking exposure events after an evaluation.
+    # @return [ExposureConfig] the config instance
+    attr_accessor :exposure_config
+
     # Configuration for downloading cohorts required for flag evaluation
     # @return [CohortSyncConfig] the config instance
     attr_accessor :cohort_sync_config
@@ -48,7 +53,8 @@ module AmplitudeExperiment
     # @param [String] server_zone Location of the Amplitude data center to get flags and cohorts from, US or EU
     # @param [Hash] bootstrap The value of bootstrap.
     # @param [long] flag_config_polling_interval_millis The value of flag config polling interval in million seconds.
-    # @param [AssignmentConfig] assignment_config Configuration for automatically tracking assignment events after an evaluation.
+    # @param [AssignmentConfig] assignment_config Configuration for automatically tracking assignment events after an evaluation. @deprecated use exposure_config instead
+    # @param [ExposureConfig] exposure_config Configuration for automatically tracking exposure events after an evaluation.
     # @param [CohortSyncConfig] cohort_sync_config Configuration for downloading cohorts required for flag evaluation
     def initialize(server_url: DEFAULT_SERVER_URL,
                    server_zone: ServerZone::US,
@@ -57,6 +63,7 @@ module AmplitudeExperiment
                    debug: false,
                    logger: nil,
                    assignment_config: nil,
+                   exposure_config: nil,
                    cohort_sync_config: nil)
       @logger = logger
       if logger.nil?
@@ -73,6 +80,7 @@ module AmplitudeExperiment
       @bootstrap = bootstrap
       @flag_config_polling_interval_millis = flag_config_polling_interval_millis
       @assignment_config = assignment_config
+      @exposure_config = exposure_config
     end
   end
 end

data/lib/experiment/local/evaluate_options.rb

@@ -0,0 +1,10 @@
+module AmplitudeExperiment
+  # Options for evaluating variants for a user.
+  class EvaluateOptions
+    attr_accessor :tracks_exposure
+
+    def initialize(tracks_exposure: nil)
+      @tracks_exposure = tracks_exposure
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure.rb

@@ -0,0 +1,22 @@
+module AmplitudeExperiment
+  # Exposure is a class that represents a user's exposure to a set of flags.
+  class Exposure
+    attr_accessor :user, :results, :timestamp
+
+    def initialize(user, results)
+      @user = user
+      @results = results
+      @timestamp = (Time.now.to_f * 1000).to_i
+    end
+
+    def canonicalize
+      sb = "#{@user&.user_id&.strip} #{@user&.device_id&.strip} "
+      results.sort.to_h.each do |key, value|
+        next unless value.key
+
+        sb += "#{key.strip} #{value.key&.strip} "
+      end
+      sb
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure_config.rb

@@ -0,0 +1,12 @@
+module AmplitudeExperiment
+  # ExposureConfig
+  class ExposureConfig < AmplitudeAnalytics::Config
+    attr_accessor :api_key, :cache_capacity
+
+    def initialize(api_key = nil, cache_capacity = 65_536, **kwargs)
+      super(**kwargs)
+      @api_key = api_key
+      @cache_capacity = cache_capacity
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure_filter.rb

@@ -0,0 +1,20 @@
+module AmplitudeExperiment
+  # ExposureFilter
+  class ExposureFilter
+    attr_accessor :ttl_millis
+
+    def initialize(size, ttl_millis = DAY_MILLIS)
+      @cache = LRUCache.new(size, ttl_millis)
+      @ttl_millis = ttl_millis
+    end
+
+    def should_track(exposure)
+      return false if exposure.results.empty?
+
+      canonical_exposure = exposure.canonicalize
+      track = @cache.get(canonical_exposure).nil?
+      @cache.put(canonical_exposure, 0) if track
+      track
+    end
+  end
+end

data/lib/experiment/local/exposure/exposure_service.rb

@@ -0,0 +1,71 @@
+require_relative '../../../amplitude'
+module AmplitudeExperiment
+  # ExposureService
+  class ExposureService
+    def initialize(amplitude, exposure_filter)
+      @amplitude = amplitude
+      @exposure_filter = exposure_filter
+    end
+
+    def track(exposure)
+      return unless @exposure_filter.should_track(exposure)
+
+      events = ExposureService.to_exposure_events(exposure, @exposure_filter.ttl_millis)
+      events.each do |event|
+        @amplitude.track(event)
+      end
+    end
+
+    def self.to_exposure_events(exposure, ttl_millis)
+      events = []
+      canonicalized = exposure.canonicalize
+      exposure.results.each do |flag_key, variant|
+        track_exposure = variant.metadata ? variant.metadata.fetch('trackExposure', true) : true
+        next unless track_exposure
+
+        # Skip default variant exposures
+        is_default = variant.metadata ? variant.metadata.fetch('default', false) : false
+        next if is_default
+
+        # Determine user properties to set and unset.
+        set_props = {}
+        unset_props = {}
+        flag_type = variant.metadata['flagType'] if variant.metadata
+        if flag_type != 'mutual-exclusion-group'
+          if variant.key
+            set_props["[Experiment] #{flag_key}"] = variant.key
+          elsif variant.value
+            set_props["[Experiment] #{flag_key}"] = variant.value
+          end
+        end
+
+        # Build event properties.
+        event_properties = {}
+        event_properties['[Experiment] Flag Key'] = flag_key
+        if variant.key
+          event_properties['[Experiment] Variant'] = variant.key
+        elsif variant.value
+          event_properties['[Experiment] Variant'] = variant.value
+        end
+        event_properties['metadata'] = variant.metadata if variant.metadata
+
+        # Build event.
+        event = AmplitudeAnalytics::BaseEvent.new(
+          '[Experiment] Exposure',
+          user_id: exposure.user.user_id,
+          device_id: exposure.user.device_id,
+          event_properties: event_properties,
+          user_properties: {
+            '$set' => set_props,
+            '$unset' => unset_props
+          },
+          insert_id: "#{exposure.user.user_id} #{exposure.user.device_id} #{AmplitudeExperiment.hash_code("#{flag_key} #{canonicalized}")} #{exposure.timestamp / ttl_millis}"
+        )
+        event.groups = exposure.user.groups if exposure.user.groups
+
+        events << event
+      end
+      events
+    end
+  end
+end

data/lib/experiment/version.rb

@@ -1,3 +1,3 @@
 module AmplitudeExperiment
-  VERSION = '1.8.0'.freeze
+  VERSION = '1.9.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amplitude-experiment
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Amplitude
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-15 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -213,6 +213,11 @@ files:
 - lib/experiment/local/assignment/assignment_service.rb
 - lib/experiment/local/client.rb
 - lib/experiment/local/config.rb
+- lib/experiment/local/evaluate_options.rb
+- lib/experiment/local/exposure/exposure.rb
+- lib/experiment/local/exposure/exposure_config.rb
+- lib/experiment/local/exposure/exposure_filter.rb
+- lib/experiment/local/exposure/exposure_service.rb
 - lib/experiment/persistent_http_client.rb
 - lib/experiment/remote/client.rb
 - lib/experiment/remote/config.rb