Implement a user profile service

This topic describes how to use the default or how to set up a custom User Profile Service for the Optimizely React SDK.

Suggest Edits

Use a User Profile Service to persist information about your users and ensure variation assignments are sticky. Sticky implies that once a user gets a particular variation, their assignment won't change.

In the React SDK, there is no default implementation. Implementing a User Profile Service is optional and is only necessary if you want to keep variation assignments sticky even when experiment conditions are changed while it is running (for example, audiences, attributes, variation pausing, and traffic distribution). Otherwise, the React SDK is stateless and relies on deterministic bucketing to return consistent assignments.

If the User Profile Service doesn't bucket a user as you expect, then check whether other features are overriding the bucketing. For more information, see How bucketing works.

Implement a service

Refer to the code samples below to provide your own User Profile Service. It should expose two functions with the following signatures:

lookup: Takes a user ID string and returns a user profile matching the schema below.
save: Takes a user profile and persists it.

If you want to use the User Profile Service purely for tracking purposes and not sticky bucketing, you can implement only the save method (always return nil from lookup).

import { createInstance } from '@optimizely/react-sdk';

// Sample user profile service implementation
const userProfileService = {
  lookup: userId => {
    // Perform user profile lookup
  },
  save: userProfileMap => {
    // Persist user profile
  },
};

const optimizelyClient = createInstance({
  datafile: window.datafile, // assuming you have a datafile at window.datafile
  userProfileService, // Passing your userProfileService created above
});

The code example below shows the JSON schema for the user profile object.

Use experiment_bucket_map to override the default bucketing behavior and define an alternate experiment variation for a given user. For each experiment that you want to override, add an object to the map. Use the experiment ID as the key and include a variation_id property that specifies the desired variation. If there isn't an entry for an experiment, then the default bucketing behavior persists.

In the example below, ^[a-zA-Z0-9]+$ is the experiment ID.

{
  "title": "UserProfile",
  "type": "object",
  "properties": {
    "user_id": {"type": "string"},
    "experiment_bucket_map": {"type": "object",
                              "patternProperties": {
                                 "^[a-zA-Z0-9]+$": {"type": "object",
                                                    "properties": {"variation_id": {"type":"string"}},
                                                    "required": ["variation_id"]}
                               }
                             }
  },
  "required": ["user_id", "experiment_bucket_map"]
}

The React SDK uses the User Profile Service you provide to override Optimizely's default bucketing behavior in cases when an experiment assignment has been saved.

When implementing your own User Profile Service, we recommend loading the user profiles into the User Profile Service on initialization and avoiding performing expensive, blocking lookups on the lookup function to minimize the performance impact of incorporating the service.

Implement asynchronous user lookups with experiment bucket map attribute

You can implement attributes.$opt_experiment_bucket_map to perform asynchronous lookups of users' previous variations. The SDK handles attributes.$opt_experiment_bucket_map the same way it would userProfileService.lookup, and this allows you to do an asynchronous lookup of the experiment bucket map before passing it to the Activate method.

📘
Note
attributes.$opt_experiment_bucket_map will always take precedence over an implemented userProfileService.lookup.

The example below shows how to implement consistent bucketing via attributes.

import React from 'react';
import {
  createInstance,
  OptimizelyProvider,
} from '@optimizely/react-sdk'

const optimizelyClient = createInstance({
  datafile: window.datafile, // assuming you have a datafile at window.datafile
});

// In practice, this could come from a DB call
const experimentBucketMap = {
  123: { // ID of experiment
    variation_id: '456', // ID of variation to force for this experiment
  }
}

const user = {
  id: ‘myuser123’,
  attributes: {
    // By passing this $opt_experiment_bucket_map, we force that the user
    // will always get bucketed into variationid='456' for experiment id='123'
    '$opt_experiment_bucket_map': experimentBucketMap,
  },
};

function App() {
  return (
    <OptimizelyProvider
      optimizely={optimizely}
      user={user}
    >
    {/* … your application components here … */}
    </OptimizelyProvider>
  </App>
}

You can use the asynchronous service example below to try this functionality in a test environment. If you implement this example in a production environment, be sure to modify UserProfileDB to a real database.

import React from 'react';
import {
  createInstance,
  OptimizelyProvider,
} from '@optimizely/react-sdk'

// This is here only as an example; in a production environment this could access a real datastore
class UserProfileDB {
  constructor() {
    /* Example structure
     * {
     *   user1: {
     *     user_id: 'user1',
     *     experiment_bucket_map: {
     *       '12095834311': { // experimentId
     *         variation_id: '12117244349' // variationId
     *       }
     *     }
     *   }
     * }
     */
    this.db = {}
  }

  save(user_id, experiment_bucket_map) {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        this.db[user_id] = { user_id, experiment_bucket_map }
        resolve()
      }, 50)
    })
  }

  lookup(userId) {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        let result
        if (this.db[userId] && this.db[userId].experiment_bucket_map) {
          result = this.db[userId].experiment_bucket_map
        }
        resolve(result)
      }, 50)
    })
  }
}

const userDb = new UserProfileDB()

const userProfileService = {
  lookup(userId) {
    // In our case we will not implement this function here. We will look up the attributes for the user below.
  },
  save(userProfileMap) {
    const { user_id, experiment_bucket_map } = userProfileMap
    userDb.save(user_id, experiment_bucket_map)
  }
}

const client = createInstance({
  datafile: window.datafile, // assuming you have a datafile at window.datafile
  userProfileService,
})

// React SDK supports passing a Promise as user, for async user lookups like this
const user = userDb.lookup(userId).then((experimentBucketMap = {}) => {
  return {
    id: 'user1',
    attributes: {
      $opt_experiment_bucket_map: experimentBucketMap
    },
  }
})

// The provider will use the given user and optimizely instance.
// The provided experiment bucket map will force any specified variation
// assignments from userDb.
// The provided user profile service will save any new variation assignments to
//userDb.
function App() {
  return (
    <OptimizelyProvider
      optimizely={optimizely}
      user={user}
    >
    {/* … your application components here … */}
    </OptimizelyProvider>
  </App>
}

Updated about 1 year ago

Implement a service

Implement asynchronous user lookups with experiment bucket map attribute

📘Note

📘
Note