amplitude-experiment 1.0.0.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f67be77264977612b2728ee49db7923a26414cdeefc71d15059cbcd6564031ac
+  data.tar.gz: d59583f45788bea92e6c5855b0cb2f754a87a2b022784f6a3e89eca239173819
+SHA512:
+  metadata.gz: fd383c6a79f4164fbc3897d12256da8c19b5824be542faa23b43384ad32aa781c6cfee5b4101d015cd6fbef5994818ddc8ddd77addd83f8522c9716063f1dd45
+  data.tar.gz: b0d7f6429e872a86027cd0f34b2e796b04be39cc672616e5e99e543b32635dbe8226c06356f941fcfd7e118d608a4d151ce80fa6b6be10cfa5e41ae08e656138

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,61 @@
+<p align="center">
+  <a href="https://amplitude.com" target="_blank" align="center">
+    <img src="https://static.amplitude.com/lightning/46c85bfd91905de8047f1ee65c7c93d6fa9ee6ea/static/media/amplitude-logo-with-text.4fb9e463.svg" width="280">
+  </a>
+  <br />
+</p>
+
+# experiment-ruby-server
+Ruby Server SDK for Experiment
+
+## Installation
+Into Gemfile from rubygems.org:
+```ruby
+gem 'amplitude-experiment'
+```
+Into environment gems from rubygems.org:
+```ruby
+gem install 'amplitude-experiment'
+```
+
+## Quick Start
+```ruby
+require 'amplitude-experiment'
+
+# (1) Get your deployment's API key
+apiKey = 'YOUR-API-KEY'
+
+# (2) Initialize the experiment client
+experiment = Experiment.init(api_key)
+
+# (3) Fetch variants for a user
+user = Experiment::User.new(user_id: 'user@company.com', device_id: 'abcezas123', user_properties: {'premium' => true})
+
+# (4) Lookup a flag's variant
+# 
+# To fetch asynchronous
+experiment.fetch_async(user) do |_, variants|
+  variant = variants['YOUR-FLAG-KEY']
+  unless variant.nil?
+    if variant.value == 'on'
+      # Flag is on
+    else
+      # Flag is off
+    end
+  end
+end
+
+# To fetch synchronous
+variants = experiment.fetch(user)
+variant = variants['YOUR-FLAG-KEY']
+unless variant.nil?
+  if variant.value == 'on'
+    # Flag is on
+  else
+    # Flag is off
+  end
+end
+```
+
+## Need Help?
+If you have any problems or issues over our SDK, feel free to [create a github issue](https://github.com/amplitude/experiments-ruby-server/issues/new) or submit a request on [Amplitude Help](https://help.amplitude.com/hc/en-us/requests/new).

data/lib/amplitude-experiment.rb

@@ -0,0 +1 @@
+require 'experiment'

data/lib/experiment/client.rb

@@ -0,0 +1,146 @@
+require 'net/http'
+require 'json'
+require 'uri'
+require 'logger'
+
+module Experiment
+  # Main client for fetching variant data.
+  class Client
+    # Creates a new Experiment Client instance.
+    #
+    # @param [String] api_key The environment API Key
+    # @param [Config] config
+    def initialize(api_key, config = nil)
+      @api_key = api_key
+      @config = config || Config.new
+      @logger = Logger.new($stdout)
+      @logger.level = if @config.debug
+                        Logger::DEBUG
+                      else
+                        Logger::INFO
+                      end
+      raise ArgumentError, 'Experiment API key is empty' if @api_key.nil? || @api_key.empty?
+    end
+
+    # Fetch all variants for a user synchronous.
+    #
+    # This method will automatically retry if configured (default).
+    # @param [User] user
+    # @return [Hash] Variants Hash
+    def fetch(user)
+      fetch_internal(user)
+    rescue StandardError => e
+      @logger.error("[Experiment] Failed to fetch variants: #{e.message}")
+      {}
+    end
+
+    # Fetch all variants for a user asynchronous.
+    #
+    # This method will automatically retry if configured (default).
+    # @param [User] user
+    def fetch_async(user, &callback)
+      Thread.new do
+        variants = fetch_internal(user)
+        yield(user, variants) unless callback.nil?
+        variants
+      rescue StandardError => e
+        @logger.error("[Experiment] Failed to fetch variants: #{e.message}")
+        yield(user, {}) unless callback.nil?
+        {}
+      end
+    end
+
+    private
+
+    # @param [User] user
+    def fetch_internal(user)
+      @logger.debug("[Experiment] Fetching variants for user: #{user.as_json}")
+      do_fetch(user, @config.fetch_timeout_millis)
+    rescue StandardError => e
+      @logger.error("[Experiment] Fetch failed: #{e.message}")
+      begin
+        return retry_fetch(user)
+      rescue StandardError => err
+        @logger.error("[Experiment] Retry Fetch failed: #{err.message}")
+      end
+      throw e
+    end
+
+    # @param [User] user
+    def retry_fetch(user)
+      return {} if @config.fetch_retries.zero?
+
+      @logger.debug('[Experiment] Retrying fetch')
+      delay_millis = @config.fetch_retry_backoff_min_millis
+      err = nil
+      @config.fetch_retries.times do
+        sleep(delay_millis / 1000.0)
+        begin
+          return do_fetch(user, @config.fetch_retry_timeout_millis)
+        rescue StandardError => e
+          @logger.error("[Experiment] Retry failed: #{e.message}")
+          err = e
+        end
+        delay_millis = [delay_millis * @config.fetch_retry_backoff_scalar, @config.fetch_retry_backoff_max_millis].min
+      end
+      throw err unless err.nil?
+    end
+
+    # @param [User] user
+    # @param [Integer] timeout_millis
+    def do_fetch(user, timeout_millis)
+      start_time = Time.now
+      user_context = add_context(user)
+      endpoint = "#{@config.server_url}/sdk/vardata"
+      headers = {
+        'Authorization' => "Api-Key #{@api_key}",
+        'Content-Type' => 'application/json;charset=utf-8'
+      }
+      uri = URI(endpoint)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = timeout_millis / 1000 if (timeout_millis / 1000) > 0
+      request = Net::HTTP::Post.new(uri, headers)
+      request.body = user_context.to_json
+      if request.body.length > 8000
+        @logger.warn("[Experiment] encoded user object length #{request.body.length} cannot be cached by CDN; must be < 8KB")
+      end
+      @logger.debug("[Experiment] Fetch variants for user: #{request.body}")
+      response = http.request(request)
+      end_time = Time.now
+      elapsed = (end_time - start_time) * 1000.0
+      @logger.debug("[Experiment] Fetch complete in #{elapsed.round(3)} ms")
+      json = JSON.parse(response.body)
+      variants = parse_json_variants(json)
+      @logger.debug("[Experiment] Fetched variants: #{variants}")
+      variants
+    end
+
+    # Parse JSON response hash
+    #
+    # @param [Hash] json
+    # @return [Hash] Hash with String => Variant
+    def parse_json_variants(json)
+      variants = {}
+      json.each do |key, value|
+        variant_value = ''
+        if value.key?('value')
+          variant_value = value.fetch('value')
+        elsif value.key?('key')
+          # value was previously under the "key" field
+          variant_value = value.fetch('key')
+        end
+        variants.store(key, Variant.new(variant_value, value.fetch('payload')))
+      end
+      variants
+    end
+
+    # @param [User] user
+    # @return [User, Hash] user with library context
+    def add_context(user)
+      user = {} if user.nil?
+      user.library = "experiment-ruby-server/#{VERSION}" if user.library.nil?
+      user
+    end
+  end
+end

data/lib/experiment/config.rb

@@ -0,0 +1,65 @@
+module Experiment
+  # Configuration
+  class Config
+    # Default server url
+    DEFAULT_SERVER_URL = 'https://api.lab.amplitude.com'.freeze
+
+    # Set to true to log some extra information to the console.
+    # @return [Boolean] the value of debug
+    attr_accessor :debug
+
+    # The server endpoint from which to request variants.
+    # @return [Boolean] the value of server url
+    attr_accessor :server_url
+
+    # The request timeout, in milliseconds, used when fetching variants triggered by calling start() or setUser().
+    # @return [Integer] the value of fetch_timeout_millis
+    attr_accessor :fetch_timeout_millis
+
+    # The number of retries to attempt before failing.
+    # @return [Integer] the value of fetch_retries
+    attr_accessor :fetch_retries
+
+    # Retry backoff minimum (starting backoff delay) in milliseconds. The minimum backoff is scaled
+    #  by `fetch_retry_backoff_scalar` after each retry failure.
+    # @return [Integer] the value of fetch_retry_backoff_min_millis
+    attr_accessor :fetch_retry_backoff_min_millis
+
+    # Retry backoff maximum in milliseconds. If the scaled backoff is greater than the max,
+    #   the max is used for all subsequent retries.
+    # @return [Integer] the value of fetch_retry_backoff_max_millis
+    attr_accessor :fetch_retry_backoff_max_millis
+
+    # Scales the minimum backoff exponentially.
+    # @return [Float] the value of fetch_retry_backoff_scalar
+    attr_accessor :fetch_retry_backoff_scalar
+
+    # The request timeout for retrying fetch requests.
+    # @return [Integer] the value of fetch_retry_timeout_millis
+    attr_accessor :fetch_retry_timeout_millis
+
+    # @param [Boolean] debug Set to true to log some extra information to the console.
+    # @param [String] server_url The server endpoint from which to request variants.
+    # @param [Integer] fetch_timeout_millis The request timeout, in milliseconds, used when fetching variants
+    #  triggered by calling start() or setUser().
+    # @param [Integer] fetch_retries The number of retries to attempt before failing.
+    # @param [Integer] fetch_retry_backoff_min_millis Retry backoff minimum (starting backoff delay) in milliseconds.
+    #  The minimum backoff is scaled by `fetch_retry_backoff_scalar` after each retry failure.
+    # @param [Integer] fetch_retry_backoff_max_millis Retry backoff maximum in milliseconds. If the scaled backoff is
+    #  greater than the max, the max is used for all subsequent retries.
+    # @param [Float] fetch_retry_backoff_scalar Scales the minimum backoff exponentially.
+    # @param [Integer] fetch_retry_timeout_millis The request timeout for retrying fetch requests.
+    def initialize(debug: false, server_url: DEFAULT_SERVER_URL, fetch_timeout_millis: 10_000, fetch_retries: 0,
+                   fetch_retry_backoff_min_millis: 500, fetch_retry_backoff_max_millis: 10_000,
+                   fetch_retry_backoff_scalar: 1.5, fetch_retry_timeout_millis: 10_000)
+      @debug = debug
+      @server_url = server_url
+      @fetch_timeout_millis = fetch_timeout_millis
+      @fetch_retries = fetch_retries
+      @fetch_retry_backoff_min_millis = fetch_retry_backoff_min_millis
+      @fetch_retry_backoff_max_millis = fetch_retry_backoff_max_millis
+      @fetch_retry_backoff_scalar = fetch_retry_backoff_scalar
+      @fetch_retry_timeout_millis = fetch_retry_timeout_millis
+    end
+  end
+end

data/lib/experiment/cookie.rb

@@ -0,0 +1,41 @@
+require 'base64'
+
+module Experiment
+  # This class provides utility functions for parsing and handling identity from Amplitude cookies.
+  class AmplitudeCookie
+    # Get the cookie name that Amplitude sets for the provided
+    #
+    # @param [String] api_key The Amplitude API Key
+    # @return [String] The cookie name that Amplitude sets for the provided
+    def self.cookie_name(api_key)
+      raise ArgumentError, 'Invalid Amplitude API Key' if api_key.nil? || api_key.length < 6
+
+      "amp_#{api_key[0..5]}"
+    end
+
+    # Parse a cookie string and returns user
+    #
+    # @param [String] amplitude_cookie A string from the amplitude cookie
+    # @return [User] a Experiment User context containing a device_id and user_id
+    def self.parse(amplitude_cookie)
+      values = amplitude_cookie.split('.', -1)
+      user_id = nil
+      unless values[1].nil? || values[1].empty?
+        begin
+          user_id = Base64.decode64(values[1]).force_encoding('UTF-8')
+        rescue StandardError
+          user_id = nil
+        end
+      end
+      User.new(user_id: user_id, device_id: values[0])
+    end
+
+    # Generates a cookie string to set for the Amplitude Javascript SDK
+    #
+    # @param [String] device_id A device id to set
+    # @return [String] A cookie string to set for the Amplitude Javascript SDK to read
+    def self.generate(device_id)
+      "#{device_id}.........."
+    end
+  end
+end

data/lib/experiment/factory.rb

@@ -0,0 +1,15 @@
+# Provides factory methods for storing singleton instance of Client
+module Experiment
+  @instances = {}
+  @default_instance = '$default_instance'
+
+  # Initializes a singleton Client. This method returns a default singleton instance, subsequent calls to
+  #  init will return the initial instance regardless of input.
+  #
+  # @param [String] api_key The environment API Key
+  # @param [Config] config Optional Config.
+  def self.init(api_key, config = nil)
+    @instances.store(@default_instance, Client.new(api_key, config)) unless @instances.key?(@default_instance)
+    @instances.fetch(@default_instance)
+  end
+end

data/lib/experiment/user.rb

@@ -0,0 +1,137 @@
+module Experiment
+  # Defines a user context for evaluation.
+  # `device_id` and `user_id` are used for identity resolution.
+  # All other predefined fields and user properties are used for
+  # rule based user targeting.
+  class User
+    # Device ID for associating with an identity in Amplitude
+    # @return [String, nil] the value of device id
+    attr_accessor :device_id
+
+    # User ID for associating with an identity in Amplitude
+    # @return [String, nil] the value of user id
+    attr_accessor :user_id
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of country
+    attr_accessor :country
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of city
+    attr_accessor :city
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of region
+    attr_accessor :region
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of dma
+    attr_accessor :dma
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of language
+    attr_accessor :language
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of platform
+    attr_accessor :platform
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of version
+    attr_accessor :version
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of os
+    attr_accessor :os
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of device manufacturer
+    attr_accessor :device_manufacturer
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of device brand
+    attr_accessor :device_brand
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of device model
+    attr_accessor :device_model
+
+    # Predefined field, must be manually provided
+    # @return [String, nil] the value of carrier
+    attr_accessor :carrier
+
+    # Predefined field, auto populated, can be manually overridden
+    # @return [String, nil] the value of library
+    attr_accessor :library
+
+    # Custom user properties
+    # @return [Hash, nil] the value of user properties
+    attr_accessor :user_properties
+
+    # @param [String, nil] device_id Device ID for associating with an identity in Amplitude
+    # @param [String, nil] user_id User ID for associating with an identity in Amplitude
+    # @param [String, nil] country Predefined field, must be manually provided
+    # @param [String, nil] city Predefined field, must be manually provided
+    # @param [String, nil] region Predefined field, must be manually provided
+    # @param [String, nil] dma Predefined field, must be manually provided
+    # @param [String, nil] language Predefined field, must be manually provided
+    # @param [String, nil] platform Predefined field, must be manually provided
+    # @param [String, nil] version Predefined field, must be manually provided
+    # @param [String, nil] os Predefined field, must be manually provided
+    # @param [String, nil] device_manufacturer Predefined field, must be manually provided
+    # @param [String, nil] device_brand Predefined field, must be manually provided
+    # @param [String, nil] device_model Predefined field, must be manually provided
+    # @param [String, nil] carrier Predefined field, must be manually provided
+    # @param [String, nil] library Predefined field, auto populated, can be manually overridden
+    # @param [Hash, nil] user_properties Custom user properties
+    def initialize(device_id: nil, user_id: nil, country: nil, city: nil, region: nil, dma: nil, language: nil,
+                   platform: nil, version: nil, os: nil, device_manufacturer: nil, device_brand: nil,
+                   device_model: nil, carrier: nil, library: nil, user_properties: nil)
+      @device_id = device_id
+      @user_id = user_id
+      @country = country
+      @city = city
+      @region = region
+      @dma = dma
+      @language = language
+      @platform = platform
+      @version = version
+      @os = os
+      @device_manufacturer = device_manufacturer
+      @device_brand = device_brand
+      @device_model = device_model
+      @carrier = carrier
+      @library = library
+      @user_properties = user_properties
+    end
+
+    # Return User as Hash.
+    # @return [Hash] Hash object with user values
+    def as_json(_options = {})
+      {
+        device_id: @device_id,
+        user_id: @user_id,
+        country: @country,
+        city: @city,
+        region: @region,
+        dma: @dma,
+        language: @language,
+        platform: @platform,
+        version: @version,
+        os: @os,
+        device_manufacturer: @device_manufacturer,
+        device_brand: @device_brand,
+        device_model: @device_model,
+        carrier: @carrier,
+        library: @library,
+        user_properties: @user_properties
+      }
+    end
+
+    # Return user information as JSON string.
+    # @return [String] details about user as json string
+    def to_json(*options)
+      as_json(*options).to_json(*options)
+    end
+  end
+end

data/lib/experiment/variant.rb

@@ -0,0 +1,26 @@
+module Experiment
+  # Variant
+  class Variant
+    # The value of the variant determined by the flag configuration.
+    # @return [String] the value of variant value
+    attr_accessor :value
+
+    # The attached payload, if any.
+    # @return [Object, nil] the value of variant payload
+    attr_accessor :payload
+
+    # @param [String] value The value of the variant determined by the flag configuration.
+    # @param [Object, nil] payload The attached payload, if any.
+    def initialize(value, payload = nil)
+      @value = value
+      @payload = payload
+    end
+
+    # Determine if current variant equal other variant
+    # @param [Variant] other
+    def ==(other)
+      value == other.value &&
+        payload == other.payload
+    end
+  end
+end

data/lib/experiment/version.rb

@@ -0,0 +1,3 @@
+module Experiment
+  VERSION = '1.0.0.beta.1'.freeze
+end

data/lib/experiment.rb

@@ -0,0 +1,10 @@
+require 'experiment/config'
+require 'experiment/cookie'
+require 'experiment/user'
+require 'experiment/variant'
+require 'experiment/factory'
+require 'experiment/client'
+
+# Amplitude Experiment Module
+module Experiment
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: amplitude-experiment
+version: !ruby/object:Gem::Version
+  version: 1.0.0.beta.1
+platform: ruby
+authors:
+- Amplitude
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-04-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Amplitude Experiment Ruby Server SDK
+email:
+- sdk@amplitude.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- Gemfile
+- README.md
+- lib/amplitude-experiment.rb
+- lib/experiment.rb
+- lib/experiment/client.rb
+- lib/experiment/config.rb
+- lib/experiment/cookie.rb
+- lib/experiment/factory.rb
+- lib/experiment/user.rb
+- lib/experiment/variant.rb
+- lib/experiment/version.rb
+homepage: https://github.com/amplitude/experiment-ruby-server
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'false'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Amplitude Experiment Ruby Server SDK
+test_files: []