Ampli

Ampli dynamically generates a light-weight wrapper for the Amplitude SDK based on your analytics tracking plan in Amplitude Data making event tracking easier and less error-prone.

This document provides a high-level overview of Ampli. For more information, see Amplitude Academy.

The Ampli Wrapper provides types and methods that prevent human error by strictly enforcing event names and property values. The wrapper code enables autocompletion for all events and properties in your tracking plan, as well as static type checks at development and compile time.

 1import { ampli, SongPlayed } from './ampli';
 2 
 3// These 2 events are tracked as expected.
 4ampli.songPlayed({ title: 'Happy Birthday' });
 5ampli.track(new SongPlayed({ title: 'Song 2' }));
 6 
 7// The following 2 events won't track due to data quality issues.
 8// Instead they generate type errors at build time with information
 9// about the expected property names and types.
10 
11// Error: Event 'Song Played' is missing required property 'title'
12ampli.songPlayed({ name: 'I Knew You Were Trouble' });
13 
14// Error: Property 'title' received 'boolean' expected type 'String'
15ampli.songPlayed({ title: true });

Compare this to the general purpose Amplitude SDK. Sending events with hand entered values can create data quality issues and require close coordination between data governors and engineers.

 1import * as amplitude from '@amplitude/analytics-browser';
 2 
 3// These 2 events are tracked as expected
 4amplitude.track('Song Played', { title: 'Happy Birthday'});
 5amplitude.track({
 6    event_type: 'Song Played',
 7    event_properties: {title: 'Song 2'}
 8});
 9 
10// The following 2 events are tracked but have data quality issues making them
11// difficult to include in analysis. Typos and type errors are easy to create
12// and hard to find & fix.
13 
14// Charts based on 'title' will not include this event, which sets 'name' instead.
15amplitude.track('Song Played', { name: 'I Knew You Were Trouble' });
16 
17// This event will not be included in charts based on event_type='Song Played'.
18// Also it sets 'title' to boolean 'true' instead of the expected type 'String'.
19amplitude.track('sonG Playd', { title: true });

The Ampli CLI generates the Ampli Wrapper and can verify the instrumentation status of your events. This makes it easy to know if you missed any event tracking calls giving you confidence that you successfully completed your implementation.

1➜ ampli status
2✔ Verifying event tracking implementation in source code
3  ✔ Song Played (1 location)
4✔ All events tracked: 1 found, 1 total

Supported platforms

Amplitude Data

Amplitude Data allows you to plan your analytics by defining the events and properties you want to track in your application. Ampli requires a tracking plan in Amplitude Data with events added to an SDK source.

The following examples will reference this tracking plan.

• Browser SDK source named web
• Event Song Played with required property title of type String
• Event Song Played is added to source web
• Environment named production

Ampli CLI

The Ampli CLI connects to Amplitude Data and uses the schema information for a given Source to generate and verify the Ampli Wrapper in your project.

Install Ampli CLI

1brew tap amplitude/ampli
2brew install ampli

1npm install -g @amplitude/ampli

Generate the Ampli wrapper

Running ampli pull connects to Amplitude Data and downloads the Ampli Wrapper for your tracking plan.

1ampli pull [source-name] [--path ./path/for/generated/ampli/wrapper]

The Ampli Wrapper is associated to a specific Source in Amplitude Data. You can optionally provide the desired Source name as a parameter, if not you will be prompted to select one.

1? Select a Source: web

The first time you run ampli pull on a source you will be asked to select a development language and an underlying Amplitude SDK. If you want to change the Source configuration later you can run ampli configure to select a different platform, language, or Amplitude SDK.

1? Select a platform: Browser
2? Select a language: TypeScript
3? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)

The generated Ampli Wrapper will then be available in the provided path. If no path was provided, the Ampli CLI provides a sensible default based on the platform of your Source.

1✔ Tracking library generated successfully.
2  ↳ Path: ./ampli

Verify event instrumentation

Running ampli status scans the source code in your project directory and checks for event tracking calls e.g. ampli.songPlayed({ ... }). It will output the number of times each event is detected.

1➜ ampli status
2✔ Verifying event tracking implementation in source code
3  ✔ Song Played (1 location)
4✔ All events tracked: 1 found, 1 total

If there are events in your tracking plan that are not implemented ampli status will return an error. For example, if you were to add a new event Song Favorited to the tracking plan but not instrument it in the project.

1➜ ampli status
2✔ Verifying event tracking implementation in source code
3  ✔ Song Played (1 location)
4  ✘ Song Favorited
5✘ ERROR Event tracking incomplete: 1 missed, 2 total

Ampli Wrapper

A generated SDK for your tracking plan

The Ampli Wrapper is a thin facade over the Amplitude SDK that provides convenience methods e.g. ampli.songPlayed() and classes e.g. new SongPlayed() for all events in your tracking plan.

 1import { ampli, SongPlayed } from './ampli';
 2 
 3ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
 4 
 5ampli.client.setUserId('ampli@amplitude.com');
 6 
 7ampli.songPlayed({ title: 'Happy Birthday' });
 8 
 9ampli.track(new SongPlayed({ title: 'Song 2'}));
10 
11ampli.flush();

Wrapping the Amplitude SDK

The Ampli Wrapper provides access to all methods of the underlying Amplitude SDK instance via ampli.client. It is possible to configure the instance directly or provide an existing one. If none is provided a default instance of the Amplitude SDK is used.

 1import * as amplitude from '@amplitude/analytics-browser';
 2import { ampli } from './ampli';
 3import { CustomPlugin } from './plugins';
 4 
 5// Initialize the Amplitude SDK instance
 6amplitude.init(AMPLITUDE_API_KEY);
 7 
 8// Provide the Amplitude SDK instance to Ampli
 9ampli.load({ client: { instance: amplitude }});
10assertEqual(ampli.client, amplitude);
11 
12// Call methods directly on the Amplitude SDK
13ampli.client.add(CustomPlugin);
14ampli.client.setUserId('ampli@amplitude.com');
15ampli.client.setGroup('team', 'awesome');

To configure the underlying Amplitude SDK instance without creating it directly provide client.configuration to ampli.load(). All configuration options of the underlying Amplitude SDK are supported.

1ampli.load({ client: { apiKey: AMPLITUDE_API_KEY, configuration: { serverZone: 'EU' } }});

Add the Ampli Wrapper to your project and track events

Use the Ampli CLI to download the Ampli Wrapper.

1ampli pull [--path ./ampli]

The downloaded source code in path and ampli.json should be added to your repository and source control.

1git add ./ampli ampli.json
2git commit -m "Added Ampli wrapper"

Depending on the Amplitude SDK selected for your Source your will need to install the corresponding dependency.

1npm install @amplitude/analytics-browser

Once the Ampli Wrapper has been downloaded with ampli pull and dependencies installed you can start using it to track events in your code.

1import { ampli, SongPlayed } from './ampli';
2 
3ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
4ampli.songPlayed({ title: 'Happy Birthday' });
5ampli.flush();

Use the Ampli CLI to verify instrumentation status of the Ampli Wrapper in your project.

1ampli status