feat: custom bucketing seed

Author: Kaustubh22327

CHANGELOG.md

@@ -5,7 +5,40 @@ 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.19.0] - 2025-02-18
+## [1.20.0] - 2026-03-03
+
+### Added
+
+- Added support for custom bucketing seed on the `VWOContext` so that bucketing can be driven by a caller-provided seed instead of the raw `userId`, with automatic fallback to `userId` when the seed is not set.
+
+  Example usage:
+
+  ```java
+  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);
+
+  // Use custom bucketing seed so different userIds can share bucketing
+  VWOContext context = new VWOContext();
+  context.setId("user-123");
+  context.setBucketingSeed("shared-seed-1");
+
+  GetFlag flag = vwoClient.getFlag("feature-key", context);
+
+  // If bucketingSeed is invalid (non-string, empty or whitespace-only),
+  // the SDK logs INVALID_PARAM for bucketingSeed and falls back to userId.
+  ```
+
+## [1.19.0] - 2026-02-18
 ### 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.
@@ -90,7 +123,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   VWO instance = VWO.init(vwoInitOptions);
   ```
 
-## [1.17.0] - 2025-01-19
+## [1.17.0] - 2026-01-19
 
 ### Added
 

pom.xml

@@ -19,7 +19,7 @@ limitations under the License. -->
 
     <groupId>com.vwo.sdk</groupId>
     <artifactId>vwo-fme-java-sdk</artifactId>
-    <version>1.19.0</version>
+    <version>1.20.0</version>
     <packaging>jar</packaging>
 
     <name>VWO FME Java SDK</name>

src/main/java/com/vwo/VWOClient.java

@@ -123,6 +123,15 @@ public GetFlag getFlag(String featureKey, VWOContext context) {
             if (context == null || context.getId() == null || context.getId().isEmpty()) {
                 throw new IllegalArgumentException("User ID is required");
             }
+
+            if (!DataTypeUtil.isNull(context.getBucketingSeed())) {
+                if (!DataTypeUtil.isString(context.getBucketingSeed())
+                        || context.getBucketingSeed().trim().isEmpty()) {
+                    vwoBuilder.getLoggerService().log(LogLevelEnum.ERROR, "INVALID_BUCKETING_SEED", new HashMap<String, Object>() {{
+                    }});
+                    context.setBucketingSeed(null);
+                }
+            }
             // get UUID from context
             uuid = this.getUUIDFromContext(context, apiName);
 
@@ -141,6 +150,8 @@ public GetFlag getFlag(String featureKey, VWOContext context) {
             if (this.options.getIsAliasingEnabled()) {
                 context.setId(UserIdUtil.getUserId(context.getId(), serviceContainer));
                 serviceContainer.setUuid(context.getId(), true);
+                // regenerate uuid with the resolved userId (handles case where aliasing changed the userId)
+                uuid = this.getUUIDFromContext(context, apiName);
             }
             serviceContainer.setUuid(uuid, false);
 

src/main/java/com/vwo/api/GetFlagAPI.java

@@ -181,7 +181,7 @@ public static GetFlag getFlag(String featureKey, VWOContext context, ServiceCont
             // Evaluate the passed rollout rule traffic and get the variation
             if (!rolloutRulesToEvaluate.isEmpty()) {
                 Campaign passedRolloutCampaign = rolloutRulesToEvaluate.get(0);
-                Variation variation = evaluateTrafficAndGetVariation(serviceContainer, passedRolloutCampaign, context.getId());
+                Variation variation = evaluateTrafficAndGetVariation(serviceContainer, passedRolloutCampaign, context);
                 if (variation != null) {
                     isFlagEnabled = true;
                     variablesToReturn = variation.getVariables();
@@ -256,7 +256,7 @@ public static GetFlag getFlag(String featureKey, VWOContext context, ServiceCont
             // Evaluate the passed experiment rule traffic and get the variation
             if (!experimentRulesToEvaluate.isEmpty()) {
                 Campaign campaign = experimentRulesToEvaluate.get(0);
-                Variation variation = evaluateTrafficAndGetVariation(serviceContainer, campaign, context.getId());
+                Variation variation = evaluateTrafficAndGetVariation(serviceContainer, campaign, context);
                 if (variation != null) {
                     isFlagEnabled = true;
                     variablesToReturn = variation.getVariables();

src/main/java/com/vwo/constants/Constants.java

@@ -32,7 +32,7 @@ public class Constants {
   public static final int DEFAULT_REQUEST_TIME_INTERVAL = 600; // 10 * 60(secs) = 600 secs i.e. 10 minutes
   public static final int DEFAULT_EVENTS_PER_REQUEST = 100;
   public static final String SDK_NAME = "vwo-fme-java-sdk";
-  public static final String SDK_VERSION = "1.19.0";
+  public static final String SDK_VERSION = "1.20.0";
   public static final long SETTINGS_EXPIRY = 10000000;
   public static final long SETTINGS_TIMEOUT = 50000;
 

src/main/java/com/vwo/models/user/VWOContext.java

@@ -27,6 +27,7 @@ public class VWOContext {
     private long sessionId = generateSessionId();
     private Boolean useIdForWeb = false;
     private Map<String, ?> customVariables = new HashMap<>();
+    private String bucketingSeed;
 
     private Map<String, ?> variationTargetingVariables = new HashMap<>();
 
@@ -95,4 +96,12 @@ public Boolean isUseIdForWeb() {
     public void setUseIdForWeb(Boolean useIdForWeb) {
         this.useIdForWeb = useIdForWeb;
     }
+
+    public String getBucketingSeed() {
+        return bucketingSeed;
+    }
+
+    public void setBucketingSeed(String bucketingSeed) {
+        this.bucketingSeed = bucketingSeed;
+    }
 }

src/main/java/com/vwo/services/CampaignDecisionService.java

@@ -27,18 +27,22 @@
 
 import java.util.*;
 
+import static com.vwo.utils.CampaignUtil.getBucketingId;
+import static com.vwo.utils.CampaignUtil.getUserIdForLogging;
+
 public class CampaignDecisionService {
 
     /**
      * This method is used to check if the user is part of the campaign.
-     * @param userId  User ID for which the check is to be performed.
+     * @param context  VWOContext object containing the user context.
      * @param campaign CampaignModel object containing the campaign settings.
      * @return  boolean value indicating if the user is part of the campaign.
      */
-    public boolean isUserPartOfCampaign(String userId, Campaign campaign, ServiceContainer serviceContainer) {
-        if (campaign == null || userId == null) {
+    public boolean isUserPartOfCampaign(VWOContext context, Campaign campaign, ServiceContainer serviceContainer) {
+        if (campaign == null || context == null || context.getId()==null) {
             return false;
         }
+        String bucketingId = getBucketingId(context);
         double trafficAllocation;
         // Check if the campaign is of type ROLLOUT or PERSONALIZE
         // If yes, set the traffic allocation to the weight of the first variation
@@ -52,14 +56,14 @@ public boolean isUserPartOfCampaign(String userId, Campaign campaign, ServiceCon
 
         // Generate bucket key using salt if available, otherwise use campaign ID
         String bucketKey = (salt != null && !salt.isEmpty()) ? 
-                          salt + "_" + userId : 
-                          campaign.getId() + "_" + userId;
+                          salt + "_" + bucketingId : 
+                          campaign.getId() + "_" + bucketingId;
 
         int valueAssignedToUser = new DecisionMaker().getBucketValueForUser(bucketKey);
         boolean isUserPart = valueAssignedToUser != 0 && valueAssignedToUser <= trafficAllocation;
 
         serviceContainer.getLoggerService().log(LogLevelEnum.INFO, "USER_PART_OF_CAMPAIGN", new HashMap<String, Object>() {{
-            put("userId", userId);
+            put("userId", getUserIdForLogging(context));
             put("notPart", isUserPart? "" : "not");
             put("campaignKey", campaign.getType().equals(CampaignTypeEnum.AB.getValue()) ? campaign.getKey() : campaign.getName() + "_" + campaign.getRuleKey());
         }});
@@ -96,15 +100,16 @@ public Variation checkInRange(Variation variation, int bucketValue) {
 
     /**
      * This method is used to bucket the user to a variation based on the bucket value.
-     * @param userId  User ID for which the bucketing is to be performed.
+     * @param context  VWOContext object containing the user context.
      * @param accountId  Account ID for which the bucketing is to be performed.
      * @param campaign  CampaignModel object containing the campaign settings.
      * @return  VariationModel object containing the variation allotted to the user.
      */
-    public Variation bucketUserToVariation(String userId, String accountId, Campaign campaign, ServiceContainer serviceContainer) {
-        if (campaign == null || userId == null) {
+    public Variation bucketUserToVariation(VWOContext context, String accountId, Campaign campaign, ServiceContainer serviceContainer) {
+        if (campaign == null || context == null || context.getId()==null) {
             return null;
         }
+        String bucketingId = getBucketingId(context);
 
         int multiplier = campaign.getPercentTraffic() != 0 ? 1 : 0;
         int percentTraffic = campaign.getPercentTraffic();
@@ -113,15 +118,15 @@ public Variation bucketUserToVariation(String userId, String accountId, Campaign
         String bucketKey;
         // if salt is not null and not empty, use salt else use campaign id
         if (salt != null && !salt.isEmpty()) {
-            bucketKey = salt + "_" + accountId + "_" + userId;
+            bucketKey = salt + "_" + accountId + "_" + bucketingId;
         } else {
-            bucketKey = campaign.getId() + "_" + accountId + "_" + userId;
+            bucketKey = campaign.getId() + "_" + accountId + "_" + bucketingId;
         }
         long hashValue = new DecisionMaker().generateHashValue(bucketKey);
         int bucketValue = new DecisionMaker().generateBucketValue(hashValue, Constants.MAX_TRAFFIC_VALUE, multiplier);
 
         serviceContainer.getLoggerService().log(LogLevelEnum.DEBUG, "USER_BUCKET_TO_VARIATION", new HashMap<String, Object>() {{
-            put("userId", userId);
+            put("userId", getUserIdForLogging(context));
             put("campaignKey", campaign.getRuleKey());
             put("percentTraffic", String.valueOf(percentTraffic));
             put("bucketValue", String.valueOf(bucketValue));
@@ -168,17 +173,17 @@ public boolean getPreSegmentationDecision(Campaign campaign, VWOContext context,
 
     /**
      * This method is used to get the variation allotted to the user in the campaign.
-     * @param userId  User ID for which the variation is to be allotted.
+     * @param context  VWOContext containing the user context.
      * @param accountId  Account ID for which the variation is to be allotted.
      * @param campaign  CampaignModel object containing the campaign settings.
      * @return  VariationModel object containing the variation allotted to the user.
      */
-    public Variation getVariationAllotted(String userId, String accountId, Campaign campaign, ServiceContainer serviceContainer) {
-        boolean isUserPart = isUserPartOfCampaign(userId, campaign, serviceContainer);
+    public Variation getVariationAllotted(VWOContext context, String accountId, Campaign campaign, ServiceContainer serviceContainer) {
+        boolean isUserPart = isUserPartOfCampaign(context, campaign, serviceContainer);
         if (Objects.equals(campaign.getType(), CampaignTypeEnum.ROLLOUT.getValue()) || Objects.equals(campaign.getType(), CampaignTypeEnum.PERSONALIZE.getValue())) {
             return isUserPart ? campaign.getVariations().get(0) : null;
         } else {
-            return isUserPart ? bucketUserToVariation(userId, accountId, campaign, serviceContainer) : null;
+            return isUserPart ? bucketUserToVariation(context, accountId, campaign, serviceContainer) : null;
         }
     }
 }

src/main/java/com/vwo/utils/CampaignUtil.java

@@ -18,6 +18,7 @@
 import com.vwo.constants.Constants;
 import com.vwo.enums.CampaignTypeEnum;
 import com.vwo.models.*;
+import com.vwo.models.user.VWOContext;
 import com.vwo.packages.logger.enums.LogLevelEnum;
 import com.vwo.services.LoggerService;
 
@@ -403,4 +404,39 @@ public static String getCampaignTypeFromCampaignId(Settings settings, int campai
                 .findFirst()
                 .orElse("");
     }
+
+    /**
+     * Returns the bucketing ID for a user based on the custom bucketing seed configuration.
+     * @param context A VWOContext object containing user information.
+     * @return The identifier to be used for bucketing (either the CustomBucketingSeed or the UserID).
+     */
+    public static String getBucketingId(VWOContext context) {
+        if (context == null || context.getId()==null) {
+            return "";
+        }
+        String userId = context.getId();
+        String bucketingSeed = context.getBucketingSeed();
+
+        // Simple logic: if bucketingSeed is provided and not empty, use it; otherwise fallback to userId
+        if (bucketingSeed != null && !bucketingSeed.isEmpty()) {
+            return bucketingSeed;
+        }
+
+        return userId;
+    }
+
+    /**
+     * Returns the formatted user ID for logging purposes.
+     * If a custom bucketing seed is used, it appends the seed to the user ID.
+     * @param context A VWOContext object containing user information.
+     * @return The formatted user ID string.
+     */
+    public static String getUserIdForLogging(VWOContext context) {
+        String userId = context.getId();
+        String bucketingId = getBucketingId(context);
+        if (!bucketingId.equals(userId)) {
+            return userId + " (Seed: " + bucketingId + ")";
+        }
+        return userId;
+    }
 }

src/main/java/com/vwo/utils/DecisionUtil.java

@@ -82,7 +82,7 @@ public static Map<String, Object> checkWhitelistingAndPreSeg(
                 }
             } else {
                 serviceContainer.getLoggerService().log(LogLevelEnum.INFO, "WHITELISTING_SKIP", new HashMap<String, Object>() {{
-                    put("userId", context.getId());
+                    put("userId", getUserIdForLogging(context));
                     put("campaignKey", campaign.getRuleKey());
                 }});
             }
@@ -252,27 +252,27 @@ public static Map<String, Object> checkWhitelistingAndPreSeg(
      * This method is used to evaluate the traffic for a given campaign and get the variation.
      * @param serviceContainer  ServiceContainer object containing the service container.
      * @param campaign  CampaignModel object containing the campaign settings.
-     * @param userId   String containing the user ID.
+     * @param context   VWOContext object containing user information.
      * @return  VariationModel object containing the variation details.
      */
     public static Variation evaluateTrafficAndGetVariation(
             ServiceContainer serviceContainer,
             Campaign campaign,
-            String userId) {
+            VWOContext context) {
 
         // Get the variation allotted to the user
-        Variation variation = new CampaignDecisionService().getVariationAllotted(userId, serviceContainer.getVWOInitOptions().getAccountId().toString(), campaign, serviceContainer);
+        Variation variation = new CampaignDecisionService().getVariationAllotted(context, serviceContainer.getVWOInitOptions().getAccountId().toString(), campaign, serviceContainer);
         if (variation == null) {
             serviceContainer.getLoggerService().log(LogLevelEnum.INFO, "USER_CAMPAIGN_BUCKET_INFO", new HashMap<String, Object>() {{
-                put("userId", userId);
+                put("userId", getUserIdForLogging(context));
                 put("campaignKey", campaign.getType().equals(CampaignTypeEnum.AB.getValue()) ? campaign.getKey() : campaign.getName() + "_" + campaign.getRuleKey());
                 put("status", "did not get any variation");
             }});
             return null;
         }
 
         serviceContainer.getLoggerService().log(LogLevelEnum.INFO, "USER_CAMPAIGN_BUCKET_INFO", new HashMap<String, Object>() {{
-            put("userId", userId);
+            put("userId", getUserIdForLogging(context));
             put("campaignKey", campaign.getType().equals(CampaignTypeEnum.AB.getValue()) ? campaign.getKey() : campaign.getName() + "_" + campaign.getRuleKey());
             put("status", "got variation: " + variation.getName());
         }});
@@ -290,7 +290,7 @@ private static Map<String, Object> checkCampaignWhitelisting(Campaign campaign,
         StatusEnum status = whitelistingResult != null ? StatusEnum.PASSED : StatusEnum.FAILED;
         String variationString = whitelistingResult != null ? (String) whitelistingResult.get("variationName") : "";
         serviceContainer.getLoggerService().log(LogLevelEnum.INFO, "WHITELISTING_STATUS", new HashMap<String, Object>() {{
-            put("userId", context.getId());
+            put("userId", getUserIdForLogging(context));
             put("campaignKey", campaign.getType().equals(CampaignTypeEnum.AB.getValue()) ? campaign.getKey() : campaign.getName() + "_" + campaign.getRuleKey());
             put("status", status.getStatus());
             put("variationString", variationString);
@@ -310,7 +310,7 @@ private static Map<String, Object> evaluateWhitelisting(Campaign campaign, VWOCo
         for (Variation variation : campaign.getVariations()) {
             if (variation.getSegments() != null && variation.getSegments().isEmpty()) {
                 serviceContainer.getLoggerService().log(LogLevelEnum.INFO, "WHITELISTING_SKIP", new HashMap<String, Object>() {{
-                    put("userId", context.getId());
+                    put("userId", getUserIdForLogging(context));
                     put("campaignKey", campaign.getType().equals(CampaignTypeEnum.AB.getValue()) ? campaign.getKey() : campaign.getName() + "_" + campaign.getRuleKey());
                     put("variation", !variation.getName().isEmpty() ? "for variation: " + variation.getName() : "");
                 }});
@@ -337,7 +337,7 @@ private static Map<String, Object> evaluateWhitelisting(Campaign campaign, VWOCo
                 stepFactor = assignRangeValues(variation, currentAllocation);
                 currentAllocation += stepFactor;
             }
-            whitelistedVariation = new CampaignDecisionService().getVariation(targetedVariations, new DecisionMaker().calculateBucketValue(getBucketingSeed(context.getId(), campaign, null)));
+            whitelistedVariation = new CampaignDecisionService().getVariation(targetedVariations, new DecisionMaker().calculateBucketValue(getBucketingSeed(getBucketingId(context), campaign, null)));
         } else if (targetedVariations.size() == 1) {
             whitelistedVariation = targetedVariations.get(0);
         }