feat: web insights connectivity support with get/set sessionId methods

Author: Abhi591

CHANGELOG.md

@@ -1,9 +1,54 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.18.0] - 2026-02-05
+
+### Added
+
+- Added session management capabilities to enable integration with VWO's web client testing campaigns. The SDK now automatically generates and manages session IDs to connect server-side feature flag decisions with client-side user sessions.
+
+  Example usage:
+
+  ```python
+  from vwo import init
+
+  options = {
+      'sdk_key': '32-alpha-numeric-sdk-key',
+      'account_id': '123456',
+  }
+
+  vwo_client = init(options)
+
+  # Session ID is automatically generated if not provided
+  context = {'id': 'user-123'}
+  flag = vwo_client.get_flag('feature-key', context)
+
+  # Access the session ID to pass to web client for session recording
+  session_id = flag.get_session_id()
+  print(f"Session ID for web client: {session_id}")
+  ```
+
+  You can also explicitly set a session ID to match a web client session:
+
+  ```python
+  from vwo import init
+
+  vwo_client = init(options)
+
+  context = {
+    'id': 'user-123',
+    'session_id': 1697123456  # Custom session ID matching web client
+  }
+
+  flag = vwo_client.get_flag('feature-key', context)
+  ```
+
+  This enhancement enables seamless integration between server-side feature flag decisions and client-side session recording, allowing for comprehensive user behavior analysis across both server and client environments.
+
 ## [1.17.0] - 2025-01-08
 
 ### Added

README.md

@@ -50,6 +50,51 @@ vwo_client.track_event('event_name', user_context, event_properties)
 vwo_client.set_attribute('attribute_key', 'attribute_value', user_context)
  ```
 
+## Utility Functions
+
+### getUUID
+
+The `getUUID` function generates a deterministic UUID for a given user and account combination. This utility function can be used without initializing the SDK, making it useful for generating consistent UUIDs across different parts of your application.
+
+#### Function Signature
+
+```python
+vwo.getUUID(user_id: str, account_id: str) -> Optional[str]
+```
+
+#### Parameters
+
+| **Parameter** | **Description**                                    | **Required** | **Type** |
+| ------------- | -------------------------------------------------- | ------------ | -------- |
+| `user_id`     | The user's unique identifier.                      | Yes          | str      |
+| `account_id`  | The VWO account ID associated with the user.        | Yes          | str      |
+
+#### Return Value
+
+- Returns a UUID string without dashes in uppercase format (e.g., `"A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"`)
+- Returns `None` if either parameter is not a valid non-empty string
+
+#### Example
+
+```python
+import vwo
+
+# Generate UUID for a user
+userId = 'user-123'
+accountId = '123456'
+
+uuid = vwo.getUUID(userId, accountId)
+
+print('Generated UUID:', uuid)
+# Output: Generated UUID: CC25A368ADA0542699EAD62489811105
+```
+
+#### Use Cases
+
+- Generate consistent UUIDs for users across different services
+- Create deterministic identifiers for analytics and tracking
+- Generate UUIDs without requiring SDK initialization
+
 ## Advanced Configuration Options
 
 To customize the SDK further, additional parameters can be passed to the `init()` API. Here’s a table describing each option:
@@ -82,6 +127,7 @@ The following table explains all the parameters in the `context` dictionary:
 | `custom_variables` | Custom attributes for targeting.                                           | No           | Dict |
 | `user_agent`       | User agent string for identifying the user's browser and operating system. | No           | str   |
 | `ip_address`       | IP address of the user.                                                    | No           | str   |
+| `session_id`       | Session ID for connecting server-side decisions with client-side sessions. | No           | int   |
 
 #### Example
 
@@ -93,10 +139,64 @@ context = {
         'location': 'US'
     },
     'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36',
-    'ip_address': '1.1.1.1'
+    'ip_address': '1.1.1.1',
+    'session_id': 1697123456  # Optional: Custom session ID for web client integration
+}
+```
+
+## Session Management
+
+The SDK provides automatic session management capabilities to enable seamless integration with VWO's web client testing campaigns. Session IDs are automatically generated and managed to connect server-side feature flag decisions with client-side user sessions.
+
+### Automatic Session ID Generation
+
+Session IDs are automatically generated using Unix timestamps when not explicitly provided in the context. This ensures consistent session tracking across all feature flag evaluations and event tracking.
+
+### Session ID Access
+
+You can access and manage session IDs through the following methods:
+
+- **Get Session ID from Flag**: Use `get_flag.get_session_id()` to retrieve the session ID used for a specific feature flag evaluation
+- **Set Custom Session ID**: Set `session_id` in your context dictionary to use a custom session ID (useful for matching web client sessions)
+
+### Example Usage
+
+```python
+from vwo import init
+
+options = {
+    'sdk_key': '32-alpha-numeric-sdk-key',
+    'account_id': '123456'
+}
+
+vwo_client = init(options)
+
+# Session ID is automatically generated if not provided
+context = {'id': 'user-123'}
+flag = vwo_client.get_flag('feature-key', context)
+
+# Access the session ID to pass to web client for session recording
+session_id = flag.get_session_id()
+print(f"Session ID for web client: {session_id}")
+```
+
+You can also explicitly set a session ID to match a web client session:
+
+```python
+from vwo import init
+
+vwo_client = init(options)
+
+context_with_session = {
+    'id': 'user-123',
+    'session_id': 1697123456  # Custom session ID matching web client
 }
+
+flag = vwo_client.get_flag('feature-key', context_with_session)
 ```
 
+This enhancement enables seamless integration between server-side feature flag decisions and client-side session recording, allowing for comprehensive user behavior analysis across both server and client environments.
+
 ### Basic Feature Flagging
 
 Feature Flags serve as the foundation for all testing, personalization, and rollout rules within FME.

setup.py

@@ -121,7 +121,7 @@ def run(self):
 
 setup(
     name="vwo-fme-python-sdk",
-    version="1.17.0",
+    version="1.18.0",
     description="VWO Feature Management and Experimentation SDK for Python",
     long_description=long_description,
     long_description_content_type="text/markdown",

vwo/__init__.py

@@ -12,6 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .vwo import init
+from .vwo import init, getUUID
 from .packages.storage.connector import StorageConnector
 from .packages.logger.enums.log_level_enum import LogLevelEnum

vwo/api/get_flag_api.py

@@ -48,6 +48,9 @@
 from ..utils.network_util import get_track_user_payload_data
 from ..enums.event_enum import EventEnum
 from ..services.settings_manager import SettingsManager
+from ..utils.function_util import (
+    get_current_unix_timestamp,
+)
 
 
 class GetFlagApi:
@@ -86,7 +89,7 @@ def get(
             "an": ApiEnum.GET_FLAG.value,
             "fk": feature_key,
             "uuid": context.get_vwo_uuid(),
-            "sId": context.get_vwo_session_id(),
+            "sId": context.get_session_id(),
         }
 
         storage_service = StorageService()
@@ -147,6 +150,11 @@ def get(
             LogManager.get_instance().error_log("FEATURE_NOT_FOUND", data={"featureKey": feature_key}, debug_data = debug_event_props)
             self._get_flag_response.set_is_enabled(False)
             return self._get_flag_response
+        
+        if context.get_session_id() is None:
+            context.set_session_id(get_current_unix_timestamp())
+
+        self._get_flag_response.set_session_id(context.get_session_id())
 
         SegmentationManager.get_instance().set_contextual_data(
             settings, feature, context
@@ -445,4 +453,4 @@ def update_debug_event_props_with_message(
                 else experiment_key
             )
             message += f" and experiment:{experiment_suffix} with variation:{experiment_variation_id}"
-        debug_event_props["msg"] = message
+        debug_event_props["msg"] = message

vwo/api/set_attribute_api.py

@@ -27,6 +27,7 @@
 from ..enums.event_enum import EventEnum
 
 
+
 class SetAttributeApi:
     def set_attribute(
         self, settings: SettingsModel, attribute_map: Dict, context: ContextModel
@@ -43,13 +44,11 @@ def create_and_send_impression_for_attribute(
         )
         # Construct payload data for tracking the goal
         payload = get_attribute_payload_data(
-            settings,
-            context,
-            EventEnum.VWO_SYNC_VISITOR_PROP.value,
-            attribute_map
+            settings, context, EventEnum.VWO_SYNC_VISITOR_PROP.value, attribute_map
         )
 
         from vwo.vwo_client import VWOClient
+
         vwo_instance = VWOClient.get_instance()
 
         # Check if batch events are enabled
@@ -58,4 +57,4 @@ def create_and_send_impression_for_attribute(
             vwo_instance.batch_event_queue.enqueue(payload)
         else:
             # Send the event immediately if batch events are not enabled
-            send_post_api_request(properties, payload, context.get_id())
+            send_post_api_request(properties, payload, context.get_id())

vwo/api/track_api.py

@@ -58,7 +58,7 @@ def track(
             hook_manager.execute(hook_manager.get())
             return {event_name: True}
 
-        LogManager.get_instance().error_log("EVENT_NOT_FOUND", data={"eventName": event_name}, debug_data={"an": ApiEnum.TRACK_EVENT.value, "uuid": context.get_vwo_uuid(), "sId": context.get_vwo_session_id()})
+        LogManager.get_instance().error_log("EVENT_NOT_FOUND", data={"eventName": event_name}, debug_data={"an": ApiEnum.TRACK_EVENT.value, "uuid": context.get_vwo_uuid(), "sId": context.get_session_id()})
         return {event_name: False}
 
     def create_and_send_impression_for_track(
@@ -83,13 +83,11 @@ def create_and_send_impression_for_track(
         )
         # Construct payload data for tracking the goal
         payload = get_track_goal_payload_data(
-            settings,
-            context,
-            event_name,
-            event_properties,
+            settings, context, event_name, event_properties
         )
 
         from vwo.vwo_client import VWOClient
+
         vwo_instance = VWOClient.get_instance()
 
         # Check if batch events are enabled
@@ -98,4 +96,4 @@ def create_and_send_impression_for_track(
             vwo_instance.batch_event_queue.enqueue(payload)
         else:
             # Send the event immediately if batch events are not enabled
-            send_post_api_request(properties, payload, context.get_id())
+            send_post_api_request(properties, payload, context.get_id())

vwo/constants/Constants.py

@@ -17,7 +17,7 @@ class Constants:
     # TODO: read from setup.py
     sdk_meta = {
         "name": "vwo-fme-python-sdk",
-        "version": "1.17.0"
+        "version": "1.18.0"
     }
 
     # Constants

vwo/decorators/storage_decorator.py

@@ -51,23 +51,23 @@ def set_data_in_storage(
         context = data.get("context")
 
         if not feature_key:
-            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "featureKey"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_vwo_session_id()})
+            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "featureKey"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_session_id()})
             return None  # Invalid feature key, return None
 
         if not context or not context.get_id():
-            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "Context or Context.id"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_vwo_session_id()})
+            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "Context or Context.id"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_session_id()})
             return None  # Invalid user ID, return None
 
         if (
             data.get("rolloutKey")
             and not data.get("experimentKey")
             and not data.get("rolloutVariationId")
         ):
-            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "rolloutKey or experimentKey or rolloutVariationId"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_vwo_session_id()})
+            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "rolloutKey or experimentKey or rolloutVariationId"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_session_id()})
             return None  # Invalid rollout variation, return None
 
         if data.get("experimentKey") and not data.get("experimentVariationId"):
-            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "Variation:(rolloutKey, experimentKey or rolloutVariationId)"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_vwo_session_id()})
+            LogManager.get_instance().error_log("ERROR_STORING_DATA_IN_STORAGE",data={"key": "Variation:(rolloutKey, experimentKey or rolloutVariationId)"}, debug_data={"an": ApiEnum.GET_FLAG.value, "uuid": context.get_vwo_uuid(), "sId": context.get_session_id()})
             return None  # Invalid experiment variation, return None
 
         success = storage_service.set_data_in_storage(

vwo/models/user/context_model.py

@@ -30,8 +30,10 @@ def __init__(self, context: Dict):
         )
         self._vwo = ContextVWOModel(context.get("_vwo")) if "_vwo" in context else None
         self.post_segmentation_variables = context.get("post_segmentation_variables", [])
+        self.session_id = context.get("session_id", None)
+        if self.session_id is None:
+            self.session_id = get_current_unix_timestamp()
         self._vwo_uuid = get_uuid(self.id, str(SettingsManager.get_instance().get_account_id()))
-        self._vwo_session_id = get_current_unix_timestamp()
 
     def get_id(self) -> str:
         return str(self.id) if self.id is not None else None
@@ -71,15 +73,16 @@ def get_post_segmentation_variables(self) -> List[str]:
 
     def set_post_segmentation_variables(self, post_segmentation_variables: List[str]) -> None:
         self.post_segmentation_variables = post_segmentation_variables
+    
 
     def get_vwo_uuid(self) -> str:
         return self._vwo_uuid
 
-    def get_vwo_session_id(self) -> str:
-        return self._vwo_session_id
-
     def set_vwo_uuid(self, vwo_uuid: str) -> None:
         self._vwo_uuid = vwo_uuid
+    
+    def get_session_id(self) -> int:
+        return self.session_id
 
-    def set_vwo_session_id(self, vwo_session_id: str) -> None:
-        self._vwo_session_id = vwo_session_id
+    def set_session_id(self, session_id: int) -> None:
+        self.session_id = session_id