mParticle

Integrate in-app subscription events from RevenueCat with mParticle

👍

The mParticle integration is available to all users signed up after September '23, the legacy Grow and Pro plans, and Enterprise plans. If you're on a legacy Free or Starter plan and want to access this integration, migrate to our new pricing via your billing settings.

mParticle can be a useful integration tool for seeing all events and revenue that occur for your app even if it’s not active for a period of time. You can use mParticle to clean up your data infrastructure and collect new customer data, which can then be connected with other tools through mParticle’s powerful API.

With our mParticle integration, you can:

  • Use the API to identify users who are at risk of churning and begin a campaign to win them back.
  • Set up push notifications and emails to users who have subscribed to your product but do not engage very much.

With accurate and up-to-date subscription data in mParticle, you'll be set to turbocharge your campaigns ⚡️

Integration at a Glance

Includes RevenueSupports Negative RevenueSends Sandbox EventsIncludes Subscriber AttributesSends Transfer EventsOptional Event Types

Events

The mParticle integration tracks the following events:

EventDefault Event NameDescriptionApp StorePlay StoreAmazonStripePromo
Initial Purchaseinitial_purchaseA new subscription has been purchased.
Trial Startedtrial_startedThe start of an auto-renewing subscription product free trial.
Trial Convertedtrial_convertedWhen an auto-renewing subscription product converts from a free trial to normal paid period.
Trial Cancelledtrial_cancelledWhen a user turns off renewals for an auto-renewing subscription product during a free trial period.
RenewalrenewalAn existing subscription has been renewed or a lapsed user has resubscribed.
CancellationcancellationA subscription or non-renewing purchase has been cancelled. See cancellation reasons for more details.
UncancellationuncancellationA non-expired cancelled subscription has been re-enabled.
Non Subscription Purchasenon_renewing_purchaseA customer has made a purchase that will not auto-renew.
Subscription pausedrc_subscription_paused_eventA subscription has been paused.
ExpirationexpirationA subscription has expired and access should be removed.

If you have Platform Server Notifications configured, this event will occur as soon as we are notified (within seconds to minutes) of the expiration.

If you do not have notifications configured, delays may be approximately 1 hour.
Billing Issuesbilling_issueThere has been a problem trying to charge the subscriber. This does not mean the subscription has expired.

Can be safely ignored if listening to CANCELLATION event + cancel_reason=BILLING_ERROR.
Product Changeproduct_changeA subscriber has changed the product of their subscription.

This does not mean the new subscription is in effect immediately. See Managing Subscriptions for more details on updates, downgrades, and crossgrades.
RefundrefundWhen a user canceled their subscription via customer support

For events that have revenue, such as trial conversions and renewals, RevenueCat will automatically record this amount along with the event in mParticle.

Setup

1. Set mParticle User Identity and Send Device Data to RevenueCat

If you're using the mParticle SDK, you can set the User ID to match the RevenueCat App User Id. This way, events sent from the mParticle SDK and events sent from RevenueCat can be synced to the same user.

The mParticle integration also requires some device-specific data. RevenueCat will only send events into mParticle if the below Subscriber Attributes keys have been set for the device.

KeyDescriptionRequired
$mparticleIdThe unique mParticle user identifier (mpid).✅ (recommended)
$idfaiOS advertising identifier UUID❌ (optional)
$idfviOS vender identifier UUID❌ (optional)
$gpsAdIdGoogle advertising identifier❌ (optional)
$androidIdAndroid device identifier❌ (optional)
$ipThe IP address of the device❌ (optional)

These properties can be set manually, like any other Subscriber Attributes, or through the helper methods collectDeviceIdentifiers() and setMparticleId().

Create an identityRequest and add it to the MParticleOptions that you pass to the start() method on the mParticle SDK to set the same App User Id that is set in RevenueCat.

// Configure Purchases SDK
Purchases.configure(withAPIKey: "public_sdk_key", appUserID: "my_app_user_id")

// Set App User Id in mParticle
let options = MParticleOptions(key: "mParticle_app_key",
                               secret: "mParticle_app_secret")
let identityRequest = MPIdentityApiRequest.withEmptyUser()
identityRequest.email = "[email protected]"
identityRequest.customerId = "123456"
options.identifyRequest = identityRequest
options.onIdentifyComplete = { (result: MPIdentityApiResult?, error: Error?) in
    guard error == nil else {
        // handle error
        return
    }
    guard let result else {
        // handle empty result
        return
    }

    // IMPORTANT: user identified successfully, get the mPID and send to RevenueCat
    let mPid = result.user.userId
    Purchases.shared.attribution.collectDeviceIdentifiers()
    Purchases.shared.attribution.setMparticleID(mPid.stringValue)
}

// Start mParticle
MParticle.sharedInstance().start(with: options)
// Configure Purchases SDK
[RCPurchases configureWithAPIKey:@"public_sdk_key" appUserID:@"my_app_user_id"];


// Set App User Id in mParticle
MParticleOptions *options = [MParticleOptions optionsWithKey:@"mParticle_app_key"
                             secret:@"mParticle_app_secret"];
MPIdentityApiRequest *identityRequest = [MPIdentityApiRequest requestWithEmptyUser];
identityRequest.email = @"[email protected]";
identityRequest.customerId = @"123456";
options.identifyRequest = identityRequest;
options.onIdentifyComplete = ^(MPIdentityApiResult *_Nullable apiResult, NSError *_Nullable error) {
    if (error) {
        // handle error
        return;
    }
    if (apiResult == nil) {
        // handle empty result
        return;
    }
    // user identified successfully, get the mPID and send to RevenueCat
    NSNumber *mPid = [apiResult.user userId];
    [[RCPurchases sharedPurchases] collectDeviceIdentifiers];
    [[RCPurchases sharedPurchases] setMparticleID:mPid.stringValue];
};


// Start mParticle
[[MParticle sharedInstance] startWithOptions:options];
// Configure Purchases SDK
Purchases.configure(this, "my_api_key", "my_app_user_id");


// Set App User Id in mParticle
IdentityApiRequest identityRequest = IdentityApiRequest.withEmptyUser()
    .email("[email protected]")
    .customerId("123456")
    .build();

BaseIdentityTask identifyTask = new BaseIdentityTask()
    .addFailureListener(new TaskFailureListener() {
      @Override
      public void onFailure(IdentityHttpResponse identityHttpResponse) {
        // handle failure
      }
    }).addSuccessListener(new TaskSuccessListener() {
      @Override
      public void onSuccess(IdentityApiResult identityApiResult) {
        // user identified successfully, get the mPID and send to RevenueCat
        long mPid = identityApiResult.getUser().getId();
        Purchases.getSharedInstance().collectDeviceIdentifiers();
        Purchases.getSharedInstance().setMparticleID(String.valueOf(mPid));
      }
    });

MParticleOptions options = MParticleOptions.builder(this)
    .credentials("mParticle_app_key", "mParticle_app_secret")
    .identify(identityRequest)
    .identifyTask(identifyTask)
    .build();


// Start mParticle
MParticle.start(options);

mParticle also allows you to log a user in after starting the SDK and log a user out; you should handle both of these cases:

// handle logging out
MParticle.sharedInstance().identity.logout(completion: { (result: MPIdentityAPIResult?, error: Error?) in
    Purchases.shared().reset()
})
// handle logging out
[[[MParticle sharedInstance] identity] logoutWithCompletion:^(MPIdentityApiResult *_Nullable apiResult, NSError *_Nullable error) {
    [[RCPurchases sharedPurchases] reset];
}];
// handle logging out
MParticle.getInstance().Identity().logout(identityRequest)
    .addFailureListener(new TaskFailureListener() {
        @Override
        public void onFailure(IdentityHttpResponse identityHttpResponse) {
            // handle error
        }
    })
    .addSuccessListener(new TaskSuccessListener() {
        @Override
        public void onSuccess(IdentityApiResult identityApiResult) {
          Purchases.getSharedInstance().reset();
        }
    });
// handle logging in
MParticle.sharedInstance()
         .identity.login(identityRequest, completion: { (result: MPIdentityAPIResult?, error: Error?) in
    guard error == nil else {
        // handle error
        return
    }
    guard let result else {
        // handle empty result
        return
    }
    // user identified successfully, get the mPID and send to RevenueCat
    let mPid = result.user.userId
    Purchases.shared.attribution.collectDeviceIdentifiers()
    Purchases.shared.attribution.setMparticleID(mPid.stringValue)
})
// handle logging in
[[[MParticle sharedInstance] identity] login:identityRequest
                                  completion:^(MPIdentityApiResult *_Nullable apiResult, NSError *_Nullable error) {
    if (error) {
        // handle error
        return;
    }
    if (apiResult == nil) {
        // handle empty result
        return;
    }
    // user identified successfully, get the mPID and send to RevenueCat
    NSNumber *mPid = [apiResult.user userId];
    [RCPurchases shared] collectDeviceIdentifiers];
    [RCPurchases shared] setMparticleID: [mPid stringValue]];
}];
// handle logging in
MParticle.getInstance().Identity().login(identityRequest)
    .addFailureListener(new TaskFailureListener() {
        @Override
        public void onFailure(IdentityHttpResponse identityHttpResponse) {
            // handle error
        }
    })
    .addSuccessListener(new TaskSuccessListener() {
        @Override
        public void onSuccess(IdentityApiResult identityApiResult) {
          // user identified successfully, get the mPID and send to RevenueCat
        	long mPid = identityApiResult.getUser().getId();
        	Purchases.getSharedInstance().collectDeviceIdentifiers();
          Purchases.getSharedInstance().setMparticleID(String.valueOf(mPid));
        }
    });

❗️

Device identifiers with iOS App Tracking Transparency (iOS 14.5+)

If you are requesting the App Tracking permission through ATT to access the IDFA, you can call .collectDeviceIdentifiers() again if the customer accepts the permission to update the $idfa attribute in RevenueCat.

2. Add RevenueCat Feed Inputs in mParticle

In mParticle, add the RevenueCat feed input and create two feeds: one for the Android platform and one for the iOS platform. Copy each feed's Server to Server Key and Server to Server Secret for setup on RevenueCat. Refer to mParticle's documentation to learn more about feeds.

3. Send RevenueCat events to mParticle

After you've set up the Purchases SDK and mParticle SDK to have the same user identity, you can "turn on" the integration and configure the event names from the RevenueCat dashboard.

  1. Navigate to your project in the RevenueCat dashboard and find the Integrations card in the left menu. Select + New

  1. Choose mParticle from the Integrations menu
  2. Add your Server to Server Keys and Server to Server Secrets for each platform from step 2
  3. Enter the event names that RevenueCat will send or choose the default event names
  4. Select whether you want sales reported as gross revenue (before app store commission), or after store commission and/or estimated taxes.

4. Testing the mParticle integration

You can test the mParticle integration end-to-end before going live. It's recommended that you test the integration is working properly for new users, and any existing users that may update their app to a new version.

Make a sandbox purchase with a new user

Simulate a new user installing your app, and go through your app flow to complete a sandbox purchase.

Check that the required device data is collected

Navigate the the Customer View for the test user that just made a purchase. Make sure that all of the required data from step 1 above is listed as attributes for the user.

Check that the mParticle event delivered successfully

While still on the Customer View, click into the test purchase event in the Customer History and make sure that the mParticle integration event exists and was delivered successfully.

👍

You've done it!

You should start seeing events from RevenueCat appear in mParticle

Sample Events

Below are sample JSONs that are delivered to mParticle for the different event types.

{
    "events": [
        {
            "data": {
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1640653937777,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "initial_purchase"
                },
                "product_action": {
                    "action": "purchase",
                    "transaction_id": "GPA.1234-5678-9012-34567",
                    "total_amount": 5.99,
                    "products": [
                        {
                            "id": "weekly_sub",
                            "price": 5.99,
                            "quantity": 1,
                            "total_product_amount": 5.99
                        }
                    ]
                },
                "currency_code": "USD",
                "is_non_interactive": false
            },
            "event_type": "commerce_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "GB",
        "revenuecat_$ip": "123.45.67.89",
        "revenuecat_$appsflyerId": "1234567890123-1234567890123456789",   
        "revenuecat_$onesignalId": "1234567890123-1234567890123456789",   
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "Android",
        "android_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
        "os": "Android"
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "trial_started",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1593506190000,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "trial_started"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "MD",
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012",
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1593505191000,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "trial_converted"
                },
                "product_action": {
                    "action": "purchase",
                    "transaction_id": "123456789012345",
                    "total_amount": 5.99,
                    "products": [
                        {
                            "id": "weekly_sub",
                            "price": 5.99,
                            "quantity": 1,
                            "total_product_amount": 5.99
                        }
                    ]
                },
                "currency_code": "USD",
                "is_non_interactive": true
            },
            "event_type": "commerce_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "DE",
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "trial_cancelled",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1593505162390,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "trial_cancelled"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "GB",
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1593514136000,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "renewal"
                },
                "product_action": {
                    "action": "purchase",
                    "transaction_id": "123456789012345",
                    "total_amount": 5.99,
                    "products": [
                        {
                            "id": "weekly_sub",
                            "price": 5.99,
                            "quantity": 1,
                            "total_product_amount": 5.99
                        }
                    ]
                },
                "currency_code": "USD",
                "is_non_interactive": true
            },
            "event_type": "commerce_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "FR",
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "cancellation",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1593507675551,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "cancellation"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "RU",
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "uncancellation",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1657090180007,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "uncancellation"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "US",
        "revenuecat_$ip": "123.45.67.89",
        "revenuecat_$appsflyerId": "1234567890123-1234567890123456789",   
        "revenuecat_$onesignalId": "1234567890123-1234567890123456789",   
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
        "os": "IOS"
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "expiration",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1643111704000,
                "custom_attributes": {
                    "revenuecat_expiration_reason": "UNSUBSCRIBE",
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "expiration"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "AU",
        "revenuecat_$ip": "123.45.67.89",
        "revenuecat_$appsflyerId": "1234567890123-1234567890123456789",   
        "revenuecat_$onesignalId": "1234567890123-1234567890123456789",   
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
        "os": "iOS"
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "billing_issue",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1643386961344,
                "custom_attributes": {
                    "revenuecat_product_id": "weekly_sub",
                    "revenuecat_event": "billing_issue"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "US",
        "revenuecat_$ip": "123.45.67.89",
        "revenuecat_$appsflyerId": "1234567890123-1234567890123456789",   
        "revenuecat_$onesignalId": "1234567890123-1234567890123456789",   
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
        "os": "iOS"
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}
{
    "events": [
        {
            "data": {
                "event_name": "product_change",
                "custom_event_type": "transaction",
                "source_message_id": "12345678-1234-1234-1234-123456789012",
                "timestamp_unixtime_ms": 1642376571000,
                "custom_attributes": {
                    "revenuecat_new_product_id": "weekly_sub",
                    "revenuecat_product_id": "monthly_sub",
                    "revenuecat_event": "product_change"
                }
            },
            "event_type": "custom_event"
        }
    ],
    "source_request_id": "12345678-1234-1234-1234-123456789012",
    "user_attributes": {
        "$country": "US",
        "revenuecat_$ip": "123.45.67.89",
        "revenuecat_$appsflyerId": "1234567890123-1234567890123456789",   
        "revenuecat_$onesignalId": "1234567890123-1234567890123456789",   
        "revenuecat_aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "revenuecat_app_user_id": "123456789",
        "revenuecat_original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c"
    },
    "device_info": {
        "platform": "iOS",
        "ios_advertising_id": "12345678-1234-1234-1234-123456789012"
    },
    "application_info": {
        "application_name": "App_Name",
        "package": "co.appname",
        "os": "iOS"
    },
    "user_identities": {},
    "schema_version": 2,
    "environment": "production",
    "mpid": "12345678"
}