Migrating from Snowplow to RudderStack Beta

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 Cloud.
  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.

Update your SDK implementation

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

Android

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:
buildscript {
  repositories {
    mavenCentral()
  }
}
allprojects {
  repositories {
    mavenCentral()
  }
}
  1. Add the following dependency under dependencies section in your app/build.gradle file:
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.
info
Refer to the Setting the configuration objects section for more information on using these configuration objects.

iOS

Follow these steps to migrate to the RudderStack iOS SDK:

  1. Add the SDK to your Podfile:
pod 'RudderSnowplowMigrator', '1.0.0.beta.1'
  1. Run the following command:
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:
  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.
info
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.

<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 propertyRudderStack property
cookieDomainsetCookieDomain
cookieSameSitesameSiteCookie
cookieSecuresecureCookie

Setting configuration objects for mobile SDKs

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

NetworkConfiguration

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

info
If not set, the default values for dataPlaneUrl and controlPlaneUrl are taken as https://hosted.rudderlabs.com and https://api.rudderlabs.com respectively.

SessionConfiguration

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

warning
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).
info
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:

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

Variable nameDefault value
logLevelLogLevel.OFF
lifecycleAutotrackingtrue
screenViewAutotrackingtrue
sessionContexttrue
warning
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.

warning
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.

warning
userId is a mandatory field. If not provided, the identify call is ignored.

Updating 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:

SnowplowRudderStack
JavaKotlinObjective-CSwift
NetworkConfigurationNetworkConfigurationNetworkConfigurationRSNetworkConfigurationNetworkConfiguration
TrackerConfigurationTrackerConfigurationTrackerConfigurationRSTrackerConfigurationTrackerConfiguration
SessionConfigurationSessionConfigurationSessionConfigurationRSSessionConfigurationSessionConfiguration
SubjectConfigurationSubjectConfigurationSubjectConfigurationRSSubjectConfigurationSubjectConfiguration
StructuredStructuredStructuredRSStructuredStructured
ScreenViewScreenViewScreenViewRSScreenViewScreenView
BackgroundBackgroundBackgroundRSBackgroundBackground
ForegroundForegroundForegroundRSForegroundForeground
SelfDescribingSelfDescribingSelfDescribingRSSelfDescribingSelfDescribing
SelfDescribingJsonSelfDescribingJsonSelfDescribingJsonRSSelfDescribingJsonSelfDescribingJson
TimeMeasureTimeMeasureTimeMeasureN/AN/A
SnowplowRSTrackerRSTrackerRSTrackerRSTracker
LogLevelLogLevelLogLevelLogLevelLogLevel

Sending event data

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

Identifying a user

iOS/Android

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.

info
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.

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

Tracking user actions

iOS/Android

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.

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.

info
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.

info
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.

info
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:

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:

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.

info
The action field is mandatory in both calls.

Tracking page or screen views

iOS/Android

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 or Android 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.

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:

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.


Questions? Contact us by email or on Slack