Skip to content

Commit 304b839

Browse files
Abhi591Abhi591
committed
chore: updated README with more code examples
1 parent e5b1b55 commit 304b839

File tree

1 file changed

+203
-18
lines changed

1 file changed

+203
-18
lines changed

‎README.md

+203-18
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
[![codecov](https://codecov.io/gh/wingify/vwo-fme-python-sdk/branch/master/graph/badge.svg?token=)](https://codecov.io/gh/wingify/vwo-fme-python-sdk)
66
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
77

8-
This open source library allows you to A/B Test your Website at server-side.
8+
## Overview
9+
10+
The **VWO Feature Management and Experimentation SDK** (VWO FME Python SDK) enables python developers to integrate feature flagging and experimentation into their applications. This SDK provides full control over feature rollout, A/B testing, and event tracking, allowing teams to manage features dynamically and gain insights into user behavior.
911

1012
## Requirements
1113

@@ -19,9 +21,10 @@ It's recommended you use [virtualenv](https://virtualenv.pypa.io/en/latest/) to
1921
pip install vwo-fme-python-sdk
2022
```
2123

22-
## Basic usage
24+
## Basic Usage Example
2325

24-
```python
26+
The following example demonstrates initializing the SDK with a VWO account ID and SDK key, setting a user context, checking if a feature flag is enabled, and tracking a custom event.
27+
```python
2528
from vwo import init
2629

2730
options = {
@@ -45,9 +48,164 @@ vwo_client.track_event('event_name', user_context, event_properties)
4548

4649
# set attribute
4750
vwo_client.set_attribute('attribute_key', 'attribute_value', user_context)
51+
```
52+
53+
## Advanced Configuration Options
54+
55+
To customize the SDK further, additional parameters can be passed to the `init()` API. Here’s a table describing each option:
56+
57+
| **Parameter** | **Description** | **Required** | **Type** | **Example** |
58+
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------- | ------------------------------- |
59+
| `account_id` | VWO Account ID for authentication. | Yes | str | `'123456'` |
60+
| `sdk_key` | SDK key corresponding to the specific environment to initialize the VWO SDK Client. You can get this key from VWO Application. | Yes | str | `'32-alpha-numeric-sdk-key'` |
61+
| `poll_interval` | Time interval for fetching updates from VWO servers (in milliseconds). | No | int | `60_000` |
62+
| `gateway_service` | Configuration for integrating VWO Gateway Service. Service. | No | Dictionary | see [Gateway](#gateway) section |
63+
| `storage` | Custom storage connector for persisting user decisions and campaign data. data. | No | Dictionary | See [Storage](#storage) section |
64+
| `logger` | Toggle log levels for more insights or for debugging purposes. You can also customize your own transport in order to have better control over log messages. | No | Dictionary | See [Logger](#logger) section |
65+
| `integrations` | Callback function for integrating with third-party analytics services. | No | Function | See [Integrations](#integrations) section |
66+
67+
### User Context
68+
69+
The `context` uniquely identifies users and is crucial for consistent feature rollouts. A typical `context` is a dictionary that includes an `id` key for identifying the user. It can also include other attributes that can be used for targeting and segmentation, such as `custom_variables`, `user_agent`, and `ip_address`.
70+
71+
#### Parameters Table
72+
73+
The following table explains all the parameters in the `context` dictionary:
74+
75+
| **Parameter** | **Description** | **Required** | **Type** |
76+
| ----------------- | -------------------------------------------------------------------------- | ------------ | -------- |
77+
| `id` | Unique identifier for the user. | Yes | str |
78+
| `custom_variables` | Custom attributes for targeting. | No | Dict |
79+
| `user_agent` | User agent string for identifying the user's browser and operating system. | No | str |
80+
| `ip_address` | IP address of the user. | No | str |
81+
82+
#### Example
83+
84+
```python
85+
context = {
86+
'id': 'unique_user_id',
87+
'custom_variables': {
88+
'age': 25,
89+
'location': 'US'
90+
},
91+
'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',
92+
'ip_address': '1.1.1.1'
93+
}
94+
```
95+
96+
### Basic Feature Flagging
97+
98+
Feature Flags serve as the foundation for all testing, personalization, and rollout rules within FME.
99+
To implement a feature flag, first use the `get_flag()` method to retrieve the flag configuration.
100+
The `get_flag()` method provides a simple way to check if a feature is enabled for a specific user and access its variables. It returns a `GetFlag` object that contains methods like `is_enabled()` for checking the feature's status and `get_variable()` for retrieving any associated variables.
101+
102+
| Parameter | Description | Required | Type |
103+
| ------------ | ---------------------------------------------------------------- | -------- | ----------- |
104+
| `feature_key` | Unique identifier of the feature flag | Yes | str |
105+
| `context` | Dictionary containing user identification and contextual information | Yes | Dict |
106+
107+
Example usage:
108+
109+
```python
110+
feature_flag = vwo_client.get_flag("feature_key", context)
111+
is_enabled = feature_flag.is_enabled()
112+
113+
if is_enabled:
114+
print("Feature is enabled!")
115+
116+
# Get and use feature variable with type safety
117+
variable_value = feature_flag.get_variable('feature_variable', 'default_value')
118+
print("Variable value: " + variable_value)
119+
else:
120+
print("Feature is not enabled!")
121+
```
122+
123+
### Custom Event Tracking
124+
125+
Feature flags can be enhanced with connected metrics to track key performance indicators (KPIs) for your features. These metrics help measure the effectiveness of your testing rules by comparing control versus variation performance, and evaluate the impact of personalization and rollout campaigns. Use the `track_event()` method to track custom events like conversions, user interactions, and other important metrics:
126+
127+
| Parameter | Description | Required | Type |
128+
| ----------------- | ---------------------------------------------------------------------- | -------- | ----------- |
129+
| `event_name` | Name of the event you want to track | Yes | str |
130+
| `context` | Dictionary containing user identification and contextual information | Yes | Dict |
131+
| `event_properties` | Additional properties/metadata associated with the event | No | Dict |
132+
133+
Example usage:
134+
135+
```python
136+
vwo_client.track_event('event_name', context, event_properties)
137+
```
138+
139+
### Pushing Attributes
140+
141+
User attributes provide rich contextual information about users, enabling powerful personalization. The `set_attribute()` method in VWOClient provides a simple way to associate these attributes with users in VWO for advanced segmentation. The method accepts an attribute key, value, and dictionary containing the user information. Here's what you need to know about the method parameters:
142+
143+
| Parameter | Description | Required | Type |
144+
| ---------------- | ---------------------------------------------------------------------- | -------- | ----------- |
145+
| `attribute_key` | The unique identifier/name of the attribute you want to set | Yes | str |
146+
| `attribute_value` | The value to be assigned to the attribute | Yes | Any |
147+
| `context` | Dictionary containing user identification and other contextual information | Yes | Dict |
148+
149+
Example usage:
150+
151+
```python
152+
vwo_client.set_attribute('attribute_key', 'attribute_value', context)
153+
```
154+
155+
### Polling Interval Adjustment
156+
157+
The `poll_interval` is an optional parameter that allows the SDK to automatically fetch and update settings from the VWO server at specified intervals. Setting this parameter ensures your application always uses the latest configuration.
158+
159+
```python
160+
options = {
161+
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
162+
'account_id': '123456', # VWO Account ID
163+
'poll_interval': 60000 # Set the poll interval to 60 seconds
164+
}
165+
166+
vwo_client = init(options)
167+
```
168+
169+
### Gateway
170+
171+
The VWO FME Gateway Service is an optional but powerful component that enhances VWO's Feature Management and Experimentation (FME) SDKs. It acts as a critical intermediary for pre-segmentation capabilities based on user location and user agent (UA). By deploying this service within your infrastructure, you benefit from minimal latency and strengthened security for all FME operations.
172+
173+
#### Why Use a Gateway?
174+
175+
The Gateway Service is required in the following scenarios:
176+
177+
- When using pre-segmentation features based on user location or user agent.
178+
- For applications requiring advanced targeting capabilities.
179+
- It's mandatory when using any thin-client SDK (e.g., Go).
180+
181+
#### How to Use the Gateway
182+
183+
The gateway can be customized by passing the `gateway_service` parameter in the `init` configuration.
184+
185+
```python
186+
options = {
187+
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
188+
'account_id': '123456', # VWO Account ID
189+
'gateway_service': {
190+
'url': 'http://custom.gateway.com'
191+
}
192+
}
193+
vwo_client = init(options)
48194
```
49195

50-
- **Storage**
196+
### Storage
197+
198+
The SDK operates in a stateless mode by default, meaning each `get_flag` call triggers a fresh evaluation of the flag against the current user context.
199+
200+
To optimize performance and maintain consistency, you can implement a custom storage mechanism by passing a `storage` parameter during initialization. This allows you to persist feature flag decisions in your preferred database system (like Redis, MongoDB, or any other data store).
201+
202+
Key benefits of implementing storage:
203+
204+
- Improved performance by caching decisions
205+
- Consistent user experience across sessions
206+
- Reduced load on your application
207+
208+
The storage mechanism ensures that once a decision is made for a user, it remains consistent even if campaign settings are modified in the VWO Application. This is particularly useful for maintaining a stable user experience during A/B tests and feature rollouts.
51209

52210
```python
53211
from vwo import StorageConnector
@@ -56,7 +214,7 @@ class UserStorage(StorageConnector):
56214
return client_db.get(f"{key}_{user_id}")
57215

58216
def set(self, value: dict):
59-
key = f"{value.get('featureKey')}_{value.get('user')}"
217+
key = f"{value.get('featureKey')}_{value.get('userId')}"
60218
client_db[key] = {
61219
'rolloutKey': value.get('rolloutKey'),
62220
'rolloutVariationId': value.get('rolloutVariationId'),
@@ -76,31 +234,58 @@ options = {
76234
vwo_client = init(options)
77235
```
78236

79-
- **Log messages**
237+
### Logger
238+
239+
VWO by default logs all `ERROR` level messages to your server console.
240+
To gain more control over VWO's logging behaviour, you can use the `logger` parameter in the `init` configuration.
241+
242+
| **Parameter** | **Description** | **Required** | **Type** | **Default Value** |
243+
| ------------- | -------------------------------------- | ------------ | -------- | ----------------- |
244+
| `level` | Log level to control verbosity of logs | Yes | str | `ERROR` |
245+
| `prefix` | Custom prefix for log messages | No | str | `VWO-SDK` |
246+
247+
#### Example 1: Set log level to control verbosity of logs
80248

81249
```python
82-
from vwo import LogLevelEnum
83250
options = {
84-
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
85251
'account_id': '123456', # VWO Account ID
252+
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
86253
'logger': {
87-
'level': LogLevelEnum.DEBUG,
88-
'prefix': 'VWO-FME-PYTHON-SDK'
254+
'level': 'DEBUG'
89255
}
90256
}
91-
92257
vwo_client = init(options)
93258
```
94259

95-
- **Polling support**
260+
#### Example 2: Add custom prefix to log messages for easier identification
96261

97262
```python
98263
options = {
99-
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
100264
'account_id': '123456', # VWO Account ID
101-
'poll_interval': 5000 # in milliseconds
265+
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
266+
'logger': {
267+
'level': 'DEBUG',
268+
'prefix': 'CUSTOM LOG PREFIX'
269+
}
102270
}
271+
vwo_client = init(options)
272+
```
273+
274+
### Integrations
275+
VWO FME SDKs provide seamless integration with third-party tools like analytics platforms, monitoring services, customer data platforms (CDPs), and messaging systems. This is achieved through a simple yet powerful callback mechanism that receives VWO-specific properties and can forward them to any third-party tool of your choice.
103276

277+
```python
278+
def callback(properties):
279+
# properties will contain all the required VWO specific information
280+
print(properties)
281+
282+
options = {
283+
'sdk_key': '32-alpha-numeric-sdk-key', # SDK Key
284+
'account_id': '12345', # VWO Account ID
285+
'integrations': {
286+
'callback': callback
287+
}
288+
}
104289
vwo_client = init(options)
105290
```
106291

@@ -120,18 +305,18 @@ python setup.py test
120305

121306
* [Abhishek Joshi](https://github.com/Abhi591)
122307

123-
## Changelog
308+
### Version History
124309

125-
Refer [CHANGELOG.md](https://github.com/wingify/vwo-fme-python-sdk/blob/master/CHANGELOG.md)
310+
The version history tracks changes, improvements, and bug fixes in each version. For a full history, see the [CHANGELOG.md](https://github.com/wingify/vwo-fme-python-sdk/blob/master/CHANGELOG.md).
126311

127312
## Contributing
128313

129-
Please go through our [contributing guidelines](https://github.com/wingify/vwo-fme-python-sdk/blob/master/CONTRIBUTING.md)
314+
We welcome contributions to improve this SDK! Please read our [contributing guidelines](https://github.com/wingify/vwo-fme-python-sdk/blob/master/CONTRIBUTING.md) before submitting a PR.
130315

131316

132317
## Code of Conduct
133318

134-
[Code of Conduct](https://github.com/wingify/vwo-fme-python-sdk/blob/master/CODE_OF_CONDUCT.md)
319+
Our [Code of Conduct](https://github.com/wingify/vwo-fme-python-sdk/blob/master/CODE_OF_CONDUCT.md) outlines expectations for all contributors and maintainers.
135320

136321
## License
137322

0 commit comments

Comments
 (0)