On this page

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, replace Amplitude SDK calls with Ampli calls. You can migrate gradually.

Progressive migration

Step 0: Amplitude SDK only

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

Code example

typescript
import * as amplitude from "@amplitude/analytics-browser";

amplitude.init(AMPLITUDE_API_KEY);
amplitude.track("Song Played", { title: "The best song in the world." });
amplitude.track({
  event_type: "Song Played",
  event_properties: {
    title: "Song 2",
  },
});
amplitude.flush();

Step 1: Amplitude SDK and Ampli together

You can use Ampli with your existing Amplitude SDK implementation. Learn how Ampli and the Amplitude SDK work together in the Ampli overview documentation.

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

typescript
ampli.load({ client: { instance: amplitude } });

All existing amplitude.track('Song Played') calls, also known as amplitude.logEvent(), continue to work. You also get access to strongly typed methods and types for all events for the source in your tracking plan. For example, use ampli.songPlayed() and ampli.track(new SongPlayed()).

Process

Use branching for easier migration

Amplitude recommends creating a branch and adding small sets of events at a time, which splits the migration into manageable parts rather than requiring you to implement all events at the same time.

If you plan to use ampli status to verify instrumentation, implement all events for the current source before the check can pass. Isolating the instrumentation into small parts lets you use ampli status at each part of the migration instead of waiting for all events to be complete.

  1. Add some events to the tracking plan in Data. Add those events to your Source.
  2. Run 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 Ampli replaces all Amplitude SDK calls.

Code example

diff
import * as amplitude, { BaseEvent } from '@amplitude/analytics-browser';
+ import { ampli, SongPlayed } from './path/to/ampli';

// Original Implementation
// Notice this will keep working as-is, so you can keep the
// existing implementation while progressively migrating to Ampli

amplitude.init(AMPLITUDE_API_KEY);
amplitude.add(new MyPlugin());
amplitude.setUserId('me');
amplitude.track('Song Played', { title: 'Happy Birthday'});
amplitude.track({
  event_type: 'Song Played',
  event_properties: {
    title: 'The best song in the world.'
  }
});
amplitude.flush();

+ // Ampli implementation
+ // Pass in the existing instance of Amplitude SDK to Ampli
+ // Use Ampli to track new strongly typed methods and types
+ // All Ampli methods call the underlying Amplitude SDK instance
+
+ ampli.load({ client: { instance: amplitude }});
+ ampli.songPlayed({ title: 'Hello Sunshine' });
+ ampli.track(new SongPlayed({ title: 'Song 2' }));
+ ampli.flush();

Step 2: Ampli only

After Ampli replaces all existing Amplitude SDK instrumentation, remove unnecessary Amplitude SDK imports and initialization. Use the equivalent imports and initialization from Ampli.

Code example

diff
- import * as amplitude, { BaseEvent, Options } from '@amplitude/analytics-browser';
+ import { ampli, SongPlayed, Options } from './path/to/ampli';

// Initialize
const sdkOptions: Options = { ... };
- amplitude.init(AMPLITUDE_API_KEY, undefined, sdkOptions);
+ ampli.load({
+   client: {
+     apiKey: AMPLITUDE_API_KEY,
+     configuration: sdkOptions
+   }
+ })

// Plugins
- amplitude.add(new MyPlugin())
+ ampli.client.add(new MyPlugin())

// Set User
- amplitude.setUserId('me')
+ ampli.client.setUserId('me')

// Track Events
- amplitude.track('Song Played', { songId: 'Happy Birthday'});
+ ampli.songPlayed({title: 'Happy Birthday'});
+ ampli.track(new SongPlayed({ songId: 'The best song in the world.' }));

// Flush Events
- amplitude.flush();
+ ampli.flush();

Side-by-side comparison

Install

shell
npm install @amplitude/analytics-browser

Initialize

typescript
import * as amplitude from "@amplitude/analytics-browser";

amplitude.init(AMPLITUDE_API_KEY);

Track

typescript
amplitude.track("Sign Up");

amplitude.track({
  event_type: "Song Played",
  user_properties: {
    title: "Get Back",
  },
});

Flush

typescript
amplitude.flush();

Other methods

typescript
amplitude.setUserId("me");
amplitude.add(new MyPlugin());
amplitude.setGroup("team", "awesome");
amplitude.groupIdentify("team", "awesome", {
  groupProperty: true,
});

Was this helpful?