Step 2: Implementing Hightouch Events SDKs

Hightouch Events provides a range of SDKs across web, mobile, and server-side languages. This step covers the technical implementation of 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, making the initial code changes straightforward. We'll cover examples below for a couple of languages.

Implementing the Browser SDK (Javascript)

Use the Browser SDK to track events in webpages.

1. Install the Browser SDK by loading the Javascript through a script tag with the following snippet or through npm.

Through a script tag:

<script type="text/javascript">
!function(){var e=window.htevents=window.htevents||[];if(!e.initialize)if(e.invoked)window.console&&console.error&&console.error("Hightouch snippet included twice.");else{e.invoked=!0,e.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"],e.factory=function(t){return function(){var n=Array.prototype.slice.call(arguments);return n.unshift(t),e.push(n),e}};for(var t=0;t<e.methods.length;t++){var n=e.methods[t];e[n]=e.factory(n)}e.load=function(t,n){var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src="<https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js>";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(o,r),e._loadOptions=n,e._writeKey=t},e.SNIPPET_VERSION="0.0.1",
e.load('WRITE_KEY',{apiHost:'us-east-1.hightouch-events.com'}),
e.page()}}();
</script>

Through npm:

Install with npm install @ht-sdks/events-sdk-js-browser.

Import and initialize the SDK:

import { HtEventsBrowser } from "@ht-sdks/events-sdk-js-browser";
export const htevents = HtEventsBrowser.load(
  { writeKey: "WRITE_KEY" },
  { apiHost: "us-east-1.hightouch-events.com" }
);

In both cases, replace your WRITE_KEY with the write key from your source.

Implementing standard tracking calls, such as track, page, and identify

During this step of the migration, you'll update your instances of event method calls to also call the same Hightouch SDK method.

The example below shows an implementation of a wrapper function that calls the track method of a prior tool and Hightouch Events. Both track calls take the same parameters, and include a migrationId property that enables validation of data during the migration process.

function track(eventName, properties) {
  const context = { migrationId: getMigrationId() };
  analytics.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}`;
}

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

Handling identify and page view events

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

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

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

Migrating 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):
    migration_id = str(uuid.uuid4())
    properties_with_id = {**properties, 'migrationId': migration_id}

    # Track with Segment
    analytics.track(user_id, event_name, properties_with_id)

    # Track with Hightouch
    htevents.track(user_id, event_name, properties_with_id)

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 collects a range of information. Read the docs for the full list of fields.

Hightouch Events also automatically migrates anonymous IDs that were previously assigned by Segment or Rudderstack. If a user had an anonymous ID assigned via one of those providers, we'll continue to use the same anonymous ID in Hightouch Events so that user sessions are not interrupted or fragmented by the migration.

Optional: Gradual rollout

Depending on the number of your event sources, your event volume, and whether any 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.

In the next section, we'll explore how to define data contracts to ensure robust data governance throughout your migration and beyond.