Event

This section describes the configuration settings necessary to activate mParticle’s event tracking integration with Facebook. The event tracking integration enables conversion tracking for Facebook advertising campaigns.

Supported Features

• Event Forwarding

Data Processing Notes

Facebook has limits around the number of unique event names and attributes their platform can process as noted here: https://developers.facebook.com/docs/reference/android/current/class/AppEventsLogger/

• 1000 unique event names
• 25 attributes per event
• Between 2 and 40 characters in an event name and attribute
• It may takes up to 24 hours to see refreshed stats in Facebook Analytics

Prerequisites

Event data from mParticle to Facebook is typically sent server side. However, Web data can be sent client or server side based on your implementation and settings. These different options require different settings:

• iOS, tvOS, and Android - data is sent S2S, and you’ll need your app’s Facebook Application ID and Application Secret
• Data Feeds - data is sent S2S, and you’ll need your Facebook Pixel ID
• Web - for client side kit, you’ll need your Facebook Pixel ID
• Web - for S2S, you’ll need your Facebook Pixel ID and Facebook Marketing API Access Token. You also need to enable both the Use Pixel Server-Side Forwarding and Forward Web Requests Server Side settings.
• Roku, Xbox, SmartTV, FireTV, Alexa - you’ll need your Facebook Pixel ID and Facebook Marketing API Access Token.
• os_version is required for iOS/tvOS events. If os_version is not present, the event will be rejected and an error message will be shown in System Alerts.

Configuring Facebook Pixel Server-to-Server

You need to perform a few steps in Facebook to create a Facebook Pixel S2S connection.

1. Navigate to the Facebook Events Manager
2. Connect a New Data Source: Select Web with a connection method of Conversions API.
3. Create an Access Token: Open the settings for the new Pixel Data Source, scroll to the Conversions API > Set up manually section and click Create Access Token. Follow the steps described and copy the Access Token for setup in mParticle.

Configuring Duplicate Events

Facebook recommends sending the same pixel event twice - once from the browser and once from the server. If done incorrectly, this can result in duplicate events appearing in Facebook. The following steps walk through how to configure this within mParticle.

Using only the mParticle Web SDK (Recommended)

To do this using mParticle, you will need to perform the following steps:

1. Setup the mParticle Web SDK in your application
2. Setup two configurations for mParticle’s Facebook integration. One of these configurations must have Use Pixel Server-Side Forwarding enabled and the other must not. Both must have an access token set.
3. Connect both of these configurations to your Web input. The configuration with server-side Pixel forwarding enabled, must also have Forward Web Requests Server Side enabled. Similarly, the connection with Pixel server-side forwarding disabled, must have Forward Web Requests Server Side disabled.

Other Scenarios

Ideally, all Web data sent to mParticle will be sent through the mParticle Web SDK, but it is still possible to deduplicate events outside of this flow if necessary. To ensure redundant events sent through Facebook Pixel and the Facebook Conversions API are correctly deduplicated when they reach Facebook, two conditions must be met:

• Events must have consistent event_name values.
• Events must have consistent event_id values. For this, the field source_message_id may be used to manually set the Event ID sent to Facebook.

If you use the mParticle Web SDK and server-side web integration, then this will be automatically handled.

If you need to manually assign a source_message_id via the web SDK and server-side separately, use the following API:

mParticle.logBaseEvent({
    messageType: 4, // This is the messageType for custom events.  Use 3 for page views
    name: 'Test Event',
    data: {attr1: 'value1'}, // custom attributes
    eventType: mParticle.EventType.Navigation, // optional for custom events. Do not set for page views
    customFlags: {flag1: 'flagValue1'},
    sourceMessageId: 'custom_source_message_id'
});

You can also assign a source_message_id to commerce events:

// 1. Create the product

const product1 = mParticle.eCommerce.createProduct(
    'Double Room - Econ Rate',  // Name
    'econ-1',                   // SKU
    100.00,                     // Price
    4,                          // Quantity
);

// 2. Summarize the transaction
const transactionAttributes = {
    Id: 'foo-transaction-id',
    Revenue: 430.00,
    Tax: 30
};

// 3. Log the purchase event
// Optional custom attributes for a product action can be defined as key/value pairs witin an object
const customAttributes = {
    'sale': true
};

// Optional custom flags can be defined as key/value pairs within an object
const customFlags = {
    'Google.Category': 'travel'
};

const options = {
    sourceMessageId: 'custom_source_message_id'
}

mParticle.eCommerce.logProductAction(
    mParticle.ProductActionType.Purchase,
    [product1],
    customAttributes,
    customFlags,
    transactionAttributes,
    options
);

Note that your workspace will need to be on event batching in order to leverage passing a custom source_message_id to the Web SDK for this to work. If you are not on web batching, please contact your customer success manager.

Visit the Facebook Business Help Center and Facebook For Developers for more information on the subject of deduplication.

Troubleshooting Facebook Pixel Issues

Please run through the following steps to confirm your settings are correct:

• Verify your access token is of type System User and will never expire using this page: https://developers.facebook.com/tools/debug/accesstoken/
• Verify your Pixel ID is valid using this page. Please enter the ID and confirm the Send To Test Events works: https://developers.facebook.com/docs/marketing-api/conversions-api/payload-helper/

If you run into issues with either of the above steps, please repeat the steps described in Configuring Facebook Pixel Server-to-Server.

Event Data Mapping

• The iOS/tvOS and Android integrations forward App State Transition, Commerce, Custom, Screen View, and Session Start events.
• The Web integration forwards Commerce, Custom, Screen View, and Session Start / End events.

iOS14 Update for Device Data Mapping

The Facebook advertiser_tracking_enabled field is set based on the att_authorization_status and limit_ad_tracking fields as defined below. Check the iOS14 Implementation guide for more information.

If att_authorization_status is available:

If att_authorization_status is not available, the limit_ad_tracking field is evaluated:

User Data Mappings

mParticle will send a variety of user data fields to Facebook for advanced matching. The specific fields sent depends on if Facebook Pixel server-side forwarding is enabled or not.

Facebook Pixel Server-Side Forwarding Disabled

mParticle will hash and send the following fields to Facebook when they are set for a user.

Facebook Pixel Server-Side Forwarding Enabled

Custom Mappings

mParticle’s Facebook integration supports custom mappings which allows you to map your events and attributes for Facebook. mParticle provides mappings for the following Facebook event types:

fb_content_type

When setting up the custom mappings, the fb_content_type can provide additional information on the event to be used for Collaborative Ads. The acceptable values for fb_content_type are:

• product
• product_group
• destination
• flight
• hotel
• vehicle
• [“product”, “local_service_business”]

If a value provided for fb_content_type is not in the above list, the value sent will be product.

Product Events

mParticle forwards the mParticle product events Added to Cart and Added to Wishlist to Facebook using Facebook’s corresponding pre-defined event names. mParticle Product Views are forwarded to Facebook as the pre-defined event “Viewed Content”. The unit price, currency, product category, and SKU are passed to Facebook as well. See below for a sample Added to Cart event call using the Facebook SDK, and an equivalent call using the mParticle SDK.

//Facebook SDK call
[FBAppEvents logEvent:FBAppEventNameAddedToCart
           valueToSum:54.23
           parameters:@{ FBAppEventParameterNameCurrency    : @"USD",
                         FBAppEventParameterNameContentType : @"shoes",
                         FBAppEventParameterNameContentID   : @"HDFU-8452" } ];

//Equivalent mParticle SDK call
MPProduct *product = [[MPProduct alloc] initWithName:@"A Shoe"
                                            category:@"shoes"
                                            quantity:1
                                       revenueAmount:54.23];
product.unitPrice = 54.23;
product.sku = @"HDFU-8452";

[[MParticle sharedInstance] logProductEvent:MPProductEventAddedToCart product:product];

//Facebook SDK call
Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "shoes");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, "HDFU-8452");

logger.logEvent(AppEventsConstants.EVENT_NAME_ADDED_TO_CART,
        54.23,
        parameters);

//Equivalent mParticle SDK call
MPProduct product = new MPProduct.Builder("A Shoe", "HDFU-8452")
    .quantity(1)
    .unitPrice(54.23)
    .totalRevenue(54.23)
    .productCategory("shoes")
    .currencyCode("USD")
    .build();
mp.logProductEvent(MPProduct.Event.ADD_TO_CART, product);

Purchase Events

Purchase events logged through mParticle’s eCommerce SDK methods will be forwarded to Facebook using Facebook’s “Purchased” pre-defined event name.

Custom Events

All custom app events, which are logged via mParticle’s logEvent SDK method, will be forwarded to Facebook as custom app events, using the event name passed to mParticle’s logEvent SDK method.

//Facebook SDK call
[FBAppEvents logEvent:@"battledAnOrc"];

//Equivalent mParticle SDK call
[[MParticle sharedInstance] logEvent:@"battledAnOrc"];

//Facebook SDK call
logger.logEvent("battledAnOrc");

//Equivalent mParticle SDK call
mp.logEvent("battledAnOrc");

Screen Views

For the Web platform, mParticle will forward screen views as ‘PageView’ events.

• Note: This also applies to Pixel server-side forwarding.

For the iOS/tvOS and Android platforms, screen views are supported by custom mappings. Reference the custom mappings section for more.

Web Server-to-Server Fields

There are several fields only accepted by server-to-server Web connections. These fields and the mParticle fields they are set from are listed below:

*Custom data fields can also be set via custom mappings or E-Commerce event fields. See the relevant sections for more details.

Configuration Settings

Connection Settings