Skip to content

Ampli

Overview

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. A video demo is also available below and in Amplitude Academy.

How Ampli fits into your workflow

How Ampli fits into your workflow

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.

import { ampli, SongPlayed } from './ampli';

ampli.songPlayed({ title: 'Happy Birthday' });
ampli.track(new SongPlayed({ title: 'Song 2' }));
// => These 2 events are tracked as expected

ampli.songPlayed({ name: 'I Knew You Were Trouble' });
// => Error: Event 'Song Played' is missing required property 'title'

ampli.songPlayed({ title: true });
// => Error: Property 'title' received 'boolean' expected type 'String'

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.

import * as amplitude from '@amplitude/analytics-browser';

amplitude.track('Song Played', { title: 'Happy Birthday'});
amplitude.track({
  event_type: 'Song Played',
  event_properties: { title: 'Song 2'}
);
// => These 2 events are tracked as expected

amplitude.track('Song Played', { name: 'I Knew You Were Trouble' })
// => Event will be tracked but is difficult to include in charts and other analysis

amplitude.track('sonG Playd', { title: true })
// => Typos and property errors are easy to create, and hard to find & fix

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.

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

Amplitude Data

Create a tracking plan for your events

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
Create a Source for your desired platform Create Events in your tracking plan and assign them to your Source View Source settings and instructions
Create a Source for your desired platform Create Events in your tracking plan and assign them to your Source View Source settings and instructions

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 the Ampli CLI

NPM and Homebrew are supported.

npm install -g @amplitude/ampli

Generate the Ampli Wrapper with ampli pull

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

ampli 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.

? 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.

? Select a platform: Browser
? Select a language: TypeScript
? 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.

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

ampli pull

Example run of "ampli pull"

Verify event instrumentation with ampli status

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.

➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ 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.

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

ampli status

Example run of "ampli status"

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. Additionally, ampli.load() allows selecting different environments defined in Amplitude Data by name rather than needing to keep track of API keys.

import { ampli, SongPlayed } from './ampli';

ampli.load({ environment: 'production' });

ampli.client.setUserId('ampli@amplitude.com');

ampli.songPlayed({ title: 'Happy Birthday' }));

ampli.track(new SongPlayed({ title: 'Song 2'}));

ampli.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.

import * as amplitude from '@amplitude/analytics-browser';
import { ampli } from './ampli';
import { CustomPlugin } from './plugins';

amplitude.init('my-api-key');
ampli.load({ client: { instance: amplitude }})
assertEqual(ampli.client, amplitude);

ampli.client.add(CustomPlugin);
ampli.client.setUserId('ampli@amplitude.com');
ampli.client.setGroup('team', 'awesome');

Add the Ampli Wrapper to your project and track events

Use the Ampli CLI to download the Ampli Wrapper.

ampli pull [--path ./ampli]

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

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

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

npm 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.

import { ampli, SongPlayed } from './ampli';

ampli.load({ environment: 'production' });
ampli.songPlayed({ title: 'Happy Birthday' }));
ampli.flush();

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

ampli status

Video Tutorial

Migrating from the Amplitude SDK

It is easy to start using Ampli with your existing implementation. Learn more about migrating to Ampli from the Amplitude SDK.

Was this page helpful?