wingify-fme-ruby-sdk 1.60.1 → 1.62.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 689add6103ca863234921afae6aa6da415d466439c2888bf3b9026bc96d56aa7
-  data.tar.gz: b3178336c9f0e9c244507acb083c10f8c3bab352ee3468feefe790242ee01aca
+  metadata.gz: 960bee01b76cc7b563f9066f1b916debff3480d1660892ff2c4efcda8cf1581f
+  data.tar.gz: bca8c1d3fb285a2082526273df933fb717bb23b579f1aed48f526b382be2af19
 SHA512:
-  metadata.gz: 5740126a7a6c8abefc07dc8b3e010f2b7dfc8f17b1e8485538ac820ccdd64b959a229359a320a4e19fe5e0bd4b7831c917985126f7cd551662f23a92183e38c1
-  data.tar.gz: f59985ee2de683173c4728c8af6e43f2fb680a53a4877b10b80ed7d9c376bc90620396eeaa99429d19ac289d43e29db7a0fb6321debb04d3ec26429647601340
+  metadata.gz: 3e1f775e8c6d03f6c251860ba1e4fd4a4e213027440cd37584f5a00d1439682a6d84cc77daddab0efe7bafd909f7c6ca2ded371ed1febed48b8d85f9d6ffc377
+  data.tar.gz: 74e3bf97831c43fe6ecab34989adb413533b5ac4aff4538b8db57d88b74be83c39578d1f1f9162786db463ac388f6a022a0fbcc81c93cbbebf78e56b3ff6fb28

data/lib/wingify/constants/constants.rb

@@ -17,7 +17,7 @@
 # Define the Constants module
 module Constants
   SDK_NAME = 'vwo-fme-ruby-sdk'.freeze
-  SDK_VERSION = '1.60.1'.freeze
+  SDK_VERSION = '1.62.0'.freeze
 
   # --- Brand-specific constants ---
 
@@ -103,4 +103,8 @@ module Constants
   NETWORK_CALL_FAILURE_AFTER_MAX_RETRIES = 'NETWORK_CALL_FAILURE_AFTER_MAX_RETRIES'.freeze
   NETWORK_CALL_SUCCESS_WITH_RETRIES = 'NETWORK_CALL_SUCCESS_WITH_RETRIES'.freeze
   IMPACT_ANALYSIS = 'IMPACT_ANALYSIS'.freeze
+
+  # Internal events sampling defaults (used when settings omit or have invalid values)
+  INTERNAL_EVENTS_DEFAULT_SAMPLING_PERCENT_SERVER = 10.0
+  INTERNAL_EVENTS_DEFAULT_ALWAYS_APPLY_SAMPLING = false
 end

data/lib/wingify/constants/sampled_debug_error_template_keys.rb

@@ -0,0 +1,31 @@
+# Copyright 2024-2026 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.
+
+# Debug error template keys (msg_t) that are subject to sampling.
+# Keys not listed here always send and bypass sampling.
+class SampledDebugErrorTemplateKeys
+  SAMPLED_KEYS = %w[
+    EVENT_NOT_FOUND
+    FEATURE_NOT_FOUND
+    FEATURE_NOT_FOUND_WITH_ID
+  ].freeze
+
+  # Checks whether a debug error template key should be sampled before sending.
+  #
+  # @param message_template_key [String] The msg_t value from the debug event
+  # @return [Boolean] true if the key is in the sampled set; false otherwise
+  def self.contains?(message_template_key)
+    !message_template_key.nil? && SAMPLED_KEYS.include?(message_template_key)
+  end
+end

data/lib/wingify/models/settings/internal_event_sampling_settings_model.rb

@@ -0,0 +1,62 @@
+# Copyright 2024-2026 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.
+
+# Holds the sampling percentage for a specific platform (e.g. server).
+# Maps to the per-platform object inside sampling.usage or sampling.debug.
+class PlatformSamplingRates
+  def initialize(data)
+    data ||= {}
+    @server = data['server']
+  end
+
+  # @return [Numeric, nil] Sampling percentage for the server runtime
+  def get_server
+    @server
+  end
+end
+
+# Groups sampling rates by event category: usage and debug.
+# Maps to the top-level sampling object in the DaCDN settings.
+class EventCategorySamplingRates
+  def initialize(data)
+    data ||= {}
+    # Only build nested models when the category key is present
+    @usage = data['usage'] ? PlatformSamplingRates.new(data['usage']) : nil
+    @debug = data['debug'] ? PlatformSamplingRates.new(data['debug']) : nil
+  end
+
+  # @return [PlatformSamplingRates, nil]
+  def get_usage
+    @usage
+  end
+
+  # @return [PlatformSamplingRates, nil]
+  def get_debug
+    @debug
+  end
+end
+
+# Controls whether sampling is enforced before sending an event.
+# When server is false (the default), usage-stats and sampled debug events bypass sampling and are always sent.
+class AlwaysApplySampling
+  def initialize(data)
+    data ||= {}
+    @server = data['server']
+  end
+
+  # @return [Boolean, nil] Whether sampling must be applied on the server runtime
+  def get_server
+    @server
+  end
+end

data/lib/wingify/models/settings/settings_model.rb

@@ -15,6 +15,7 @@
 require_relative '../campaign/campaign_model'
 require_relative '../campaign/feature_model'
 require_relative '../../constants/constants'
+require_relative 'internal_event_sampling_settings_model'
 
 class SettingsModel
   attr_reader :sdk_key, :account_id, :usage_stats_account_id, :version, :collection_prefix,
@@ -33,6 +34,8 @@ class SettingsModel
     @groups = settings["groups"] || {}
     @is_web_connectivity_enabled = settings.fetch("isWebConnectivityEnabled", true)
     @is_tracking_usage_enabled = settings.fetch("isMAU", false)
+    @always_apply_sampling = settings["alwaysApplySampling"].nil? ? nil : AlwaysApplySampling.new(settings["alwaysApplySampling"] || {})
+    @sampling = settings["sampling"].nil? ? nil : EventCategorySamplingRates.new(settings["sampling"] || {})
 
     process_features(settings)
     process_campaigns(settings)
@@ -103,4 +106,14 @@ class SettingsModel
   def get_is_tracking_usage_enabled
     @is_tracking_usage_enabled
   end
+
+  # @return [AlwaysApplySampling, nil] alwaysApplySampling settings, if present
+  def get_always_apply_sampling
+    @always_apply_sampling
+  end
+
+  # @return [EventCategorySamplingRates, nil] sampling rates by event category, if present
+  def get_sampling
+    @sampling
+  end
 end

data/lib/wingify/services/internal_events_sampling_service.rb

@@ -0,0 +1,54 @@
+# Copyright 2024-2026 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.
+
+require_relative '../utils/internal_events_sampling_util'
+
+# Applies sampling rules for internal SDK events:
+# vwo_sdkUsageStats and sampled vwo_sdkDebug.
+class InternalEventsSamplingService
+  # Creates a sampling service.
+  #
+  # @param random_value_provider [Proc, nil] Optional supplier returning a value in [0, 1)
+  #   for sampling checks; overridable in tests.
+  def initialize(random_value_provider = nil)
+    # Use Kernel#rand by default; inject a custom provider when testing
+    @random_value_provider = random_value_provider || -> { rand }
+  end
+
+  # Determines whether the usage-stats event should be sent.
+  # On server, always sends unless alwaysApplySampling.server is enabled.
+  #
+  # @param settings [SettingsModel, nil] Parsed settings from the server
+  # @return [Boolean] true when the usage-stats event should be sent
+  def should_send_usage_stats_event(settings)
+    # Skip the percent check when alwaysApplySampling.server is off
+    return true unless InternalEventsSamplingUtil.should_apply_sampling(settings)
+
+    usage_stats_sampling_percent = InternalEventsSamplingUtil.get_usage_stats_sampling_percent(settings)
+    InternalEventsSamplingUtil.passes_sampling_percent(usage_stats_sampling_percent, @random_value_provider.call)
+  end
+
+  # Determines whether a sampled debug event should be sent.
+  # Only called for msg_t keys in the sampled set; always-send keys bypass this.
+  #
+  # @param settings [SettingsModel, nil] Parsed settings from the server
+  # @return [Boolean] true when the sampled debug event should be sent
+  def should_send_sampled_debug_event(settings)
+    # Skip the percent check when alwaysApplySampling.server is off
+    return true unless InternalEventsSamplingUtil.should_apply_sampling(settings)
+
+    debug_sampling_percent = InternalEventsSamplingUtil.get_debug_event_sampling_percent(settings)
+    InternalEventsSamplingUtil.passes_sampling_percent(debug_sampling_percent, @random_value_provider.call)
+  end
+end

data/lib/wingify/utils/debugger_service_util.rb

@@ -17,10 +17,29 @@ require_relative '../enums/log_level_enum'
 require_relative '../utils/network_util'
 require_relative '../services/batch_event_queue'
 require_relative '../enums/event_enum'
+require_relative '../utils/internal_events_sampling_util'
+require_relative '../services/internal_events_sampling_service'
 
 class DebuggerServiceUtil
   class << self
     def send_debugger_event(event_props)
+      # Sampled keys: apply sampling only when alwaysApplySampling.server is true; others always send
+      msg_t = event_props[:msg_t] || event_props['msg_t']
+      is_sampled_debug_event = msg_t.is_a?(String) && InternalEventsSamplingUtil.is_sampled_debug_error_template_key(msg_t)
+
+      # Resolve settings from the live SDK instance without a hard require (avoids circular load)
+      settings = nil
+      if defined?(Wingify) && Wingify.respond_to?(:instance)
+        instance = Wingify.instance
+        settings = instance.respond_to?(:settings) ? instance.settings : nil
+      end
+
+      # If msg_t is in the sampled set, drop the event when the sampling check fails
+      if is_sampled_debug_event
+        sampling_service = InternalEventsSamplingService.new
+        return unless sampling_service.should_send_sampled_debug_event(settings)
+      end
+
       # get base properties for the event
       properties = NetworkUtil.get_events_base_properties(EventEnum::DEBUGGER_EVENT)
 

data/lib/wingify/utils/internal_events_sampling_util.rb

@@ -0,0 +1,108 @@
+# Copyright 2024-2026 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.
+
+require_relative '../constants/constants'
+require_relative '../constants/sampled_debug_error_template_keys'
+
+# Helpers for reading and applying internal-events sampling settings.
+class InternalEventsSamplingUtil
+  class << self
+    # Returns the default server sampling percentage when settings omit the value.
+    #
+    # @return [Float] Default sampling percentage (10.0)
+    def get_default_sampling_percent
+      Constants::INTERNAL_EVENTS_DEFAULT_SAMPLING_PERCENT_SERVER
+    end
+
+    # Normalizes a sampling value to a valid percentage in the range [0, 100].
+    # Falls back to the server default when the value is missing or invalid.
+    #
+    # @param sampling_value [Numeric, nil] Raw value from settings
+    # @return [Float] Valid sampling percentage between 0 and 100
+    def normalize_sampling_percent(sampling_value)
+      # Accept only numeric values that fall within 0–100 inclusive
+      if !sampling_value.nil? && sampling_value.is_a?(Numeric) && sampling_value >= 0 && sampling_value <= 100
+        return sampling_value.to_f
+      end
+
+      get_default_sampling_percent
+    end
+
+    # Reads the server sampling percentage from a runtime sampling config object.
+    #
+    # @param runtime_sampling_config [PlatformSamplingRates, nil] Nested config (e.g. sampling.usage)
+    # @return [Float] Sampling percentage for the server runtime
+    def get_runtime_sampling_percent(runtime_sampling_config)
+      return get_default_sampling_percent if runtime_sampling_config.nil?
+
+      normalize_sampling_percent(runtime_sampling_config.get_server)
+    end
+
+    # Reads the usage-stats sampling percentage for the server runtime from settings.
+    #
+    # @param settings [SettingsModel, nil] Parsed settings from the server
+    # @return [Float] Configured usage-stats sampling percentage (0-100)
+    def get_usage_stats_sampling_percent(settings)
+      sampling = settings ? settings.get_sampling : nil
+      usage_sampling = sampling ? sampling.get_usage : nil
+      get_runtime_sampling_percent(usage_sampling)
+    end
+
+    # Reads the debug-event sampling percentage for the server runtime from settings.
+    #
+    # @param settings [SettingsModel, nil] Parsed settings from the server
+    # @return [Float] Configured debug sampling percentage (0-100)
+    def get_debug_event_sampling_percent(settings)
+      sampling = settings ? settings.get_sampling : nil
+      debug_sampling = sampling ? sampling.get_debug : nil
+      get_runtime_sampling_percent(debug_sampling)
+    end
+
+    # Determines whether sampling should be evaluated before send.
+    # Controlled by alwaysApplySampling.server; defaults to false.
+    #
+    # @param settings [SettingsModel, nil] Parsed settings from the server
+    # @return [Boolean] true when a sampling check is required before sending
+    def should_apply_sampling(settings)
+      return Constants::INTERNAL_EVENTS_DEFAULT_ALWAYS_APPLY_SAMPLING if settings.nil?
+
+      always_apply_sampling = settings.get_always_apply_sampling
+      # Missing config or missing server flag → use default (do not sample)
+      if always_apply_sampling.nil? || always_apply_sampling.get_server.nil?
+        return Constants::INTERNAL_EVENTS_DEFAULT_ALWAYS_APPLY_SAMPLING
+      end
+
+      always_apply_sampling.get_server
+    end
+
+    # Evaluates whether an event qualifies under the configured sampling percentage.
+    #
+    # @param sampling_percent [Float] Configured sampling percentage (0-100)
+    # @param random_value [Float] Random value in the range [0, 1)
+    # @return [Boolean] true when the random draw falls within the sampling threshold
+    def passes_sampling_percent(sampling_percent, random_value)
+      # Map random [0, 1) to an integer percent bucket [0, 100]
+      normalized_random_percent = (random_value * 101).floor
+      normalized_random_percent <= sampling_percent
+    end
+
+    # Checks whether a debug error template key is in the sampled set.
+    #
+    # @param message_template_key [String] The msg_t value from the debug event
+    # @return [Boolean] true when the key requires sampling before send
+    def is_sampled_debug_error_template_key(message_template_key)
+      SampledDebugErrorTemplateKeys.contains?(message_template_key)
+    end
+  end
+end

data/lib/wingify.rb

@@ -20,6 +20,7 @@ require_relative 'wingify/utils/brand_context'
 require_relative 'wingify/utils/brand_util'
 require_relative 'wingify/utils/event_util'
 require_relative 'wingify/services/settings_service'
+require_relative 'wingify/services/internal_events_sampling_service'
 
 module Wingify
   @@wingify_builder = nil
@@ -48,7 +49,9 @@ module Wingify
       else
         LoggerService.log(LogLevelEnum::ERROR, "INVALID_SETTINGS_SCHEMA", { accountId: options[:account_id], sdkKey: options[:sdk_key], settings: options[:settings], an: ApiEnum::INIT}, false)
       end
-      return @@wingify_builder.build(options[:settings])
+      # Keep Wingify.instance as the built client so debug sampling can read settings
+      @@instance = @@wingify_builder.build(options[:settings])
+      return @@instance
     end
 
     settings = @@wingify_builder.get_settings
@@ -99,9 +102,13 @@ module Wingify
         send_sdk_init_event(SettingsService.instance.settings_fetch_time, time_taken_for_init.to_s)
       end
 
-      usage_stats_account_id = new_instance&.original_settings&.dig("usageStatsAccountId")
+      # Send usage stats only when account id is present and sampling allows it
+      usage_stats_account_id = new_instance&.settings&.get_usage_stats_account_id
       if usage_stats_account_id
-        send_sdk_usage_stats_event(usage_stats_account_id)
+        sampling_service = InternalEventsSamplingService.new
+        if sampling_service.should_send_usage_stats_event(new_instance.settings)
+          send_sdk_usage_stats_event(usage_stats_account_id)
+        end
       end
 
       new_instance

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wingify-fme-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 1.60.1
+  version: 1.62.0
 platform: ruby
 authors:
 - Wingify
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uuidtools
@@ -221,6 +221,7 @@ files:
 - lib/wingify/api/set_attribute.rb
 - lib/wingify/api/track_event.rb
 - lib/wingify/constants/constants.rb
+- lib/wingify/constants/sampled_debug_error_template_keys.rb
 - lib/wingify/decorators/storage_decorator.rb
 - lib/wingify/enums/api_enum.rb
 - lib/wingify/enums/campaign_type_enum.rb
@@ -244,6 +245,7 @@ files:
 - lib/wingify/models/campaign/variation_model.rb
 - lib/wingify/models/gateway_service_model.rb
 - lib/wingify/models/schemas/settings_schema_validation.rb
+- lib/wingify/models/settings/internal_event_sampling_settings_model.rb
 - lib/wingify/models/settings/settings_model.rb
 - lib/wingify/models/storage/storage_data_model.rb
 - lib/wingify/models/user/context_model.rb
@@ -275,6 +277,7 @@ files:
 - lib/wingify/services/batch_event_queue.rb
 - lib/wingify/services/campaign_decision_service.rb
 - lib/wingify/services/hooks_service.rb
+- lib/wingify/services/internal_events_sampling_service.rb
 - lib/wingify/services/logger_service.rb
 - lib/wingify/services/settings_service.rb
 - lib/wingify/services/storage_service.rb
@@ -289,6 +292,7 @@ files:
 - lib/wingify/utils/function_util.rb
 - lib/wingify/utils/gateway_service_util.rb
 - lib/wingify/utils/impression_util.rb
+- lib/wingify/utils/internal_events_sampling_util.rb
 - lib/wingify/utils/log_message_util.rb
 - lib/wingify/utils/meg_util.rb
 - lib/wingify/utils/network_util.rb