Migrate to Ampli

Ampli provides the benefits of type safety, linting, and data validation to make sure that your analytics are accurate and trustworthy.

To migrate from Amplitude SDK to Ampli, you need to replace all calls using Amplitude SDK with calls using Ampli. However, the process can be done gradually and at your own pace.

Progressive Migration

Step 0 - Amplitude SDK Only

This page assumes you have existing analytics instrumentation using the Amplitude SDK.

Code Example

 1import * as amplitude from '@amplitude/analytics-browser';
 2 
 3amplitude.init(AMPLITUDE_API_KEY);
 4amplitude.track('Song Played', { title: 'The best song in the world.' });
 5amplitude.track({
 6  event_type: 'Song Played',
 7  event_properties: {
 8    title: 'Song 2'
 9  }
10});
11amplitude.flush();

Step 1 - Amplitude SDK & Ampli Together

It is easy to use Ampli with your existing Amplitude SDK implementation. Learn more about how Ampli and the Amplitude SDK work together in the Ampli overview documentation.

Start by passing your existing Amplitude SDK instance to Ampli. Ampli will use the given instance for all event tracking. This includes the API key, plugins, storage provider, log provider and other configuration set on the Amplitude instance.

1ampli.load({ client: { instance: amplitude }})

All existing amplitude.track('Song Played') (a.k.a. amplitude.logEvent()) will continue to work. However, you now also have access to strongly typed methods and types for all events for the Source in your tracking plan for exampleampli.songPlayed() and ampli.track(new SongPlayed()).

Process

1. Add some events to the tracking plan in Data. Add those events to your Source.
2. ampli pull to download the generated Events to your project
3. Start replacing amplitude.track('My Event', {prop: true}) with ampli.myEvent({ prop: true}) or ampli.track(new MyEvent({prop:true})) for each event in the tracking plan.
4. Repeat until all Amplitude SDK calls have been replaced by Ampli.

Code Example

 1import * as amplitude, { BaseEvent } from '@amplitude/analytics-browser';
 2+ import { ampli, SongPlayed } from './path/to/ampli';
 3 
 4// Original Implementation
 5// Notice this will keep working as-is, so you can keep the
 6// existing implementation while progressively migrating to Ampli
 7 
 8amplitude.init(AMPLITUDE_API_KEY);
 9amplitude.add(new MyPlugin());
10amplitude.setUserId('me');
11amplitude.track('Song Played', { title: 'Happy Birthday'});
12amplitude.track({
13  event_type: 'Song Played',
14  event_properties: {
15    title: 'The best song in the world.'
16  }
17});
18amplitude.flush();
19 
20+ // Ampli implementation
21+ // Pass in the existing instance of Amplitude SDK to Ampli
22+ // Use Ampli to track new strongly typed methods and types
23+ // All Ampli methods call the underlying Amplitude SDK instance
24+
25+ ampli.load({ client: { instance: amplitude }});
26+ ampli.songPlayed({ title: 'Hello Sunshine' });
27+ ampli.track(new SongPlayed({ title: 'Song 2' }));
28+ ampli.flush();

Step 2 - Ampli Only

After all existing Amplitude SDK instrumentation has been replaced with Ampli, you can do a little clean up by removing unnecessary imports and initialization of the Amplitude SDK and instead use the equivalent from Ampli. That’s it!

Code Example

 1- import * as amplitude, { BaseEvent, Options } from '@amplitude/analytics-browser';
 2+ import { ampli, SongPlayed, Options } from './path/to/ampli';
 3 
 4// Initialize
 5const sdkOptions: Options = { ... };
 6- amplitude.init(AMPLITUDE_API_KEY, undefined, sdkOptions);
 7+ ampli.load({
 8+   client: {
 9+     apiKey: AMPLITUDE_API_KEY,
10+     configuration: sdkOptions
11+   }
12+ })
13 
14// Plugins
15- amplitude.add(new MyPlugin())
16+ ampli.client.add(new MyPlugin())
17 
18// Set User
19- amplitude.setUserId('me')
20+ ampli.client.setUserId('me')
21 
22// Track Events
23- amplitude.track('Song Played', { songId: 'Happy Birthday'});
24+ ampli.songPlayed({title: 'Happy Birthday'});
25+ ampli.track(new SongPlayed({ songId: 'The best song in the world.' }));
26 
27// Flush Events
28- amplitude.flush();
29+ ampli.flush();

Side by Side Comparison

Install

1npm install @amplitude/analytics-browser

1npm install @amplitude/analytics-browser
2npm install -g @amplitude/ampli
3ampli pull [--path] ./ampli

Initialize

1import * as amplitude from '@amplitude/analytics-browser';
2 
3amplitude.init(AMPLITUDE_API_KEY);

 1import { ampli, SongPlayed } from './ampli';
 2 
 3// Initialize with Amplitude API Key
 4ampli.load({
 5    client: {
 6        apiKey: AMPLITUDE_API_KEY
 7    }
 8});
 9 
10// Or initialize with pre-existing Amplitude SDK instance
11ampli.load({
12  client: {
13    instance: amplitude,
14  }
15});

Track

1amplitude.track('Sign Up');
2 
3amplitude.track({
4  event_type: 'Song Played',
5  user_properties: {
6    title: 'Get Back'
7  }
8})

 1ampli.songPlayed({ title: "Get Back" })
 2ampli.track(new SongPlayed({ title: "Hey"}))
 3 
 4// Not recommended, but possible
 5// Ampli can track untyped events if desired
 6ampli.track({
 7  event_type: 'Sign Up',
 8  user_properties: {
 9    userProp: 1
10  }
11})

Flush

1amplitude.flush();

1ampli.flush();

Other Methods

 1amplitude.setUserId('me');
 2amplitude.add(new MyPlugin())
 3amplitude.setGroup('team', 'awesome')
 4amplitude.groupIdentify(
 5  'team',
 6  'awesome',
 7  {
 8    groupProperty: true
 9  },
10)

 1ampli.client.setUserId('me');
 2ampli.client.add(new MyPlugin())
 3ampli.client.setGroup('team', 'awesome')
 4ampli.client.groupIdentify(
 5  'team',
 6  'awesome',
 7  {
 8    groupProperty: true
 9  },
10)