Integrate flags with Vercel Web Analytics

Learn how to tag your page views and custom events with feature flags
Table of Contents

Feature flags are available in Beta on all plans

Feature Flags section in Vercel Web Analytics
Feature Flags section in Vercel Web Analytics

Vercel Web Analytics can look up the values of evaluated feature flags in the DOM. It can then enrich page views and client-side events with these feature flags.

  1. To share your feature flags with Web Analytics:

    1. Emit your feature flag values to the DOM as described in Supporting Feature Flags.

    2. Next, add the <FlagsReporter /> component before your <Analytics /> component, including a list of flag keys you want to track:

      app/layout.tsx
      import { Analytics } from '@vercel/analytics/react';
      import { FlagsReporter } from '@vercel/flags/react';
       
      export default function RootLayout({ children }: { children: React.ReactNode }) {
        return (
          <html lang="en">
            <body>
              {children}
              <FlagsReporter keys={['summer-sale', 'instant-checkout']} />
              <Analytics />
            </body>
          </html>
        );
      }

    This will annotate all page views and client-side events with the summer-sale and instant-checkout feature flags.

    It's important to configure these tracked keys because the amount of flags and their values can exceed the event size limit of Vercel Web Analytics.

  2. Client-side events in Web Analytics will now automatically respect the defaults configured through keys on the FlagsReporter component, and attach those to custom events.

    To manually overwrite the tracked flags for a specific track event, call:

    component.ts
    import { track } from '@vercel/analytics';
     
    track('My Event', {}, { flags: ['summer-sale'] });

    If the flag values on the client are encrypted, the entire encrypted string becomes part of the event payload. This can lead to the event getting reported without any flags when the encrypted string exceeds size limits.

To track feature flags in server-side events:

  1. First, report the feature flag value using reportValue to make the flag show up in Runtime Logs:

    app/api/test/route.ts
    import { reportValue } from '@vercel/flags';
     
    // force dynamic mode so the flag actually gets reported,
    // otherwise the route would be static
    export const dynamic = 'force-dynamic';
     
    export async function GET() {
      reportValue('summer-sale', false);
      return Response.json({ ok: true });
    }
  2. Once reported, any calls to track can look up the feature flag while handling a specific request:

    app/api/test/route.ts
    import { track } from '@vercel/analytics/server';
    import { reportValue } from '@vercel/flags';
     
    // force dynamic mode so the flag actually gets reported,
    // otherwise the route would be static
    export const dynamic = 'force-dynamic';
     
    export async function GET() {
      reportValue('summer-sale', false);
      track('My Event', {}, { flags: ['summer-sale'] });
     
      return Response.json({ ok: true });
    }

If you are using an implementation of the Feature Flags Pattern you don't need to call reportValue. The respective implementation will automatically call reportValue for you.

Last updated on June 21, 2024