Skip to content

Instantly share code, notes, and snippets.

@durw4rd
Last active September 26, 2024 15:40
Show Gist options
  • Save durw4rd/f38d76cebd5deb7ad091df23bc1b2adf to your computer and use it in GitHub Desktop.
Save durw4rd/f38d76cebd5deb7ad091df23bc1b2adf to your computer and use it in GitHub Desktop.
Integration Guide: Send LaunchDarkly experiment evaluation details to ContentSquare

Integration Guide: Send LaunchDarkly experiment evaluation details to Contentsquare


NOTE

This is not an officially supported integration. Feel free to use the code as is or make modifications to it according to your needs but note that if you need help with any potential modifications to the integration, this would need to be through a paid engagement with LaunchDarkly's Professional Services team. The (free) Technical Support team won't be able to help you.

Contact your Account Executive or Customer Success Manager if you’d like to learn more about our PS offerings.


Overview

This guide provides detailed instructions for mutual customers of LaunchDarkly and Contentsquare to set up or update their implementation to utilize the integration between the two platforms. The integration leverages the 'flag-used' inspector interface from the LaunchDarkly JavaScript SDK and calls a method on the ContentSquare-owned object CS_CONF.integrations_handler.launchdarkly(). This function will pass three attributes: flag key, served flag variation, and the evaluation context that was used for the evaluation.

Prerequisites

  1. LaunchDarkly Account: Ensure you have an active LaunchDarkly account and access to the project where you want to implement the integration.
  2. A compatible LaunchDarkly SDK installed in your application: This integration only work with LaunchDarkly JavaScript-based SDKs supporting the inspectors interface.
  3. Contentsquare Account: Ensure you have an active ContentSquare account with the necessary permissions to configure integrations.

Step-by-Step Integration

Step 1: Enable the integration in Contentsquare dashboard

Go to the section How to request an integration to see the instructions to enable this integration. You can then return here once completed.

If you have already completed the step above then continue below.

Step 2: Implement the Integration Function

Create a function to send flag evaluation data to Contentsquare. This function will be called by the LaunchDarkly SDK every time it evaluates a feature flag. The function checks 1) if the flag evaluation is part of an active LD experiment, 2) if the Contentsquare integration object is available on page, and 3) passes it the flag evaluation data.

const sendCSAnalyticsEvent = (flagKey, flagDetail, context) => {
  const { value, variationIndex, reason } = flagDetail;
  const { kind, key, name } = context;
  
  // Making sure the flag is part of an experiment by checking the value of `flagDetail > reason > inExperiment` is `true`
  if (!!reason && !!reason.inExperiment) {
    /**
       * Calls the ContentSquare integration handler with the flag evaluation data.
       *
       * Arguments:
       * flagKey (string): The key of the evaluated flag.
       * value (any): The value of the served flag variation.
       * context (object): The evaluation context used for the flag evaluation, containing properties:
       *    - kind (string): The kind of context (e.g., "user", "organization").
       *    - key (string): The unique key for the context (e.g., user ID).
       *    - name (string): The name associated with the context (e.g., user name).
       */
    function callCShandler() {
      CS_CONF.integrations_handler.launchdarkly(flagKey, value, context);
    }

    if (
      window.CS_CONF &&
      window.CS_CONF.integrations_handler &&
      window.CS_CONF.integrations_handler.launchdarkly
    ) {
      callCShandler();
    } else {
      window.addEventListener("Contentsquare_LD_Integration_Launch", () => {
        callCShandler();
      });
    }
  }
};

Note

The above code sends the relevant experiment evaluation data to a Contentsquare integrations handler function. If this function is available at the time when The LD SDK dispatches the event, it will extract the flag and variation info and pass it to Contensquare. If the function is not yet loaded, the handler will register a listener to dispatch the information whenever the integrations handler function is loaded.

[...]
// Integrations handler function is loaded
const campaignName = flagKey;
const variationName = value;

dispatch(campaignName, variationName);
[...]

// Integrations handler function not loaded yet
const evt = new window.CustomEvent("Contentsquare_LD_Integration_Launch");
window.dispatchEvent(evt);

Step 3: Configure LaunchDarkly Client

Define/update the LaunchDarkly client configuration options by including the inspector that will trigger the integration function.

The 'inspectors' argument inside the config object accepts an array of objects which allow you to set up listeners for the selected SDK operations. Each object defines a single event listener and accepts the following arguments:

  • type (string): Refers to a specific SDK operation that should be observer
  • name (string): Identifies the inspector instance
  • method (function): A method that is called when the SDK evaluates a feature flag as a result of calling the variation method. You can provide an in-line function or call a function defined elsewhere.
const ldConfigOptions = {
  // Any other/existing configuration options
  inspectors: [
    {
      type: 'flag-used',
      name: 'Contentsquare-analytics-integration',
      method: sendCSAnalyticsEvent
    }
  ]
};

// Example initialization of the LaunchDarkly client
const client = LDClient.initialize('YOUR_CLIENT_SIDE_ID', ldContext, ldConfigOptions);

client.on('ready', () => {
  console.log('LaunchDarkly client is ready');
});

Step 4: Verify the Integration

  1. Deploy the Code: Ensure your integration code is deployed to your web application.
  2. Test the Integration: Trigger a flag evaluation in your application and check if the data is being sent to Contentsquare using the 'Contentsquare Tracking Setup Assistant' browser extension
  3. Contentsquare Handler: Ensure the Contentsquare handler is correctly invoked and the integration works as expected.

Troubleshooting

  • Make sure the LD flag you are evaluating has an experiment rule attached to it and the evaluation context is part of the experiment.
  • Check Console Logs: Update the sendCSAnalyticsEvent function by adding console logs for messages indicating the flag evaluation details and any errors.
  • Event Listener: Ensure the event listener Contentsquare_LD_Integration_Launch is correctly set up and triggered.
  • Network Requests: Verify that network requests to Contentsquare are successfully sent and received.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment