# Migrate to Ampli

Migrate from the Amplitude SDK to Ampli gradually while preserving existing analytics instrumentation.

Source: https://amplitude.com/docs/sdks/ampli/migrate-to-ampli

---

On this page

- [Progressive migration](#progressive-migration)
- [Step 0: Amplitude SDK only](#step-0-amplitude-sdk-only)
- [Step 1: Amplitude SDK and Ampli together](#step-1-amplitude-sdk-and-ampli-together)
- [Step 2: Ampli only](#step-2-ampli-only)
- [Side-by-side comparison](#side-by-side-comparison)
- [Install](#install)
- [Initialize](#initialize)
- [Track](#track)
- [Flush](#flush)
- [Other methods](#other-methods)

# 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](/docs/sdks/ampli) 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.

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.

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.add(new MyPlugin());
amplitude.setUserId('me');
amplitude.track('Song Played', { title: 'Happy Birthday'});
  event_type: 'Song Played',
    title: 'The best song in the world.'
  }

+ // 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.

- 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();

## Side-by-side comparison

### Install

shell

npm install @amplitude/analytics-browser

### Initialize

### Track

amplitude.track("Sign Up");

  user_properties: {
    title: "Get Back",

### Flush

### Other methods

amplitude.setUserId("me");
amplitude.setGroup("team", "awesome");
amplitude.groupIdentify("team", "awesome", {
  groupProperty: true,

Was this helpful?

<!--$-->

<!--/$-->