Migrating from Segment or RudderStack

Migrating from Segment or RudderStack is straightforward because the tracking libraries have the same interface. This document describes step-by-step how to migrate.

Prepare

First, prepare for your migration by evaluating how your events are currently used:

• What applications do you collect events from?
• What tools do you send your events to?
• What data pipelines depend on the events in your warehouse? For example, analytics and activation.

The query logs from your warehouse are a great way to find what queries depend on your event tables.

Instrument Your Applications

Next, you need to add tracking code to your applications to collect the same information as your old event collection tool.

Hightouch Events was designed to work with the most common tracking interfaces, so reinstrumenting only requires importing the Hightouch SDK and invoking the Hightouch SDK alongside your old tool.

Not only does Hightouch accept the same tracking options, but it also autocollects the same properties as other event tools. Additionally, Hightouch automatically migrates anonymous ids from your users' devices, so anonymous sessions will seamlessly transfer over.

We recommend updating your application code to expose an analytics wrapper that invokes your old event tool and Hightouch in the same call (kudos if you designed your events code like this from day one!). This wrapper can add a migrationId to both versions of your events so that they can be rejoined in the warehouse when validating your migration.

function track(eventName, properties) {
  const context = { migrationId: getMigrationId() };
  oldTool.track(eventName, properties, context);
  htevents.track(eventName, properties, context);
}

function getMigrationId(): string {
  const timestamp = Date.now();
  const randomness = Math.floor(Math.random() * 1000);
  return `${timestamp}-${randomness}`;
}

Additionally, you need to decide how you want the data to appear in the warehouse. To simplify the migration you may choose to write the data in the same format as your old tool, or you can customize the schema if it simplifies your data pipelines.

Either way, we recommend writing the Hightouch events into a separate schema in your warehouse. This makes it easier to isolate the events while you test, and to compare them with your old data.

Validate Your Data

Now that you have some test data in your warehouse, you can validate it to confirm that your new tracking can power all your existing use cases. For example, you may realize that there's a backend service that you forgot to migrate over.

We recommend checking the data using some (or all) of the following techniques:

1. Does the Hightouch data have the same schema as your existing data? Depending on your current setup, you can check this by directly comparing the tables and schemas in the warehouse, or by just running your existing models against the new schemas.
2. Does Hightouch collect the same data values?
   • Does Hightouch collect approximately the same volume of data? (Note that you shouldn't expect a 100% match. A variety of expected scenarios like deployment rollout, ad blockers, and network errors can cause events to appear in one tool but not another.)
   • JOIN events between Hightouch and your old events tool using your migrationId to compare the column values
3. Are your business reports and dashboards the same when built off the Hightouch events?

Unify Your Data

Once you're confident in the data you're collecting with Hightouch, you will need to combine it with historical data from your old events tool. This can be done by UNIONing the data together, and deduping events that were collected in both tools.

We recommend deduping by picking a timestamp before which you will just use events from your old events provider, and after which you will use Hightouch's events.

For additional deduping to account for events that are collected at slightly different times, you may deduplicate based on the migration ID as well. The migration ID is particularly useful for mobile apps to evaluate when enough of your users have upgraded to the Hightouch-instrumented version of your app.