# How to Migrate from Snowplow to RudderStack

This document covers the steps required to migrate from Snowplow to RudderStack and replace your instrumentation code. You can then start using the RudderStack SDKs to track your events with minimal code changes.

Set up your RudderStack dashboard

  1. Sign up for RudderStack.
  2. Set up the source-destination connections in the dashboard to facilitate event data flow. For more information on setting up connections, see the Quickstart guide.
Note your source write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. and data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL at the top of the Connections page in your RudderStack dashboard. as they will be used in the next section.

Update your SDK implementation

Depending on your target platform, follow these steps to move your existing Snowplow SDK implementation to RudderStack.

Android (Java) — Legacy

RudderStack distributes the Rudder Snowplow adapter SDK through Maven Central. We recommended you add the SDK to your project through the Android Gradle build system.

  1. Add the following code in your project level app/build.gradle file:
groovy 
buildscript {
  repositories {
    mavenCentral()
  }
}
allprojects {
  repositories {
    mavenCentral()
  }
}
  1. Add the following dependency under dependencies section in your app/build.gradle file:
groovy 
implementation 'com.rudderstack.android.snowplow:adapter:1.0.0.beta.1'
  1. Update your SDK initialization to any one of the following snippet (method 1, 2, or 3 in the following snippets). Also, replace the WRITE_KEY and DATA_PLANE_URL with your source write key and data plane URL obtained in the above section.
java 
//Method 1: Default values are considered for all configuration objects 
//except networkConfiguration.
RSTracker tracker = new RSTracker()
            .createTracker(
                this, WRITE_KEY, networkConfiguration
            );

//Method 2: Default values are considered for all configuration objects.
RSTracker tracker = new RSTracker()
            .createTracker(
                this, WRITE_KEY, DATA_PLANE_URL
            );

//Method 3: Values for all configuration objects must be provided.
RSTracker tracker = new RSTracker()
            .createTracker(
                this, WRITE_KEY, networkConfiguration,
                sessionConfiguration, trackerConfiguration,
                subjectConfiguration
            );
Refer to the Setting the configuration objects section for more information on using these configuration objects.

iOS (Obj-C) — Legacy

Follow these steps to migrate to the RudderStack iOS (Obj-C) SDK:

  1. Add the SDK to your Podfile:
ruby 
pod 'RudderSnowplowMigrator', '1.0.0.beta.1'
  1. Run the following command:
ruby 
pod install
  1. Add the following code in all .m and .h files (for Objective-C) or .swift files(for Swift) where you want to refer or use RudderStack SDK classes:
objectivec 
@import RudderSnowplowMigrator;
  1. Update your SDK initialization to any one of the following snippet (method 1, 2, or 3). Also, replace the WRITE_KEY and DATA_PLANE_URL with your source write key and data plane URL obtained in the above section.
objectivec 
//Method 1: Default values are considered for all configuration objects 
//except networkConfiguration.
RSTracker *tracker = [RSTracker createTrackerWithWriteKey:WRITE_KEY network:networkConfig];

//Method 2: Default values are considered for all configuration objects.
RSTracker *tracker = [RSTracker createTrackerWithWriteKey:WRITE_KEY dataPlaneUrl:DATA_PLANE_URL];

//Method 3: Values for all configuration objects must be provided.
RSTracker *tracker = [RSTracker createTrackerWithWriteKey:WRITE_KEY network:networkConfig configurations:@[trackerConfig]];
Refer to the the Setting the configuration objects section for more information on using these configuration objects.

JavaScript

To migrate to the RudderStack JavaScript SDK, add the following code snippet in the <head> section of your website. Also, replace the WRITE_KEY and DATA_PLANE_URL with your source write key and data plane URL obtained in the above section.

html 
<script>
  rs=window.rs=[],rs.snoplowAdapter=function(){rs.push(Array.prototype.slice.call(arguments))},rs.snoplowAdapter("newTracker",<WRITE_KEY>,<DATA_PLANE_URL>,{<Configurations>});
  //Optionally, use RudderStack JavaScript SDK load options
  rudderanalytics.load();
</script>

<script src="https://cdn.rudderlabs.com/adapter/sp/beta/v1/rs-sp-analytics.min.js"></script>

The <Configurations> parameter in the above snippet can be replaced by the following Snowplow properties which are mapped to the RudderStack properties as shown:

Snowplow property RudderStack property
cookieDomain setCookieDomain
cookieSameSite sameSiteCookie
cookieSecure secureCookie

Update mobile SDK configuration

RudderStack supports setting values for the following Snowplow configuration objects in the mobile SDKs (iOS (Obj-C)/Android (Java)). If not set, the default values are assigned.

NetworkConfiguration

The NetworkConfiguration class can be used to specify the collector endpoint:

objectivec 
// 1
RSNetworkConfiguration *networkConfig = [[RSNetworkConfiguration alloc] initWithDataPlaneUrl:DATA_PLANE_URL];
// 2
RSNetworkConfiguration *networkConfig = [[RSNetworkConfiguration alloc] initWithDataPlaneUrl:DATA_PLANE_URL controlPlaneUrl:CONTROL_PLANE_URL];

SessionConfiguration

The SessionConfiguration class can be used to capture sessions to track the user activity in the app:

objectivec 
RSSessionConfiguration *sessionConfig = [[RSSessionConfiguration alloc] initWithForegroundTimeout:[[NSMeasurement alloc] initWithDoubleValue:30 unit:NSUnitDuration.minutes] backgroundTimeout:[[NSMeasurement alloc] initWithDoubleValue:30 unit:NSUnitDuration.minutes]];

// 2
RSSessionConfiguration *sessionConfig = [[RSSessionConfiguration alloc] initWithForegroundTimeoutInSeconds:60 backgroundTimeoutInSeconds:60];
You need to pass both the arguments for the SessionConfiguration class as shown in the previous code snippets. However, RudderStack ignores the first argument (as it is a placeholder argument) and considers only the second argument (backgroundTimeout).
For mobile SDKs, Snowplow’s default timeout session is 30 minutes whereas RudderStack’s default timeout session is 5 minutes. Refer to the RudderStack Session Tracking documentation for more information.

TrackerConfiguration

The TrackerConfiguration class can be used to configure contexts and automatic events of the tracker and the general behavior, as shown in the following snippets:

objectivec 
RSTrackerConfiguration * trackerConfig = [
  [RSTrackerConfiguration alloc] init
];
[trackerConfig base64Encoding: YES];
[trackerConfig logLevel: LogLevelDebug];
[trackerConfig sessionContext: YES];
[trackerConfig deepLinkContext: YES];
[trackerConfig applicationContext: YES];
[trackerConfig platformContext: YES];
[trackerConfig geoLocationContext: NO];
[trackerConfig screenContext: YES];
[trackerConfig screenViewAutotracking: YES];
[trackerConfig lifecycleAutotracking: YES];
[trackerConfig installAutotracking: YES];
[trackerConfig exceptionAutotracking: YES];
[trackerConfig diagnosticAutotracking: NO];
[trackerConfig userAnonymisation: NO];
[trackerConfig appId: APP_ID];

Snowplow automatically captures and tracks the following data. Refer to the Auto-tracked events and entities section for more information.

Variable name Default value
logLevel LogLevel.OFF
lifecycleAutotracking true
screenViewAutotracking true
sessionContext true
RudderStack ignores any variable other than the ones mentioned above.

SubjectConfiguration

The SubjectConfiguration class can be used to capture basic user information which is attached to all events as the context entity.

Snowplow does not provide any call to identify a user. However, RudderStack sends an call if you initialize the SubjectConfiguration class while initializing the SDK. Note that a user is not identified if the SDK is not initialized.

The userId field is mapped to the RudderStack’s userId. All the other properties are mapped to RudderStack’s traits object.

userId is a mandatory field. If not provided, the identify call is ignored.
objectivec 
RSSubjectConfiguration * subjectConfig = [
  [RSSubjectConfiguration alloc] init
];
[subjectConfig userId: @ "user_id"];
[subjectConfig traits: @ {
  @ "key_1": @ "value_1", @ "key_2": @20, @ "key_3": @YES
}];

Update class names

The following table lists the corresponding class names in Snowplow and RudderStack (mobile SDKs) which need to be updated based on your platform:

Snowplow RudderStack
Java Kotlin Objective-C Swift
NetworkConfiguration NetworkConfiguration NetworkConfiguration RSNetworkConfiguration NetworkConfiguration
TrackerConfiguration TrackerConfiguration TrackerConfiguration RSTrackerConfiguration TrackerConfiguration
SessionConfiguration SessionConfiguration SessionConfiguration RSSessionConfiguration SessionConfiguration
SubjectConfiguration SubjectConfiguration SubjectConfiguration RSSubjectConfiguration SubjectConfiguration
Structured Structured Structured RSStructured Structured
ScreenView ScreenView ScreenView RSScreenView ScreenView
Background Background Background RSBackground Background
Foreground Foreground Foreground RSForeground Foreground
SelfDescribing SelfDescribing SelfDescribing RSSelfDescribing SelfDescribing
SelfDescribingJson SelfDescribingJson SelfDescribingJson RSSelfDescribingJson SelfDescribingJson
TimeMeasure TimeMeasure TimeMeasure N/A N/A
Snowplow RSTracker RSTracker RSTracker RSTracker
LogLevel LogLevel LogLevel LogLevel LogLevel

Send events

Migrate your existing events from Snowplow to RudderStack by following the below sections:

Identify

iOS (Obj-C)/Android (Java)

Snowplow’s SubjectConfiguration class can be used to identify users. See the Setting configuration objects section for more information.

JavaScript

Snowplow supports identifying a user by passing the setUserId method. A Snowplow event including the setUserId method triggers the identify call in the RudderStack JavaScript SDK.

RudderStack supports only the setUserId method of the Snowplow v2 JS tracker.

In the following sample call, alex@example.com is the userId, while firstName, lastName, and city are the user traits.

javascript 
rs.snowplowAdapter('setUserId', 'alex@example.com', {
  firstName: 'Alex',
  lastName: 'Keener',
  city: 'New Orleans'
});

Track

iOS (Obj-C)/Android (Java)

Custom structured events

RudderStack sends a track call for Snowplow events containing the Structured class.

In the following example, RudderStack maps Action_example to the RudderStack event name and the rest of the properties like Category_example, label, value, etc. to the RudderStack properties.

objectivec 
RSStructured * structured = [
  [RSStructured alloc] initWithCategory: @ "Category_example"
  action: @ "Action_example"
];
[structured label: @ "my-label"];
[structured property: @ "my-property"];
[structured value: @5];
[structured properties: @ {
  @ "key_1": @ "value_1", @ "key_2": @ "value_2"
}];

[tracker track: structured];
Custom self-described events

RudderStack sends a track call for Snowplow events containing the SelfDescribing class.

In the following example, RudderStack maps action to the RudderStack event name.

objectivec 
// 1
RSSelfDescribingJson * selfDescribingJson = [
  [RSSelfDescribingJson alloc] initWithSchema: @ "schema"
  andDictionary: @ {
    @ "action": @ "Action_2", @ "key_2": @ "value_2"
  }
];
RSSelfDescribing * selfDescribing = [
  [RSSelfDescribing alloc] initWithEventData: selfDescribingJson
];

// 2
RSSelfDescribing * selfDescribing = [
  [RSSelfDescribing alloc] initWithSchema: @ "schema"
  payload: @ {
    @ "action": @ "Action_2", @ "key_2": @ "value_2"
  }
];

[tracker track: selfDescribing];
action is a mandatory field. RudderStack does not send any call if it is absent.
Custom foreground events

RudderStack sends a track call for Snowplow events containing the Foreground class.

RudderStack sends the event name as Application Opened and maps the rest of the properties like index, properties, etc. to the RudderStack properties.

objectivec 
RSForeground * foreground = [
  [RSForeground alloc] initWithIndex: @1
];
[foreground properties: @ {
  @ "key_1": @ "value_1"
}];

[tracker track: foreground];
This is not a default application lifecycle event. Hence, the properties like version, build, etc. are not present under properties.
Custom background events

RudderStack sends a track call for Snowplow events containing the Background class.

RudderStack sends the event name as Application Backgrounded and maps the rest of the properties, like index, properties, etc. to the RudderStack properties.

objectivec 
RSBackground * background = [
  [RSBackground alloc] initWithIndex: @1
];
[background properties: @ {
  @ "key_1": @ "value_1"
}];

[tracker track: background];
This is not a default application lifecycle event. Hence, the properties like version, build, etc. are not present under properties.

JavaScript

The RudderStack JavaScript SDK supports Snowplow’s trackStructEvent and trackSelfDescribingEvent calls. These Snowplow calls capture user events along with their associated properties and trigger the track call in the RudderStack JavaScript SDK.

A sample trackSelfDescribingEvent call:

javascript 
rs.snowplowAdapter('trackSelfDescribingEvent', {
  event: {
    data: {
      action: 'order completed',
      category: 'FCW',
      product_id: 'P1100DFG9766',
      revenue: 30,
      currency: 'USD',
      user_actual_id: 12345,
    },
  },
});

In the previous code snippet, the trackSelfDescribingEvent method tracks the Order Completed event along with other information like revenue, currency, and user_actual_id, etc.

A sample trackStructEvent call:

javascript 
rs.snowplowAdapter('trackStructEvent', {
  action: 'order completed',
  category: 'FCW',
  label: 'Sample label',
  property: 'Some property',
  value: 40.0,
});

In the previous code snippet, the trackStructEvent method tracks the Order Completed event along with other information like label, property, and value, etc.

The action field is mandatory in both calls.

Track page or screen views

iOS (Obj-C)/Android (Java)

Snowplow’s ScreenView class captures whenever a new screen is loaded. A Snowplow event including the ScreenView class triggers the screen call in the RudderStack iOS (Obj-C) or Android (Java) SDK.

RudderStack maps the name property to RudderStack event name and the rest of the properties, like screenId, previousName, previousId, etc. to the RudderStack properties.

objectivec 
RSScreenView * screen = [
  [RSScreenView alloc] initWithName: @ "DemoScreenName"
  screenId: [
    [NSUUID alloc] init
  ]
];
[screen type: @ "type"];
[screen previousName: @ "previousName"];
[screen previousId: @ "previousId"];
[screen previousType: @ "previousType"];
[screen transitionType: @ "transitionType"];
[screen viewControllerClassName: @ "viewControllerClassName"];
[screen topViewControllerClassName: @ "topViewControllerClassName"];
[screen properties: @ {
  @ "key_1": @ "value_1",
    @ "key_2": @ "value_2"
}];

[tracker track: screen];

JavaScript

Snowplow’s trackPageView call lets you record your website’s page views with any additional relevant information about the viewed page. A Snowplow event including the trackPageView call triggers the screen call in the RudderStack JavaScript SDK.

A sample trackPageView call:

javascript 
rs.snowplowAdapter(
  'trackPageView',
  {
    title: 'Cart Viewed',
  },
  {
    path: '/best-seller/1',
    referrer: 'https://www.google.com/search?q=estore+bestseller',
    search: 'estore bestseller',
    title: 'The best sellers offered by EStore',
    url: 'https://www.estore.com/best-seller/1',
  },
);

In the previous code snippet, the SDK captures the page title and other contextual information.