VWO Feature Management and Experimentation SDK for Java

Overview

The VWO Feature Management and Experimentation SDK (VWO FME Java SDK) enables java 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.

Requirements

The Java SDK supports:

Open JDK - 8 onwards
Oracle JDK - 8 onwards

Our Build is successful on these Java Versions -

Installation

Install dependencies using mvn install

Add below Maven dependency in your project.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

<dependency>
    <groupId>com.vwo.sdk</groupId>
    <artifactId>vwo-fme-java-sdk</artifactId>
    <version>LATEST</version>
</dependency>

Wingify (SDK version >= 1.50.0) — recommended

<dependency>
    <groupId>com.wingify.sdk</groupId>
    <artifactId>wingify-fme-java-sdk</artifactId>
    <version>LATEST</version>
</dependency>

Basic Usage Example

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.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.VWO;
import com.vwo.models.user.VWOContext;
import com.vwo.models.user.GetFlag;
import com.vwo.models.user.VWOInitOptions;
import java.util.HashMap;
import java.util.Map;

public class VWOExample {
    public static void main(String[] args) {
        // Initialize VWO SDK with your account details
        VWOInitOptions vwoInitOptions = new VWOInitOptions();
        vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key"); // Replace with your SDK key
        vwoInitOptions.setAccountId(123456); // Replace with your account ID

        // Initialize VWO instance
        VWO vwoInstance = VWO.init(vwoInitOptions);

        // Create user context
        VWOContext context = new VWOContext();
        context.setId("unique_user_id"); // Set a unique user identifier

        // Check if a feature flag is enabled
        GetFlag getFlag = vwoInstance.getFlag("feature_key", context);
        Boolean isFeatureEnabled = getFlag.isEnabled();
        System.out.println("Is feature enabled? " + isFeatureEnabled);

        // Get a variable value with a default fallback
        String variableValue = (String) getFlag.getVariable("feature_variable", "default_value");
        System.out.println("Variable value: " + variableValue);

        // Track a custom event
        Map<String, Boolean> trackResponse = vwoInstance.trackEvent("event_name", context);
        System.out.println("Event tracked: " + trackResponse);

        // Set multiple custom attributes
        Map<String, Object> attributeMap = new HashMap<>();
        attributeMap.put("attribute-name", "attribute-value");
        vwoInstance.setAttribute(attributeMap, context);
    }
}

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.Wingify;
import com.wingify.models.user.WingifyUserContext;
import com.wingify.models.user.GetFlag;
import com.wingify.models.user.WingifyInitOptions;
import java.util.HashMap;
import java.util.Map;

public class WingifyExample {
    public static void main(String[] args) {
        // Initialize Wingify SDK with your account details
        WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
        wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key"); // Replace with your SDK key
        wingifyInitOptions.setAccountId(123456); // Replace with your account ID

        // Initialize Wingify instance
        Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

        // Create user context
        WingifyUserContext context = new WingifyUserContext();
        context.setId("unique_user_id"); // Set a unique user identifier

        // Check if a feature flag is enabled
        GetFlag getFlag = wingifyInstance.getFlag("feature_key", context);
        Boolean isFeatureEnabled = getFlag.isEnabled();
        System.out.println("Is feature enabled? " + isFeatureEnabled);

        // Get a variable value with a default fallback
        String variableValue = (String) getFlag.getVariable("feature_variable", "default_value");
        System.out.println("Variable value: " + variableValue);

        // Track a custom event
        Map<String, Boolean> trackResponse = wingifyInstance.trackEvent("event_name", context);
        System.out.println("Event tracked: " + trackResponse);

        // Set multiple custom attributes
        Map<String, Object> attributeMap = new HashMap<>();
        attributeMap.put("attribute-name", "attribute-value");
        wingifyInstance.setAttribute(attributeMap, context);
    }
}

UUID Generation

The VWO SDK provides a utility function to generate usage-neutral, deterministic UUIDs based on the user ID and account ID. This can be useful for consistent user identification across different systems or for pre-generating UUIDs.

This function does not require the SDK to be initialized.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.VWO;

String userId = "user123";
String accountId = "account456";

String uuid = VWO.getUUID(userId, accountId);
System.out.println("Generated UUID: " + uuid);

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.Wingify;

String userId = "user123";
String accountId = "account456";

String uuid = Wingify.getUUID(userId, accountId);
System.out.println("Generated UUID: " + uuid);

The function returns a UUID string without dashes in uppercase format, or null if invalid input is provided.

Advanced Configuration Options

To customize the SDK further, additional parameters can be passed to the init() API using the VWOInitOptions object (or WingifyInitOptions for SDK version 1.50.0 and later). Here’s a table describing each option:

Parameter	Description	Required	Type	Example
`setAccountId`	VWO Account ID for authentication.	Yes	String	`'123456'`
`setSdkKey`	SDK key corresponding to the specific environment to initialize the VWO SDK Client. You can get this key from VWO Application.	Yes	String	`'32-alpha-numeric-sdk-key'`
`setPollInterval`	Time interval for fetching updates from VWO servers (in milliseconds).	No	Number	`60000`
`setGatewayService`	Configuration for integrating VWO Gateway Service. Service.	No	Object	see Gateway section
`setStorage`	Custom storage connector for persisting user decisions and campaign data. data.	No	Object	See Storage section
`setLogger`	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	Object	See Logger section
`setIntegrations`	Callback function for integrating with third-party analytics services.	No	Function	See Integrations section
`setIsAliasingEnabled`	Enable user aliasing functionality. Requires gateway service to be configured.	No	Boolean	see UserAliasing section
`setProxyUrl`	Custom proxy URL for redirecting all SDK network requests (settings, tracking, etc.) through your own proxy server.	No	String	see Proxy section

Refer to the official VWO documentation for additional parameter details.

User Context

The VWOContext object (or WingifyUserContext for SDK version 1.50.0 and later) uniquely identifies users and is crucial for consistent feature rollouts. A typical context includes an id for identifying the user, set via setId(). It can also include other attributes that can be used for targeting and segmentation, such as custom variables (set via setCustomVariables()), user agent (set via setUserAgent()), IP address (set via setIpAddress()), and platform variables (set via setPlatformVariables()) for Web Testing pre-segmentation.

Parameters Table

The following table explains all the parameters in the context object:

Parameter	Description	Required	Type
`setId`	Unique identifier for the user.	Yes	String
`setCustomVariables`	Custom attributes for targeting.	No	Map<String, Object>
`setUserAgent`	User agent string for identifying the user's browser and operating system.	No	String
`setIpAddress`	IP address of the user.	No	String
`setPlatformVariables`	Platform-level data for pre-segmentation (e.g. Web Testing campaign assignments under `webTestingCampaigns`, usually provided by your frontend).	No	Map<String, ?>

Example

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOContext context = new VWOContext();
context.setId("unique_user_id"); // Set a unique user identifier

// Create the map using HashMap in Java 8 and below
Map<String, Object> customVariables = new HashMap<>();
customVariables.put("age", 25);
customVariables.put("location", "US");
context.setCustomVariables(customVariables);

context.setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36");
context.setIpAddress("1.1.1.1");

Wingify (SDK version >= 1.50.0) — recommended

WingifyUserContext context = new WingifyUserContext();
context.setId("unique_user_id"); // Set a unique user identifier

// Create the map using HashMap in Java 8 and below
Map<String, Object> customVariables = new HashMap<>();
customVariables.put("age", 25);
customVariables.put("location", "US");
context.setCustomVariables(customVariables);

context.setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36");
context.setIpAddress("1.1.1.1");

Web testing pre-segmentation

Server-side flag decisions can align with Web Testing (browser) experiments. Campaign assignments are typically read on the frontend (e.g. VWO cookies) and sent to your server; pass them in platformVariables.webTestingCampaigns as a map of campaign ID → variation ID (strings), or as a JSON string of that object.

Pre-segment rules in the VWO dashboard can use the campaignVariation operator:

Operand pattern	Meaning
`C`	User is in campaign `C` (any variation).
`!C`	User is not in campaign `C`.
`C_V`	User is in campaign `C` with variation `V`.
`C_!V`	User is in campaign `C` and assigned variation is not `V`.

Rollout rules evaluate pre-segments from the first variation only; AB/testing rules use campaign-level segments.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.VWO;
import com.vwo.models.user.VWOContext;
import com.vwo.models.user.GetFlag;
import com.vwo.models.user.VWOInitOptions;
import java.util.HashMap;
import java.util.Map;

VWOInitOptions options = new VWOInitOptions();
options.setAccountId(123456);
options.setSdkKey("32-alpha-numeric-sdk-key");
VWO vwoClient = VWO.init(options);

VWOContext context = new VWOContext();
context.setId("user-123");

Map<String, Object> platformVariables = new HashMap<>();
// Values should match what your frontend sends (example shape only)
platformVariables.put("webTestingCampaigns", "{\"122\":\"1\",\"130\":\"2\"}");
context.setPlatformVariables(platformVariables);

GetFlag flag = vwoClient.getFlag("feature_key", context);

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.Wingify;
import com.wingify.models.user.WingifyUserContext;
import com.wingify.models.user.GetFlag;
import com.wingify.models.user.WingifyInitOptions;
import java.util.HashMap;
import java.util.Map;

WingifyInitOptions options = new WingifyInitOptions();
options.setAccountId(123456);
options.setSdkKey("32-alpha-numeric-sdk-key");
Wingify wingifyClient = Wingify.init(options);

WingifyUserContext context = new WingifyUserContext();
context.setId("user-123");

Map<String, Object> platformVariables = new HashMap<>();
// Values should match what your frontend sends (example shape only)
platformVariables.put("webTestingCampaigns", "{\"122\":\"1\",\"130\":\"2\"}");
context.setPlatformVariables(platformVariables);

GetFlag flag = wingifyClient.getFlag("feature_key", context);

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 flag.getSessionId() to retrieve the session ID used for a specific feature flag evaluation
Set Custom Session ID: Use context.setSessionId(sessionId) to set a custom session ID (useful for matching web client sessions)

Example Usage

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.VWO;
import com.vwo.models.user.VWOContext;
import com.vwo.models.user.GetFlag;
import com.vwo.models.user.VWOInitOptions;

// Initialize VWO client
VWOInitOptions options = new VWOInitOptions();
options.setAccountId(123456);
options.setSdkKey("32-alpha-numeric-sdk-key");
VWO vwoClient = VWO.init(options);

// Session ID is automatically generated if not provided
VWOContext context = new VWOContext();
context.setId("user-123");
GetFlag flag = vwoClient.getFlag("feature-key", context);

// Access the session ID to pass to web client for session recording
long sessionId = flag.getSessionId();
System.out.println("Session ID for web client: " + sessionId);

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.Wingify;
import com.wingify.models.user.WingifyUserContext;
import com.wingify.models.user.GetFlag;
import com.wingify.models.user.WingifyInitOptions;

// Initialize Wingify client
WingifyInitOptions options = new WingifyInitOptions();
options.setAccountId(123456);
options.setSdkKey("32-alpha-numeric-sdk-key");
Wingify wingifyClient = Wingify.init(options);

// Session ID is automatically generated if not provided
WingifyUserContext context = new WingifyUserContext();
context.setId("user-123");
GetFlag flag = wingifyClient.getFlag("feature-key", context);

// Access the session ID to pass to web client for session recording
long sessionId = flag.getSessionId();
System.out.println("Session ID for web client: " + sessionId);

You can also explicitly set a session ID to match web client session

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOContext context = new VWOContext();
context.setId("user-123");
context.setSessionId(1697123456); // Custom session ID matching web client
GetFlag flag = vwoClient.getFlag("feature-key", context);

Wingify (SDK version >= 1.50.0) — recommended

WingifyUserContext context = new WingifyUserContext();
context.setId("user-123");
context.setSessionId(1697123456); // Custom session ID matching web client
GetFlag flag = wingifyClient.getFlag("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.

Basic Feature Flagging

Feature Flags serve as the foundation for all testing, personalization, and rollout rules within FME. To implement a feature flag, first use the getFlag() method to retrieve the flag configuration. The getFlag() 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 isEnabled() for checking the feature's status and getVariable() for retrieving any associated variables.

Parameter	Description	Required	Type
`featureKey`	Unique identifier of the feature flag	Yes	String
`context`	Object containing user identification and contextual information	Yes	VWOContext / WingifyUserContext

Example usage:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

GetFlag featureFlag = vwoInstance.getFlag("feature_key", context);
Boolean isEnabled = featureFlag.isEnabled();

if (isEnabled) {
  System.out.println("Feature is enabled!");

  // Get and use feature variable with type safety
  String variableValue = (String) featureFlag.getVariable("feature_variable", "default_value");
  System.out.println("Variable value: " + variableValue);
} else {
  System.out.println("Feature is not enabled!");
}

Wingify (SDK version >= 1.50.0) — recommended

GetFlag featureFlag = wingifyInstance.getFlag("feature_key", context);
Boolean isEnabled = featureFlag.isEnabled();

if (isEnabled) {
  System.out.println("Feature is enabled!");

  // Get and use feature variable with type safety
  String variableValue = (String) featureFlag.getVariable("feature_variable", "default_value");
  System.out.println("Variable value: " + variableValue);
} else {
  System.out.println("Feature is not enabled!");
}

Custom Event Tracking

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 trackEvent() method to track custom events like conversions, user interactions, and other important metrics:

Parameter	Description	Required	Type
`eventName`	Name of the event you want to track	Yes	String
`context`	Object containing user identification and contextual information	Yes	VWOContext / WingifyUserContext
`eventProperties`	Additional properties/metadata associated with the event	No	Map<String, Object>

Example usage:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

Map<String, Object> eventProperties = new HashMap<>();
eventProperties.put("amount", 49.99);

vwoInstance.trackEvent("event_name", context, eventProperties);

Wingify (SDK version >= 1.50.0) — recommended

Map<String, Object> eventProperties = new HashMap<>();
eventProperties.put("amount", 49.99);

wingifyInstance.trackEvent("event_name", context, eventProperties);

See Tracking Conversions documentation for more information.

Pushing Attributes

User attributes provide rich contextual information about users, enabling powerful personalization. The setAttribute() method provides a simple way to associate these attributes with users in VWO for advanced segmentation. The method accepts an attribute map and the user context object containing the user information. Here's what you need to know about the method parameters:

Parameter	Description	Required	Type
`attributeMap`	Multiple attributes you want to set for a user.	Yes	Map<String, Object>
`context`	Object containing user identification and other contextual information	Yes	VWOContext / WingifyUserContext

Example usage:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

Map<String, Object> attributeMap = new HashMap<>();
attributeMap.put("attribute-name", "attribute-value");
vwoInstance.setAttribute(attributeMap, context);

Wingify (SDK version >= 1.50.0) — recommended

Map<String, Object> attributeMap = new HashMap<>();
attributeMap.put("attribute-name", "attribute-value");
wingifyInstance.setAttribute(attributeMap, context);

See Pushing Attributes documentation for additional information.

Polling Interval Adjustment

The setPollInterval is an optional parameter that allows the SDK to automatically fetch and update settings from the VWO server at specified intervals. The polling interval can be configured in three ways:

Set via SDK options: If pollInterval is specified in the initialization options (must be >= 1000 milliseconds), that interval will be used
VWO Application Settings: If configured in your VWO application settings, that interval will be used
Default Fallback: If neither of the above is set, a 10 minute (600,000 milliseconds) polling interval is used

Setting this parameter ensures your application always uses the latest configuration by periodically checking for and applying any updates.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setPollInterval(60000); // Set the poll interval to 60 seconds

VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setPollInterval(60000); // Set the poll interval to 60 seconds

Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Proxy

The setProxyUrl parameter allows you to redirect all SDK network calls through a custom proxy URL. This feature enables you to route all SDK network requests (settings, tracking, etc.) through your own proxy server, providing better control over network traffic and security.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOInitOptions vwoInitOptions = new VWOInitOptions();

vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setProxyUrl("http://custom.proxy.com");

VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();

wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setProxyUrl("http://custom.proxy.com");

Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Gateway

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.

Why Use a Gateway?

The Gateway Service is required in the following scenarios:

When using pre-segmentation features based on user location or user agent.
For applications requiring advanced targeting capabilities.
It's mandatory when using any thin-client SDK (e.g., Go).

How to Use the Gateway

The gateway can be customized by passing the setGatewayService() parameter in the init configuration.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> gatewayService = new HashMap<>();
gatewayService.put("url", "http://custom.gateway.com");
vwoInitOptions.setGatewayService(gatewayService);
VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> gatewayService = new HashMap<>();
gatewayService.put("url", "http://custom.gateway.com");
wingifyInitOptions.setGatewayService(gatewayService);
Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Refer to the Gateway Documentation for further details.

UserAliasing

User aliasing allows you to create consistent user experiences across different user identifiers. This is particularly useful when users can be identified by multiple IDs (e.g., anonymous ID, authenticated ID, email, etc.) and you want to maintain consistent feature flag decisions across these different identifiers.

Prerequisites

User aliasing requires:

Gateway Service: Must be configured and running. see Gateway section for more details.
Aliasing Enabled: Must be set to true in initialization options

Configuration

To enable user aliasing, you need to configure both the gateway service and the aliasing flag:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOInitOptions vwoInitOptions = new VWOInitOptions();

vwoInitOptions.setSdkKey("sdk-key");
vwoInitOptions.setAccountId(1234);

// set gateway service
Map<String, Object> gatewayService = new HashMap<>();
gatewayService.put("url", "http://custom.gateway.com");
vwoInitOptions.setGatewayService(gatewayService);

// set aliasing flag in vwoInitOptions
vwoInitOptions.setIsAliasingEnabled(true);
VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();

wingifyInitOptions.setSdkKey("sdk-key");
wingifyInitOptions.setAccountId(1234);

// set gateway service
Map<String, Object> gatewayService = new HashMap<>();
gatewayService.put("url", "http://custom.gateway.com");
wingifyInitOptions.setGatewayService(gatewayService);

// set aliasing flag in wingifyInitOptions
wingifyInitOptions.setIsAliasingEnabled(true);
Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Setting User Alias

Use the setAlias() method to create an alias relationship between a user ID and an alias ID:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

// Method 1: Using user ID and alias ID directly
Boolean isAliasSet = vwoInstance.setAlias("user-123", "alias-456");

// Method 2: Using VWOContext and alias ID
VWOContext context = new VWOContext();
context.setId("user-123");
Boolean isAliasSetForContext = vwoInstance.setAlias(context, "alias-456");

Wingify (SDK version >= 1.50.0) — recommended

// Method 1: Using user ID and alias ID directly
Boolean isAliasSet = wingifyInstance.setAlias("user-123", "alias-456");

// Method 2: Using WingifyUserContext and alias ID
WingifyUserContext context = new WingifyUserContext();
context.setId("user-123");
Boolean isAliasSetForContext = wingifyInstance.setAlias(context, "alias-456");

Storage

The SDK operates in a stateless mode by default, meaning each getFlag call triggers a fresh evaluation of the flag against the current user context.

To optimize performance and maintain consistency, you can implement a custom storage mechanism by passing a setStorage() parameter during initialization. This allows you to persist feature flag decisions in your preferred database system (like Redis, MongoDB, or any other data store).

Key benefits of implementing storage:

Improved performance by caching decisions
Consistent user experience across sessions
Reduced load on your application

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.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.packages.storage.Connector;
import java.util.HashMap;
import java.util.Map;

public class StorageTest extends Connector {

    private final Map<String, Map<String, Object>> storage = new HashMap<>();

    @Override
    public void set(Map<String, Object> data) throws Exception {
        String key = data.get("featureKey") + "_" + data.get("userId");

        // Create a map to store the data
        Map<String, Object> value = new HashMap<>();
        value.put("rolloutKey", data.get("rolloutKey"));
        value.put("rolloutId", data.get("rolloutId"));
        value.put("rolloutVariationId", data.get("rolloutVariationId"));
        value.put("experimentKey", data.get("experimentKey"));
        value.put("experimentId", data.get("experimentId"));
        value.put("experimentVariationId", data.get("experimentVariationId"));

        // Store the value in the storage
        storage.put(key, value);
    }

    @Override
    public Object get(String featureKey, String userId) throws Exception {
        String key = featureKey + "_" + userId;

        // Check if the key exists in the storage
        if (storage.containsKey(key)) {
            return storage.get(key);
        }
        return null;
    }
}

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.packages.storage.Connector;
import java.util.HashMap;
import java.util.Map;

public class StorageTest extends Connector {

    private final Map<String, Map<String, Object>> storage = new HashMap<>();

    @Override
    public void set(Map<String, Object> data) throws Exception {
        String key = data.get("featureKey") + "_" + data.get("userId");

        // Create a map to store the data
        Map<String, Object> value = new HashMap<>();
        value.put("rolloutKey", data.get("rolloutKey"));
        value.put("rolloutId", data.get("rolloutId"));
        value.put("rolloutVariationId", data.get("rolloutVariationId"));
        value.put("experimentKey", data.get("experimentKey"));
        value.put("experimentId", data.get("experimentId"));
        value.put("experimentVariationId", data.get("experimentVariationId"));

        // Store the value in the storage
        storage.put(key, value);
    }

    @Override
    public Object get(String featureKey, String userId) throws Exception {
        String key = featureKey + "_" + userId;

        // Check if the key exists in the storage
        if (storage.containsKey(key)) {
            return storage.get(key);
        }
        return null;
    }
}

Logger

VWO by default logs all ERROR level messages to your server console. To gain more control over VWO's logging behaviour, you can use the setLogger() parameter in the init configuration.

Parameter	Description	Required	Type	Default Value
`level`	Log level to control verbosity of logs	Yes	String	`ERROR`
`prefix`	Custom prefix for log messages	No	String	`VWO-SDK` (`WINGIFY-SDK` when initialized via `Wingify`)
`transport`	Custom logger implementation for single transport	No	Map<String, Object>	`null`
`transports`	Custom logger implementation for multiple transports	No	List<Map<String, Object>>	`null`

Example 1: Set log level to control verbosity of logs

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
logger.put("level", "DEBUG");
vwoInitOptions.setLogger(logger);
VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
logger.put("level", "DEBUG");
wingifyInitOptions.setLogger(logger);
Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Example 2: Add custom prefix to log messages for easier identification

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
logger.put("level", "DEBUG");
logger.put("prefix", "CUSTOM LOG PREFIX");
vwoInitOptions.setLogger(logger);
VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
logger.put("level", "DEBUG");
logger.put("prefix", "CUSTOM LOG PREFIX");
wingifyInitOptions.setLogger(logger);
Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Example 3: Implement custom transport to handle logs your way

The transport parameter allows you to implement custom logging behavior by providing your own logging functions. You can define handlers for different log levels (debug, info, warn, error, trace) to process log messages according to your needs.

For example, you could:

Send logs to a third-party logging service
Write logs to a file
Format log messages differently
Filter or transform log messages
Route different log levels to different destinations

The transport object should implement handlers for the log levels you want to customize. Each handler receives the log message as a parameter.

For single transport you can use the transport parameter. For example:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.interfaces.logger.LogTransport;
import com.vwo.packages.logger.enums.LogLevelEnum;

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
LogTransport logTransport = (level, message) -> {
    // your custom logging logic here
};
logger.put("transport", new HashMap<String, Object>() {{
    put("level", LogLevelEnum.DEBUG);
    put("log", logTransport);
}});

vwoInitOptions.setLogger(logger);
VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.interfaces.logger.LogTransport;
import com.wingify.packages.logger.enums.LogLevelEnum;

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
LogTransport logTransport = (level, message) -> {
    // your custom logging logic here
};
logger.put("transport", new HashMap<String, Object>() {{
    put("level", LogLevelEnum.DEBUG);
    put("log", logTransport);
}});

wingifyInitOptions.setLogger(logger);
Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

For multiple transports you can use the transports parameter. For example:

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.interfaces.logger.LogTransport;
import com.vwo.packages.logger.enums.LogLevelEnum;

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setAccountId(123456);
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
List<Map<String, Object>> transports = new ArrayList<>();
LogTransport errorTransport = (level, message) -> {
    // your custom logging logic here
};
LogTransport infoTransport = (level, message) -> {
    // your custom logging logic here
};

transports.add(new HashMap<String, Object>() {{
    put("level", LogLevelEnum.INFO);
    put("log", infoTransport);
}});
transports.add(new HashMap<String, Object>() {{
    put("level", LogLevelEnum.ERROR);
    put("log", errorTransport);
}});
logger.put("transports", transports);

vwoInitOptions.setLogger(logger);
VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.interfaces.logger.LogTransport;
import com.wingify.packages.logger.enums.LogLevelEnum;

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setAccountId(123456);
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");

Map<String, Object> logger = new HashMap<>();
List<Map<String, Object>> transports = new ArrayList<>();
LogTransport errorTransport = (level, message) -> {
    // your custom logging logic here
};
LogTransport infoTransport = (level, message) -> {
    // your custom logging logic here
};

transports.add(new HashMap<String, Object>() {{
    put("level", LogLevelEnum.INFO);
    put("log", infoTransport);
}});
transports.add(new HashMap<String, Object>() {{
    put("level", LogLevelEnum.ERROR);
    put("log", errorTransport);
}});
logger.put("transports", transports);

wingifyInitOptions.setLogger(logger);
Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Integrations

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.

If SDK version less than 1.50.0, use the VWO snippet. If SDK version 1.50.0 or later, we recommend switching to the Wingify snippet

VWO (SDK version < 1.50.0)

import com.vwo.interfaces.integration.IntegrationCallback;

IntegrationCallback integrations = properties -> {
    // your function definition
};

VWOInitOptions vwoInitOptions = new VWOInitOptions();
vwoInitOptions.setSdkKey("32-alpha-numeric-sdk-key");
vwoInitOptions.setAccountId(12345);
vwoInitOptions.setIntegrations(integrations);

VWO vwoInstance = VWO.init(vwoInitOptions);

Wingify (SDK version >= 1.50.0) — recommended

import com.wingify.interfaces.integration.IntegrationCallback;

IntegrationCallback integrations = properties -> {
    // your function definition
};

WingifyInitOptions wingifyInitOptions = new WingifyInitOptions();
wingifyInitOptions.setSdkKey("32-alpha-numeric-sdk-key");
wingifyInitOptions.setAccountId(12345);
wingifyInitOptions.setIntegrations(integrations);

Wingify wingifyInstance = Wingify.init(wingifyInitOptions);

Refer to the Integrations documentation for more information.

Version History

The version history tracks changes, improvements, and bug fixes in each version. For a full history, see the CHANGELOG.md.

Contributing

We welcome contributions to improve this SDK! Please read our contributing guidelines before submitting a PR.

Code of Conduct

Our Code of Conduct outlines expectations for all contributors and maintainers.

License

Apache License, Version 2.0

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
git-hooks		git-hooks
scripts		scripts
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
pom.xml		pom.xml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

VWO Feature Management and Experimentation SDK for Java

Overview

Requirements

Installation

Basic Usage Example

UUID Generation

Advanced Configuration Options

User Context

Parameters Table

Example

Web testing pre-segmentation

Session Management

Automatic Session ID Generation

Session ID Access

Example Usage

Basic Feature Flagging

Custom Event Tracking

Pushing Attributes

Polling Interval Adjustment

Proxy

Gateway

Why Use a Gateway?

How to Use the Gateway

UserAliasing

Prerequisites

Configuration

Setting User Alias

Storage

Logger

Example 1: Set log level to control verbosity of logs

Example 2: Add custom prefix to log messages for easier identification

Example 3: Implement custom transport to handle logs your way

Integrations

Version History

Contributing

Code of Conduct

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages