Step 2: Implementing Hightouch Events SDKs

Hightouch Events provides SDKs across web, mobile, and server-side languages. This step covers switching from your current event tracking SDK (such as Segment's or RudderStack's) to Hightouch Events.

Hightouch Events is backward compatible with common tracking APIs like those of Segment and RudderStack, so the initial code changes are usually straightforward. If you're coming from a platform with a different SDK shape, such as Amplitude or mParticle, expect more re-instrumentation — see its platform guide for what differs.

Install the SDKs

Install the Hightouch SDK for each source you're migrating. Installation is the same as for a fresh implementation — see Connect event sources and the SDK reference for your platform, such as Browser, Node.js, or Python. Use the write key from your Hightouch event source.

Because the SDKs accept the same calls as your current tool, the migration-specific work isn't the install — it's sending each call to both tools so you can compare data. That's what the rest of this step covers.

Implement standard tracking calls (track, page, and identify)

During this step, you'll update your event method calls to also call the matching Hightouch SDK method.

The example below shows a wrapper function that calls the track method of your prior tool and Hightouch Events. Both calls take the same parameters and include a migrationId that lets you validate data during the migration.

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

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

This wrapper function does the following:

• Generates a unique migrationId for each event
• Sends the event to your current tracking system
• Sends the same event to Hightouch Events
• Includes the migrationId with both events for later comparison and deduplication

Attach the migrationId in the event's context, as the examples here do, so it lands consistently across event types. In the warehouse, Hightouch flattens context fields to context_<field> columns and snake-cases the key, so migrationId becomes the context_migration_id column. The validation and unification queries in later steps use context_migration_id for this reason. (If your event storage destination isn't configured to explode context into columns, the value stays nested under the context JSON instead.)

Handle identify and page view events

Create similar wrapper functions for other common event types based on their parameters and type signatures. For example, for an identify method in the Browser SDK,

function identifyUser(userId, traits) {
  const context = { migrationId: getMigrationId() };

  analytics.identify(userId, traits, context);
  htevents.identify(userId, traits, context);
}

Migrate server-side events

Follow a similar pattern for server-side event tracking. Below, we show an example of using the Python SDK with a wrapper function.

import segment.analytics as analytics
import hightouch.htevents as htevents
import uuid

analytics.write_key('YOUR_SEGMENT_WRITE_KEY')
htevents.write_key('YOUR_HIGHTOUCH_WRITE_KEY')

def track_event(user_id, event_name, properties):
    context = {'migrationId': str(uuid.uuid4())}

    # Track with Segment
    analytics.track(user_id, event_name, properties, context=context)

    # Track with Hightouch
    htevents.track(user_id, event_name, properties, context=context)

Update analytics code across your repositories

If your codebase historically directly calls Segment's (or another provider's) library to trigger events, use your preferred method for making bulk code changes across your repository or repositories, whether it's using grep / find and sed, find and replace across a workspace in your editor, or other tools to replace track, identify, group, page, and screen calls with the wrapper functions.

Make sure that you don't just update the analytics code with the wrapper function(s), but also update library imports across files that call the new wrapper function.

If you've already implemented wrapper functions and have modified them using the preceding migration examples, you should be all set.

Testing the implementation

After implementing the wrapper functions:

1. Test thoroughly in a development or staging environment.
2. Verify that events are being received by both your current system and Hightouch Events.
3. Check that the migrationId is correctly included in events from both systems.

Anonymous IDs and automatically collected information

Hightouch Events’ Browser, iOS, and Android SDKs automatically collect a range of information. Read the docs for the full list of fields.

Anonymous-ID continuity depends on the SDK. On iOS, Hightouch Events reuses the anonymous ID that Segment or RudderStack already assigned, so returning users keep their session instead of starting fresh. On Android, the SDK stores the anonymous ID under its own keys and doesn't read the previous provider's value, so those users get a new anonymous ID at cutover. Rely on userId continuity to connect known users across the switch on every platform.

Optional: Gradual rollout

Depending on the number of your event sources, your event volume, and whether any of them power critical downstream services, you can consider implementing a gradual rollout strategy. This can help build the migration team's confidence in Hightouch Events and make the migration process more manageable by constraining event volume and sources in the first migration efforts.

1. Start using Hightouch Events with a small percentage of your user base or a specific segment. Some organizations migrate a portion of traffic to start with, while others migrate sources related to a particular platform (such as mobile apps) before migrating additional platforms.
2. Monitor for any issues or discrepancies.
3. Gradually increase the percentage of users or sources on the new system.

By following these steps, you'll have successfully implemented the Hightouch SDK alongside your existing event tracking system. This dual-tracking approach allows for thorough validation and comparison in the next phases of the migration process.

As you instrument, set up data contracts for your core events to catch bad data before it reaches your warehouse. Version your contract events so older app versions keep validating during the rollout, and start permissive — allow violations with a warning, then tighten as your data stabilizes.

In the next step, you'll validate your migration to confirm that Hightouch Events captures data correctly and consistently with your previous system.