vwo-sdk 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2555f32eb2068e63dea737bdf3937708a5ef3e1e
+  data.tar.gz: dd662a2ac80ba5dc6892375c15b3d13e2e0ed3a4
+SHA512:
+  metadata.gz: 2dae59f19f9342856a343e5be3359b487069db19f4503398b577eed09c9e1e6ff98c37923c53b1fca91b5da5d66ad2d7a2414c582e0b02b3cb78f529a80a1568
+  data.tar.gz: 1d1778ccde23e98efed73462dca543c84c12ccb2a7cf4cb18e129f63514268742afc4a0d7a394b16476dadef08eb2d0bbd47b312a13afce23f1c66c23f5a3a99

data/lib/vwo.rb

@@ -0,0 +1,348 @@
+# Copyright 2019 Wingify Software Pvt. Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+require_relative 'vwo/services/settings_file_manager'
+require_relative 'vwo/services/event_dispatcher'
+require_relative 'vwo/services/settings_file_processor'
+require_relative 'vwo/logger'
+require_relative 'vwo/enums'
+require_relative 'vwo/utils/campaign'
+require_relative 'vwo/utils/impression'
+require_relative 'vwo/constants'
+require_relative 'vwo/core/variation_decider'
+
+
+# VWO main file
+class VWO
+  attr_accessor :is_instance_valid
+
+  include Enums
+  include Utils::Validations
+  include Utils::Campaign
+  include Utils::Impression
+  include CONSTANTS
+
+  FILE = FileNameEnum::VWO
+
+  # Initializes and expose APIs
+  #
+  # @param[Numeric|String]  :account_id             Account Id in VWO
+  # @param[String]          :sdk_key                Unique sdk key for user
+  # @param[Object]          :logger                 Optional - should have log method defined
+  # @param[Object]          :user_storage           Optional - to store and manage user data mapping
+  # @param[Boolean]         :is_development_mode    To specify whether the request
+  #                                                 to our server should be sent or not.
+  # @param[String]          :settings_file           Settings-file data
+
+  def initialize(
+    account_id,
+    sdk_key,
+    logger = nil,
+    user_storage = nil,
+    is_development_mode = false,
+    settings_file = nil
+  )
+    @account_id = account_id
+    @sdk_key = sdk_key
+    @user_storage = user_storage
+    @is_development_mode = is_development_mode
+    @logger = VWO::Logger.get_instance(logger)
+
+    unless valid_settings_file?(get_settings(settings_file))
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::SETTINGS_FILE_CORRUPTED, file: FILE)
+      )
+      @is_instance_valid = false
+      return
+    end
+    @is_instance_valid = true
+    @config = VWO::Services::SettingsFileProcessor.new(get_settings)
+
+    @logger.log(
+      LogLevelEnum::DEBUG,
+      format(LogMessageEnum::DebugMessages::VALID_CONFIGURATION, file: FILE)
+    )
+
+    # Process the settings file
+    @config.process_settings_file
+    @settings_file = @config.get_settings_file
+
+    # Assign VariationDecider to VWO
+    @variation_decider = VWO::Core::VariationDecider.new(@settings_file, user_storage)
+
+    if is_development_mode
+      @logger.log(
+        LogLevelEnum::DEBUG,
+        format(LogMessageEnum::DebugMessages::SET_DEVELOPMENT_MODE, file: FILE)
+      )
+    end
+    # Assign event dispatcher
+    @event_dispatcher = VWO::Services::EventDispatcher.new(is_development_mode)
+
+    # Successfully initialized VWO SDK
+    @logger.log(
+      LogLevelEnum::DEBUG,
+      format(LogMessageEnum::DebugMessages::SDK_INITIALIZED, file: FILE)
+    )
+  end
+
+  # Public Methods
+
+  # VWO get_settings method to get settings for a particular account_id
+  def get_settings(settings_file = nil)
+    @settings ||=
+      settings_file || VWO::Services::SettingsFileManager.new(@account_id, @sdk_key).get_settings_file
+    @settings
+  end
+
+  # This API method: Gets the variation assigned for the user
+  # For the campaign and send the metrics to VWO server
+  #
+  # 1. Validates the arguments being passed
+  # 2. Checks if user is eligible to get bucketed into the campaign,
+  # 3. Assigns the deterministic variation to the user(based on userId),
+  #    If user becomes part of campaign
+  #    If UserStorage is used, it will look into it for the
+  #    Variation and if found, no further processing is done
+  # 4. Sends an impression call to VWO server to track user
+  #
+  # @param[String]            :campaign_key  Unique campaign key
+  # @param[String]            :user_id            ID assigned to a user
+  # @return[String|None]                          If variation is assigned then variation-name
+  #                                               otherwise null in case of user not becoming part
+
+  def activate(campaign_key, user_id)
+    # Validate input parameters
+    unless valid_string?(campaign_key) && valid_string?(user_id)
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::ACTIVATE_API_MISSING_PARAMS, file: FILE)
+      )
+      return
+    end
+
+    unless @is_instance_valid
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::ACTIVATE_API_CONFIG_CORRUPTED, file: FILE)
+      )
+      return
+    end
+
+    # Get the campaign settings
+    campaign = get_campaign(@settings_file, campaign_key)
+
+    # Validate campaign
+    unless campaign && campaign['status'] == STATUS_RUNNING
+      # Log Campaign as invalid
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::CAMPAIGN_NOT_RUNNING, file: FILE, campaign_key: campaign_key, api: 'activate')
+      )
+      return
+    end
+
+    # Once the matching RUNNING campaign is found, assign the
+    # deterministic variation to the user_id provided
+    variation_id, variation_name = @variation_decider.get_variation(
+      user_id,
+      campaign
+    )
+
+    # Check if variation_name has been assigned
+    unless valid_value?(variation_name)
+      @logger.log(
+        LogLevelEnum::INFO,
+        format(LogMessageEnum::InfoMessages::INVALID_VARIATION_KEY, file: FILE, user_id: user_id, campaign_key: campaign_key)
+      )
+      return
+    end
+
+    # Variation found, dispatch it to server
+    impression = create_impression(
+      @settings_file,
+      campaign['id'],
+      variation_id,
+      user_id
+    )
+    @event_dispatcher.dispatch(impression)
+    variation_name
+  end
+
+  # This API method: Gets the variation name assigned for the
+  # user for the campaign
+  #
+  # 1. Validates the arguments being passed
+  # 2. Checks if user is eligible to get bucketed into the campaign,
+  # 3. Assigns the deterministic variation to the user(based on user_id),
+  #    If user becomes part of campaign
+  #    If UserStorage is used, it will look into it for the
+  #    variation and if found, no further processing is done
+  #
+  # @param[String]              :campaign_key             Unique campaign key
+  # @param[String]              :user_id                  ID assigned to a user
+  #
+  # @@return[String|Nil]                                  If variation is assigned then variation-name
+  #                                                       Otherwise null in case of user not becoming part
+  #
+  def get_variation_name(campaign_key, user_id)
+    # Check for valid arguments
+    unless valid_string?(campaign_key) && valid_string?(user_id)
+      # log invalid params
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::GET_VARIATION_NAME_API_MISSING_PARAMS, file: FILE)
+      )
+      return
+    end
+
+    unless @is_instance_valid
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::ACTIVATE_API_CONFIG_CORRUPTED, file: FILE)
+      )
+      return
+    end
+
+    # Get the campaign settings
+    campaign = get_campaign(@settings_file, campaign_key)
+
+    # Validate campaign
+    if campaign.nil? || campaign['status'] != STATUS_RUNNING
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::CAMPAIGN_NOT_RUNNING, file: FILE, campaign_key: campaign_key, api: 'get_variation')
+      )
+      return
+    end
+
+    _variation_id, variation_name = @variation_decider.get_variation(
+      user_id,
+      campaign
+    )
+
+    # Check if variation_name has been assigned
+    unless valid_value?(variation_name)
+      # log invalid variation key
+      @logger.log(
+        LogLevelEnum::INFO,
+        format(LogMessageEnum::InfoMessages::INVALID_VARIATION_KEY, file: FILE, user_id: user_id, campaign_key: campaign_key)
+      )
+      return
+    end
+
+    variation_name
+  end
+
+  # This API method: Marks the conversion of the campaign
+  # for a particular goal
+  # 1. validates the arguments being passed
+  # 2. Checks if user is eligible to get bucketed into the campaign,
+  # 3. Gets the assigned deterministic variation to the
+  #     user(based on user_d), if user becomes part of campaign
+  # 4. Sends an impression call to VWO server to track goal data
+  #
+  # @param[String]                      :campaign_key     Unique campaign key
+  # @param[String]                      :user_id          ID assigned to a user
+  # @param[String]                      :goal_identifier   Unique campaign's goal identifier
+  # @param[Numeric|String]              :revenue_value    Revenue value for revenue-type goal
+  #
+  def track(campaign_key, user_id, goal_identifier, *args)
+    if args[0].is_a?(Hash)
+      revenue_value = args[0]['revenue_value']
+    elsif args.is_a?(Array)
+      revenue_value = args[0]
+    end
+
+    # Check for valid args
+    unless valid_string?(campaign_key) && valid_string?(user_id) && valid_string?(goal_identifier)
+      # log invalid params
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::TRACK_API_MISSING_PARAMS, file: FILE)
+      )
+      return false
+    end
+
+    unless @is_instance_valid
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::ACTIVATE_API_CONFIG_CORRUPTED, file: FILE)
+      )
+      return false
+    end
+
+    # Get the campaign settings
+    campaign = get_campaign(@settings_file, campaign_key)
+
+    # Validate campaign
+    if campaign.nil? || campaign['status'] != STATUS_RUNNING
+      # log error
+      @logger.log(
+        LogLevelEnum::ERROR,
+        format(LogMessageEnum::ErrorMessages::CAMPAIGN_NOT_RUNNING, file: FILE, campaign_key: campaign_key, api: 'track')
+      )
+      return false
+    end
+
+    campaign_id = campaign['id']
+    variation_id, variation_name = @variation_decider.get_variation_allotted(user_id, campaign)
+
+    if variation_name
+      goal = get_campaign_goal(@settings_file, campaign['key'], goal_identifier)
+
+      if goal.nil?
+        @logger.log(
+          LogLevelEnum::ERROR,
+          format(
+            LogMessageEnum::ErrorMessages::TRACK_API_GOAL_NOT_FOUND,
+            file: FILE, goal_identifier: goal_identifier,
+            user_id: user_id,
+            campaign_key: campaign_key
+          )
+        )
+        return false
+      elsif goal['type'] == GOALTYPES::REVENUE && !valid_value?(revenue_value)
+        @logger.log(
+          LogLevelEnum::ERROR,
+          format(
+            LogMessageEnum::ErrorMessages::TRACK_API_REVENUE_NOT_PASSED_FOR_REVENUE_GOAL,
+            file: FILE,
+            user_id: user_id,
+            goal_identifier: goal_identifier,
+            campaign_key: campaign_key
+          )
+        )
+        return false
+      end
+
+      revenue_value = nil if goal['type'] == GOALTYPES::CUSTOM
+
+      impression = create_impression(
+        @settings_file,
+        campaign_id,
+        variation_id,
+        user_id,
+        goal['id'],
+        revenue_value
+      )
+      @event_dispatcher.dispatch(impression)
+      return true
+    end
+    false
+  end
+end

data/lib/vwo/constants.rb

@@ -0,0 +1,63 @@
+# Copyright 2019 Wingify Software Pvt. Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+class VWO
+  module CONSTANTS
+    API_VERSION = 1
+    PLATFORM = 'server'
+    SEED_VALUE = 1
+    MAX_TRAFFIC_PERCENT = 100
+    MAX_TRAFFIC_VALUE = 10_000
+    STATUS_RUNNING = 'RUNNING'
+    LIBRARY_PATH =  File.expand_path('../..', __FILE__)
+    HTTP_PROTOCOL = 'http://'
+    HTTPS_PROTOCOL = 'https://'
+    URL_NAMESPACE = '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
+    SDK_VERSION = '1.3.0'
+    SDK_NAME = 'ruby'
+
+    module ENDPOINTS
+      BASE_URL = 'dev.visualwebsiteoptimizer.com'
+      ACCOUNT_SETTINGS = '/server-side/settings'
+      TRACK_USER = '/server-side/track-user'
+      TRACK_GOAL = '/server-side/track-goal'
+    end
+
+    module EVENTS
+      TRACK_USER = 'track-user'
+      TRACK_GOAL = 'track-goal'
+    end
+
+    module DATATYPE
+      NUMBER = 'number'
+      STRING = 'string'
+      FUNCTION = 'function'
+      BOOLEAN = 'boolean'
+    end
+
+    module APIMETHODS
+      CREATE_INSTANCE = 'CREATE_INSTANCE'
+      ACTIVATE = 'ACTIVATE'
+      GET_VARIATION = 'GET_VARIATION'
+      TRACK = 'TRACK'
+    end
+
+    module GOALTYPES
+      REVENUE = 'REVENUE_TRACKING'
+      CUSTOM = 'CUSTOM_GOAL'
+    end
+  end
+end

data/lib/vwo/core/bucketer.rb

@@ -0,0 +1,177 @@
+# Copyright 2019 Wingify Software Pvt. Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+require 'murmurhash3'
+require_relative '../logger'
+require_relative '../enums'
+require_relative '../utils/validations'
+require_relative '../constants'
+
+class VWO
+  module Core
+    class Bucketer
+      include VWO::Enums
+      include VWO::CONSTANTS
+      include VWO::Utils::Validations
+
+      # Took reference from StackOverflow(https://stackoverflow.com/) to:
+      # convert signed to unsigned integer in python from StackOverflow
+      # Author - Duncan (https://stackoverflow.com/users/107660/duncan)
+      # Source - https://stackoverflow.com/a/20766900/2494535
+      U_MAX_32_BIT = 0xFFFFFFFF
+      MAX_HASH_VALUE = 2**32
+      FILE = FileNameEnum::Bucketer
+
+      def initialize
+        @logger = VWO::Logger.get_instance
+      end
+
+      # Calculate if this user should become part of the campaign or not
+      # @param[String]         :user_id     The unique ID assigned to a user
+      # @param[Dict]           :campaign    For getting traffic allotted to the campaign
+      # @return[Boolean]                    If User is a part of Campaign or not
+      #
+      def user_part_of_campaign?(user_id, campaign)
+        unless valid_value?(user_id)
+          @logger.log(
+            LogLevelEnum::ERROR,
+            format(LogMessageEnum::ErrorMessages::INVALID_USER_ID, file: FILE, user_id: user_id, method: 'is_user_part_of_campaign')
+          )
+          return false
+        end
+
+        if campaign.nil?
+          @logger.log(
+            LogLevelEnum::ERROR,
+            format(LogMessageEnum::ErrorMessages::INVALID_CAMPAIGN, file: FILE, method: 'is_user_part_of_campaign')
+          )
+          return false
+        end
+
+        traffic_allocation = campaign['percentTraffic']
+
+        value_assigned_to_user = get_bucket_value_for_user(user_id)
+        is_user_part = (value_assigned_to_user != 0) && value_assigned_to_user <= traffic_allocation
+        @logger.log(
+          LogLevelEnum::INFO,
+          format(LogMessageEnum::InfoMessages::USER_ELIGIBILITY_FOR_CAMPAIGN, file: FILE, user_id: user_id, is_user_part: is_user_part)
+        )
+        is_user_part
+      end
+
+      # Validates the User ID and
+      # Generates Variation into which the User is bucketed to
+      #
+      # @param[String]            :user_id          The unique ID assigned to User
+      # @param[Hash]              :campaign         The Campaign of which User is a part of
+      #
+      # @return[Hash|nil}                           Variation data into which user is bucketed to
+      #                                             or nil if not
+      def bucket_user_to_variation(user_id, campaign)
+        unless valid_value?(user_id)
+          @logger.log(
+            LogLevelEnum::ERROR,
+            format(LogMessageEnum::ErrorMessages::INVALID_USER_ID, file: FILE, user_id: user_id, method: 'bucket_user_to_variation')
+          )
+          return
+        end
+
+        unless campaign
+          @logger.log(
+            LogLevelEnum::ERROR,
+            format(LogMessageEnum::ErrorMessages::INVALID_CAMPAIGN, file: FILE, method: 'is_user_part_of_campaign')
+          )
+          return
+        end
+
+        hash_value = MurmurHash3::V32.str_hash(user_id, SEED_VALUE) & U_MAX_32_BIT
+        normalize = MAX_TRAFFIC_VALUE / campaign['percentTraffic']
+        multiplier = normalize / 100
+        bucket_value = generate_bucket_value(
+          hash_value,
+          MAX_TRAFFIC_VALUE,
+          multiplier
+        )
+
+        @logger.log(
+          LogLevelEnum::DEBUG,
+          format(
+            LogMessageEnum::DebugMessages::VARIATION_HASH_BUCKET_VALUE,
+            file: FILE,
+            user_id: user_id,
+            campaign_key: campaign['key'],
+            percent_traffic: campaign['percentTraffic'],
+            bucket_value: bucket_value,
+            hash_value: hash_value
+          )
+        )
+        get_variation(campaign, bucket_value)
+      end
+
+      private
+
+      # Returns the Variation by checking the Start and End
+      # Bucket Allocations of each Variation
+      #
+      # @param[Hash]        :campaign       Which contains the variations
+      # @param[Integer]     :bucket_value   The bucket Value of the user
+      # @return[Hash|nil]                   Variation data allotted to the user or None if not
+      #
+      def get_variation(campaign, bucket_value)
+        campaign['variations'].find do |variation|
+          (variation['start_variation_allocation']..variation['end_variation_allocation']).cover?(bucket_value)
+        end
+      end
+
+      # Validates the User ID and generates Bucket Value of the
+      # User by hashing the userId by murmurHash and scaling it down.
+      #
+      # @param[String]    :user_id    The unique ID assigned to User
+      # @return[Integer]              The bucket Value allotted to User
+      #                               (between 1 to $this->$MAX_TRAFFIC_PERCENT)
+      def get_bucket_value_for_user(user_id)
+        hash_value = MurmurHash3::V32.str_hash(user_id, SEED_VALUE) & U_MAX_32_BIT
+        bucket_value = generate_bucket_value(hash_value, MAX_TRAFFIC_PERCENT)
+
+        @logger.log(
+          LogLevelEnum::DEBUG,
+          format(
+            LogMessageEnum::DebugMessages::USER_HASH_BUCKET_VALUE,
+            file: FILE,
+            hash_value: hash_value,
+            bucket_value: bucket_value,
+            user_id: user_id
+          )
+        )
+        bucket_value
+      end
+
+      # Generates Bucket Value of the User by hashing the User ID by murmurHash
+      # And scaling it down.
+      #
+      # @param[Integer]             :hash_value   HashValue generated after hashing
+      # @param[Integer]             :max_value    The value up-to which hashValue needs to be scaled
+      # @param[Integer]             :multiplier
+      # @return[Integer]                          Bucket Value of the User
+      #
+      def generate_bucket_value(hash_value, max_value, multiplier = 1)
+        ratio = hash_value.to_f / MAX_HASH_VALUE
+        multiplied_value = (max_value * ratio + 1) * multiplier
+        multiplied_value.to_i
+      end
+    end
+  end
+end