Bucketing

📘

Bucketing and Bucket allocation are not the same feature

• Bucketing is related to our SDKs and their usage in "Local mode"
• Bucket allocation is a feature related to tests, here is the documentation about it

What is Bucketing?

Bucketing is a method for assigning application users to variations that replaces Decision API calls with a one-time call to the bucketing file for an environment to execute the variation assignment logic in the SDK itself. It optimizes the workflow and user ability to receive the information more efficiently.

How does bucketing work?

When a user navigates through an application, they do so via the user interface. Flagship allows applications to customize their behavior based on the context data of individual users in order to test different variations, personalize an experience, display or hide features based on business logic, or to roll out new features progressively. Using the standard connection mode in Flagship, applications must make a call to the Decision API for each user so that Flagship can return the relevant flag information to display.

By default, each Decision API call returns all the campaigns and flag details associated with a particular user. Bucketing, on the other hand, decouples the flag retrieval from the variation assignment for a smoother user experience.

When a user enters an application with bucketing enabled, the SDK will contact the CDN to retrieve the latest bucketing file, which contains all flag information for a specified environmentID, and store it in cache (memory or local). The MurmurHash algorithm is then used by the SDK to compute variation assignment. The remaining Decision API calls for event tracking and campaign activation are asynchronous, allowing the application to work smoothly without the need for a persistent internet connection.

CDN Configuration

The AWS-hosted CDN provides a bucketing file with all the flag details for the specified environmentID, meaning it does not need to be saved separately for each visitor instance. The SDK will attempt to connect to the closest CDN endpoint to retrieve the bucketing file to ensure the fastest response time regardless of physical location or network connectivity.

At the start, the SDK should make a call to the CDN and store the result in cache (memory or local) for the specified environmentID. The following is a list of the possible CDN response codes and what they mean:

• 200: Success
• 304: Not modified
• 404: Not found
• 500: Server error, try again

The CDN will reply with a 200 code when first called, along with a header containing the datetime value of the last modification. When polling the server to get subsequent modifications on the CDN, the SDK should send the last modification datetime value in the request header. If the content has not been modified since the CDN will reply with a 304 code.

Targeting and Variation Assignment

Targeting refers to the process of determining the audience for specific modifications through the use of AND and OR statements against which the user context is evaluated. When reviewing your campaign configurations, you should make sure that your campaign scenarios in Flagship are targeting the appropriate users.

For each campaign where the user context matches at least one scenario, the SDK then projects the user’s visitorID onto a 0-99 integer spectrum using the MurmurHash algorithm to compute a variation assignment according to the traffic allocation for the campaign.

For example, if you have 3 variations:

• Variation 1: 30% traffic
• Variation 2: 50% traffic
• Variation 3: 20% traffic

If the MurmurHash-computed integer falls is between 0 > 30, the user will be assigned to Variation 1. If the integer falls is between 30 > 80, the user will be assigned to Variation 2. If the computed integer is between 80 > 100, the user will be assigned to Variation 3.

Given that the MurmurHash algorithm always returns the same hash for a specific visitorID, variation assignments for a specific user will remain consistent across platforms as long as they use the same visitorID.

Variation: Within the context of a feature flag campaign, the customized behavior of a client app is computed from the user context and campaign configuration in Flagship.

What are the pros and cons of bucketing?

🚧

Bucketing limitation

Unlike the Cloud hosted API, the bucketing mode requires a cache system to save your visitors assignments for features like Progressive rollout and Dynamic allocation.

We provide a cache system in the v3 of the following SDKs:

• JS SDK
• React SDK
• React Native SDK
• iOS SDK
• Android SDK
• JAVA SDK
• PHP SDK

If your SDK is not in the list and you want more informations, feel free to Contact us!