Using Edge Config with Split

Learn how to use Edge Config with Vercel's Split integration.
Table of Contents

The Split Edge Config integration is available in Beta on all plans

Split is a feature flag provider that tracks event data, enabling you to release features, target them to audiences, and measure their impact on customer experience metrics securely.

The Split Edge Config integration enables you to write your Split rollout plan to an Edge Config. Doing so will allow you to evaluate feature flags at ultra-low latency with Vercel's Edge Network while tracking events and impressions data with Split.

Before using this integration, you should have:

  1. The latest version of Vercel CLI. To check your version, use vercel --version. To install or update Vercel CLI, use:

    pnpm
    yarn
    npm
    pnpm i -g vercel@latest

  2. A project. If you don't have one, you can run the following terminal commands to create a Next project:

    pnpm
    yarn
    npm
    pnpm i next
    terminal
    npx create-next-app@latest
  3. A Vercel project. If you don't have one, see Creating a Project

  4. An Edge Config. If you don't have one, follow the Edge Config quickstart

  5. The Edge Config SDK:

    pnpm
    yarn
    npm
    pnpm i @vercel/edge-config

The following steps will walk you through:

  • Configuring Vercel's Split Edge Config integration
  • Using it to evalute feature flags from your frontend code

To configure this integration, Split Admin access (Split Admin users can add feature flags and segments, and edit them at will) is required.

  1. Set up the Split integration

    Visit the Split page in the Vercel Integration Marketplace and select the Add Integration button. From the Integration dialog:

    1. Select a Vercel team and project to connect the integration to
    2. Log into Split
    3. Select the Split Environment you want to use
    4. Select an existing Edge Config or create a new one
    5. Copy the Edge Config item key provided on this page. You'll need it to add it to your Environment Variables

    You can also find your Edge Config Split item key in your dashboard on Vercel . In the Integrations tab, select Manage, then select Configure on the integration page. You should see the item key on the page that opens.

  2. Create your feature flags

    If you already have existing feature flags, you can skip this step and use those. In this example, we'll create one called New_Marketing_Page. You can set the user targeting to Joe and Bobby.

    To create a feature flag in Split:

    1. Log into your Split management console and select the workspace icon near the top-left of the page
    2. In the sidebar, under Target, select Feature flags. Add the name New_Marketing_Page, and set the traffic type to user. Select Create to finish
    3. With your feature flag created, select the feature flag and select the Definition tab. Select Initiate Environment to configure your flag
    4. Add valid users to the feature flag
    5. Scroll down to Targeting and select Add new individual target
    6. Under To user, add any username you want to test. This example uses Joe.
    7. Select Add new individual target, then set the Description option to off. Add another username under To user. This example uses Bobby
    8. Select Review Changes, then Create to finish

    Next, you need to add your credentials to your project's local environment to use the Split integration in your code.

  3. Get your credentials

    Next, you'll add the following credentials to your Vercel project:

    • SPLIT_SDK_CLIENT_API_KEY
    • EDGE_CONFIG_SPLIT_ITEM_KEY
    • EDGE_CONFIG

    To add environment variables to your project, visit your Vercel dashboard and select the project you want to use the Split integration with. Then select Settings > Environment Variables.

    To get your Split client-side API keys:

    1. Log into your Split management console and select the workspace icon near the top-left of the page
    2. In the list of options that appears, select Admin Settings, then navigate to API Keys -> SDK API Keys
    3. Copy the client-side keys associated with the workspace and environment you're using

    To add your Edge Config Split item key, if you didn't copy it after setting up the integration on Vercel:

    1. Visit your dashboard on Vercel
    2. In the Integrations tab, select Manage
    3. On the integration page, select Configure
    4. You should see the item key on the page that opens. Copy it

    To add your Edge Config's connection string to your project:

    1. Visit your project's page in the dashboard
    2. Select the Storage tab. Select Connect Store and select the Edge Config associated with your Split integration. The EDGE_CONFIG environment variable will be set automatically.

    Now you're ready to use the Split Edge Config integration in your code.

  4. Use the Split integration in your code

    Open your project's code on your local machine and do the following:

    1. Install Split's Browser SDK, Vercel integration utilities, and Vercel's Edge Config SDK:

      pnpm
      yarn
      npm
      pnpm i @splitsoftware/splitio-browserjs @splitsoftware/vercel-integration-utils @vercel/edge-config
    2. Create an API route in your project. The following example fetches a treatement based on which user is visiting. You can specify the user by appending ?userKey=Joe or ?userKey=Bobby to the URL when visiting the route:

    Next.js (/app)
    Next.js (/pages)
    Other frameworks
    app/api/marketing-example/route.ts
    import {
      SplitFactory,
      PluggableStorage,
      ErrorLogger,
    } from '@splitsoftware/splitio-browserjs';
    import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
    import { createClient } from '@vercel/edge-config';
     
    export const runtime = 'edge';
     
    export async function GET(request: Request) {
      const { EDGE_CONFIG_SPLIT_ITEM_KEY, SPLIT_SDK_CLIENT_API_KEY } = process.env;
     
      if (!SPLIT_SDK_CLIENT_API_KEY || !EDGE_CONFIG_SPLIT_ITEM_KEY)
        return new Response(
          `Failed to find your SDK Key (${SPLIT_SDK_CLIENT_API_KEY})
          or item key ${EDGE_CONFIG_SPLIT_ITEM_KEY}`,
        );
     
      const edgeConfigClient = createClient(process.env.EDGE_CONFIG);
      const { searchParams } = new URL(request.url);
      const userKey = searchParams.get('userKey') || 'anonymous';
      const client = SplitFactory({
        core: {
          authorizationKey: SPLIT_SDK_CLIENT_API_KEY,
          key: userKey,
        },
        mode: 'consumer_partial',
        storage: PluggableStorage({
          wrapper: EdgeConfigWrapper({
            // The Edge Config item key where Split stores
            // feature flag definitions
            edgeConfigItemKey: EDGE_CONFIG_SPLIT_ITEM_KEY,
            // The Edge Config client
            edgeConfig: edgeConfigClient,
          }),
        }),
        // Disable or keep only ERROR log level in production,
        // to minimize performance impact
        debug: ErrorLogger(),
      }).client();
     
      await new Promise((resolve) => {
        client.on(client.Event.SDK_READY, () => resolve);
        client.on(client.Event.SDK_READY_TIMED_OUT, () => resolve);
      });
     
      // Replace this with the feature flag you want
      const FEATURE_FLAG = 'New_Marketing_Page';
      const treatment = await client.getTreatment(FEATURE_FLAG);
     
      // Must await in app-router; waitUntil() is not
      // yet supported
      await client.destroy();
     
      // treatment will be 'control' if the SDK timed out
      if (treatment == 'control') return new Response('Control marketing page');
     
      return treatment === 'on'
        ? new Response('New marketing page')
        : new Response('Old marketing page');
    }
  5. Test your code

    1. Start a local development server. If you're using Vercel CLI, enter the following command in the terminal:
    terminal
    vercel dev
    1. Navigate to http://localhost:3000/api/split-example?userKey=Joe. You should see either New marketing page or Old marketing page based on how your feature flags are configured in Split
      • Try changing the userKey search param's value to Bobby, or deleting it altogether, to see different responses when you visit the route
Last updated on May 29, 2024