Guide

This guide builds on the SDK quickstart and shows you how to:

Create new event triggers and event types
Add event-specific properties
Log events from your code
View raw events in tables
Build funnels to visualize events

Prerequisites

Create new event triggers and event types

Go to the Flags view in the dashboard. Click the + button in the top-right of the sidebar and select Flag.

Enter a name, and select Event trigger as the type. Enable the toggle to create matching event types. Click Create, then click Save.

An event trigger is a special kind of flag that has a Void return type — it doesn't return a value, but can be called like any other flag.

When your code calls an event trigger, the Log event expression is evaluated, and an event is logged with the configured Event type and Payload.

By default, the event type is set to the one created automatically with your event trigger. If your event trigger is called pageView, the event type will be called PageViewEvent, and the payload will be of this type.

The payload contains:

A context field with the Context type, automatically set to the top-level context you pass to the SDK.
A properties field with a type automatically created with your event trigger. If your event trigger is called pageView, it will be called PageViewEventProperties. By default, the type is empty, but you can add event-specific properties here, e.g. href. You can then pass properties as an argument when calling the event trigger from your code.

This setup enables you to log events with both the top-level context you pass to the SDK and extra event-specific properties, with full end-to-end type safety based on your schema.

Add event-specific properties

Click the arrow next to the selected event type to navigate to it in the Schema view.

Then click Go to type on the Properties field to navigate to the event properties type.

By default, this type has no fields, i.e. there are no event-specific properties.

Click + Add, enter a name for the event property, set its type, and click Create.

Click Save.

Log events from your code

Regenerate the client:

npx hypertune

yarn hypertune

pnpm hypertune

Then use the generated method to call the event trigger and log your event:

Use the generated useHypertune hook:

components/ClientComponent.tsx

'use client'

import { useEffect } from 'react'
import { useHypertune } from '@/generated/hypertune.react'

export default function ClientComponent() {
  const hypertune = useHypertune()
  const hypertuneIsReady = hypertune.isReady()

  useEffect(() => {
    if (!hypertuneIsReady) {
      return
    }
    hypertune.pageView({
      args: { properties: { href: window.location.href } },
    })
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [hypertuneIsReady])

  return (
    <button
      type="button"
      onClick={() => {
        hypertune.signUp({ args: { properties: {} } })
      }}
    >
      Sign up
    </button>
  )
}

For events like page views that you want to log immediately after rendering a component:

First check that the Hypertune SDK is ready with hypertune.isReady().
Log them inside a useEffect with a dependency array that only contains the result of hypertune.isReady() so they're only logged once.

Use the getHypertune function:

app/api/route.ts

import { waitUntil } from '@vercel/functions'
import { NextResponse } from 'next/server'
import getHypertune from '@/lib/getHypertune'

export const runtime = 'edge'

export async function GET() {
  const hypertune = await getHypertune({ isRouteHandler: true })

  hypertune.signUp({ args: { properties: {} } })

  waitUntil(hypertune.flushLogs())

  return NextResponse.json({})
}

Notes

Enable remote logging: By default, remote logging is disabled on Next.js servers because prefetching and caching of pages and layouts can cause logs for flag evaluations, experiment exposures, and analytics events to differ from actual user behaviour. To ensure accuracy, remote logging is enabled by default on the client (in the browser) only. However, since Route Handlers aren't subject to the same prefetching and caching patterns, remote logging is enabled for them by passing { isRouteHandler: true } in the call to getHypertune.
Flush logs: waitUntil(hypertune.flushLogs()) ensures that logs are sent. Without this, logs may still flush in the background, but this isn't guaranteed in serverless environments like Vercel deployments.

View raw events in tables

Go to the Analytics view in the dashboard. Click the + button in the top-right of the sidebar and select Table. Enter a name and click Create.

Click + Add query, select Event, select the event type from the dropdown, and click Add.

You'll see a table of raw events. To filter them, click + Filter, and configure a filter.

Click Save so you can revisit this table and share it with your team.

Build funnels to visualize events

Click the + button in the top-right of the sidebar. Select Funnel, enter a name, and click Create.

Click + Add funnel step, choose Event, select the first event type of your funnel, and click Add.

You'll see the total number of events of that type during the selected time range.

Click the + button to the right of the first step, choose Event, select your conversion event in the dropdown, and click Add.

Now you'll see:

Total number of users who completed the first event during the selected time range
Number of those users who completed the conversion event during the selected time range
Conversion rate

Click Save so you can revisit this funnel and share it with your team.

Next steps

Add more steps to your funnel or configure each step with filters, breakdowns, segments, derived fields, and aggregations.
Create an A/B/n test to see if a new feature drives conversion lift across your funnel.
Run a multivariate test to find the best combination of feature variants to maximize conversion lift.
Set up an AI loop to automatically shift traffic to the best feature variants for each unique user to maximize conversion lift.

PreviousOverview NextOverview

Last updated 1 day ago