This guide is designed to help you migrate from Segment to mParticle. At a high level, both mParticle and Segment support:
Additionally, the mParticle APIs and event models are similar to Segment’s with many overlapping concepts and expectations, making for a straightforward migration.
Both Segment and mParticle support JSON-based server-side (S2S) APIs, with some high-level differences:
Component | Segment |
mParticle |
---|---|---|
S2S Endpoints | Separate identify , track , and page endpoints |
A single /events and /bulkevents endpoint which combines these concepts |
S2S Authentication | Basic authentication with “write key” and no password | Basic authentication with API key and secret as username and password |
Use the JSON snippets throughout this guide to map your Segment implementation to mParticle’s analagous APIs.
The mParticle server-side API supports two core endpoints:
https://s2s.mparticle.com/v2/events
: This endpoint receives an array of events, attributes, and identities for a single user.https://s2s.mparticle.com/v2/bulkevents
: This endpoint receives an array of the same payload as above, so that you can transmit many users at one.If you prefer to use a library rather than a direct JSON implementation, mParticle has several open-source SDKs built for the server-side API:
If you would like to backfill your data into the mParticle Identity, Profile, and Audience systems, use the historical endpoint.
mParticle offers open-source SDKs for many client-side platforms and frameworks:
Use the following iOS and Android sections to map your Segment SDK implementation to mParticle.
To update your iOS app build, update your preferred package manager.
Package Manager | Segment | mParticle |
---|---|---|
Cocoapods | pod 'Analytics' |
pod 'mParticle-Apple-SDK' |
Carthage | github "segmentio/analytics-ios" |
github "mparticle/mparticle-apple-sdk" |
SPM | git@github.com:segmentio/analytics-ios.git |
git@github.com:mParticle/mparticle-apple-sdk.git |
Both Segment and mParticle are initialized on app startup with your API credentials.
let configuration = AnalyticsConfiguration(writeKey: "YOUR_WRITE_KEY")
configuration.trackApplicationLifecycleEvents = true
configuration.recordScreenViews = true
Analytics.setup(with: configuration)
SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY"];
configuration.trackApplicationLifecycleEvents = YES;
configuration.recordScreenViews = YES;
[SEGAnalytics setupWithConfiguration:configuration];
let options = MParticleOptions(key: "APP KEY",
secret: "APP SECRET")
MParticle.sharedInstance().start(with: options)
MParticleOptions *options = [MParticleOptions optionsWithKey:@"APP KEY"
secret:@"APP SECRET"];
[[MParticle sharedInstance] startWithOptions:options];
Both Segment and mParticle publish to Maven Central. The following snippet shows how to update your Gradle build to use mParticle’s SDK:
dependencies {
//Segment
implementation 'com.segment.analytics.android:analytics:4.+'
//mParticle
implementation 'com.mparticle:android-core:5+'
}
Just as with Segment, you can quickly initialize the mParticle SDK on app startup with your API credentials.
Analytics analytics = new Analytics.Builder(context, YOUR_WRITE_KEY)
.trackApplicationLifecycleEvents()
.recordScreenViews()
.build();
Analytics.setSingletonInstance(analytics);
val options = MParticleOptions.builder(this)
.credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
.build()
MParticle.start(options)
MParticleOptions options = MParticleOptions.builder(this)
.credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
.build();
MParticle.start(options);
Segment and mParticle enable you to associate data with users and their devices via similar identify concepts.
HTTP Endpoint: POST https://api.segment.io/v1/identify
{
"userId": "019mr8mf4r",
"traits": {
"email": "pgibbons@example.com",
"name": "Peter Gibbons"
},
"context": {
"ip": "24.5.68.47"
},
"timestamp": "2012-12-02T00:30:08.276Z"
}
//Android SDK
Analytics.with(context)
.identify("019mr8mf4r", new Traits()
.putName("Peter Gibbons")
.putEmail("pgibbons@example.com"));
//iOS SDK
Analytics.shared()
.identify("019mr8mf4r",
traits: ["email": "pgibbons@example.com", "name": "Peter Gibbons"])
//iOS SDK
[[SEGAnalytics sharedAnalytics] identify:@"019mr8mf4r"
traits:@{ @"name": @"Peter Gibbons",
@"email": @"pgibbons@example.com"}];
In addition to identify
, mParticle also supports login
, logout
, and modify
. Reference the code below for a basic migration guide, and navigate to the mParticle Identity Guide to learn more.
HTTP Endpoint: POST https://s2s.mparticle.com/v2/events
{
"user_identities": {
"customer_id": "019mr8mf4r",
"email": "pgibbons@example.com"
},
"user_attributes": {
"name": "Peter Gibbons",
},
"ip": "24.5.68.47",
"timestamp_unixtime_ms":1634262037939,
"environment": "production"
}
//Android SDK
val request = IdentityApiRequest.withEmptyUser().run {
email("pgibbons@example.com")
customerId("019mr8mf4r")
build()
}
MParticle.getInstance().Identity().identify(request)
val currentUser = MParticle.getInstance().Identity().currentUser
currentUser?.setUserAttribute("name", "Peter Gibbons")
//Android SDK
IdentityApiRequest request = IdentityApiRequest.withEmptyUser()
.email("pgibbons@example.com")
.customerId("019mr8mf4r")
.build();
MParticle.getInstance().Identity().identify(request);
MParticleUser currentUser = MParticle.getInstance().Identity().getCurrentUser();
currentUser.setUserAttribute("name", "Peter Gibbons");
//iOS SDK
var identityRequest = MPIdentityApiRequest.withEmptyUser()
identityRequest.email = "pgibbons@example.com"
identityRequest.customerId = "019mr8mf4r"
MParticle.sharedInstance().identity.identify(request, completion: identityCallback)
//iOS SDK
MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];
request.email = @"pgibbons@example.com";
request.customerId = @"019mr8mf4r";
[[[MParticle sharedInstance] identity] identify:request
completion:identityCallback];
Segment supports a single track
call that accepts only one event structure, while mParticle has both a generic Custom Event as well as several pre-defined structures for different domains such as Commerce. These features allows mParticle to more deterministically map data to downstream integrations.
HTTP Endpoint: POST https://api.segment.io/v1/track
{
"userId": "019mr8mf4r",
"event": "Item Purchased",
"properties": {
"name": "Leap to Conclusions Mat",
"revenue": 14.99
},
"context": {
"ip": "24.5.68.47"
},
"timestamp": "2012-12-02T00:30:12.984Z"
}
//Android SDK
Analytics.with(context)
.identify("019mr8mf4r", new Traits()
.putName("Peter Gibbons")
.putEmail("pgibbons@example.com"));
//iOS SDK
Analytics.shared()
.identify("019mr8mf4r",
traits: ["email": "pgibbons@example.com", "name": "Peter Gibbons"])
//iOS SDK
[[SEGAnalytics sharedAnalytics] identify:@"019mr8mf4r"
traits:@{ @"name": @"Peter Gibbons",
@"email": @"pgibbons@example.com"}];
HTTP Endpoint: POST https://s2s.mparticle.com/v2/events
The following examples illustrate two core event types: Custom Event and Commerce Event. Depending on the type of event that you’re migrating from your Segment track
call, use either a Custom Event or a Commerce Event:
{
"user_identities": {
"customer_id": "019mr8mf4r"
},
"events": [
{
"data": {
"event_name": "clicked button",
"custom_attributes": {
"button_name": "home",
}
},
"event_type": "custom_event"
},
{
"data": {
"product_action": {
"action": "purchase",
"total_amount": 14.99,
"products": [
{
"name": "Leap to Conclusions Mat"
}
]
},
"custom_attributes": {}
},
"event_type": "commerce_event"
}
],
"ip": "24.5.68.47",
"timestamp_unixtime_ms": 1634262037939,
"environment": "production"
}
//Android SDK
//Custom Event
val customAttributes = mapOf(
"category" to "Destination Intro",
"title" to "Paris"
)
val event = MPEvent.Builder("Video Watched", EventType.Navigation)
.customAttributes(customAttributes)
.build()
MParticle.getInstance().logEvent(event)
//Commerce Event
// 1. Create the products
val product = Product.Builder("Double Room - Econ Rate", "econ-1", 100.00)
.quantity(4.0)
.build()
// 2. Summarize the transaction
val attributes = TransactionAttributes("foo-transaction-id")
.setRevenue(430.00)
.setTax(30.00)
// 3. Log the purchase event
val event = CommerceEvent.Builder(Product.PURCHASE, product)
.transactionAttributes(attributes)
.build()
MParticle.getInstance().logEvent(event)
//Android SDK
//Custom Event
Map<String, String> customAttributes = new HashMap<String, String>();
customAttributes.put("category", "Destination Intro");
customAttributes.put("title", "Paris");
MPEvent event = new MPEvent.Builder("Video Watched", EventType.Navigation)
.customAttributes(customAttributes)
.build();
MParticle.getInstance().logEvent(event);
//Commerce Event
// 1. Create the products
Product product = new Product.Builder("Double Room - Econ Rate", "econ-1", 100.00)
.quantity(4.0)
.build();
// 2. Summarize the transaction
TransactionAttributes attributes = new TransactionAttributes("foo-transaction-id")
.setRevenue(430.00)
.setTax(30.00);
// 3. Log the purchase event
CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
.transactionAttributes(attributes)
.build();
MParticle.getInstance().logEvent(event);
//iOS SDK
//Custom Event
if let event = MPEvent(name: "Video Watched", type: MPEventType.navigation) {
event.customAttributes = ["category": "Destination Intro", "title": "Paris"]
MParticle.sharedInstance().logEvent(event)
}
//Commerce Event
// 1. Create the products
let product = MPProduct.init(name: "Foo name",
sku: "Foo sku",
quantity: 4,
price: 100.00)
// 2. Summarize the transaction
let attributes = MPTransactionAttributes.init()
attributes.transactionId = "foo-transaction-id"
attributes.revenue = 430.00
attributes.tax = 30.00
// 3. Log the purchase event
let action = MPCommerceEventAction.purchase;
let event = MPCommerceEvent.init(action: action, product: product)
event.transactionAttributes = attributes
MParticle.sharedInstance().logEvent(event)
//iOS SDK
//Custom Event
MPEvent *event = [[MPEvent alloc] initWithName:@"Video Watched"
type:MPEventTypeTransaction];
event.customAttributes = @{@"category":@"Destination Intro",
@"title":@"Paris"};
[[MParticle sharedInstance] logEvent:event];
//Commerce Event
// 1. Create the products
MPProduct *product = [[MPProduct alloc] initWithName:@"Double Room - Econ Rate"
sku:@"econ-1"
quantity:@4
price:@100.00];
// 2. Summarize the transaction
MPTransactionAttributes *attributes = [[MPTransactionAttributes alloc] init];
attributes.transactionId = @"foo-transaction-id";
attributes.revenue = @430.00;
attributes.tax = @30.00;
// 3. Log the purchase event
MPCommerceEventAction action = MPCommerceEventActionPurchase;
MPCommerceEvent *event = [[MPCommerceEvent alloc] initWithAction:action
product:product];
event.transactionAttributes = attributes;
[[MParticle sharedInstance] logEvent:event];
You can migrate Segment page
calls to the mParticle screen_view
event type.
HTTP Endpoint: POST https://api.segment.io/v1/page
{
"userId": "019mr8mf4r",
"name": "Example page call",
"properties": {
"foo": "bar"
},
"timestamp": "2012-12-02T00:31:29.738Z"
}
//Android SDK
Analytics.with(context).screen("Smartwatches", "Purchase Screen",
Properties().putValue("sku", "13d31"))
//Android SDK
Analytics.with(context)
.screen("Smartwatches", "Purchase Screen",
new Properties().putValue("sku", "13d31"));
//iOS SDK
Analytics.shared().screen("Photo Feed", properties: ["Feed Type": "private"])
//iOS SDK
[[SEGAnalytics sharedAnalytics] screen:@"Photo Feed"
properties:@{ @"Feed Type": @"private" }];
HTTP Endpoint: POST https://s2s.mparticle.com/v2/events
{
"user_identities": {
"customer_id": "019mr8mf4r"
},
"events": [
{
"data": {
"event_name": "Example screen view",
"custom_attributes": {
"foo": "bar"
}
},
"event_type": "screen_view"
}
],
"timestamp_unixtime_ms": 1634262037939,
"environment": "production"
}
//Android SDK
val screenInfo = HashMap<String, String>()
screenInfo["rating"] = "5"
screenInfo["property_type"] = "hotel"
MParticle.getInstance().logScreen("Destination Details", screenInfo)
//Android SDK
Map<String, String> screenInfo = new HashMap<String, String>();
screenInfo.put("rating", "5");
screenInfo.put("property_type", "hotel");
MParticle.getInstance().logScreen("Destination Details", screenInfo);
//iOS SDK
let screenInfo = ["rating": "5", "property_type": "hotel"];
MParticle.sharedInstance().logScreen("Destination Details", eventInfo: screenInfo)
//iOS SDK
NSDictionary *screenInfo = @{@"rating":@"5",
@"property_type":@"hotel"};
[[MParticle sharedInstance] logScreen:@"Destination Details"
eventInfo:screenInfo];
The API mapping guide above is designed to help you assess a basic migration. Both platforms have many APIs and capabilities, so reach out to support@mparticle.com if you have specific questions about your migration.
Was this page helpful?