Marketing API Version

Dynamic Product Ads for Mobile Apps - Quick Start

Get started on setting up Dynamic Product Ads using the Facebook Mobile SDK.

We also strongly recommend you incorporate deep linking and defferred deep linking into your app to provide people using your app with the best experience possible.

  1. Setup Facebook Mobile SDK for iOS/Android
  2. Setup Mobile App Events
  3. Setup Deep Linking
  4. Setup Product Feed
  5. Tracking specs

1. Setup Facebook Mobile SDK for iOS/Android

The first step is to integrate Facebook SDK for iOS/Android, use the following guide to get started.

Facebook SDK for iOS - Getting StartedFacebook SDK for Android - Getting Started

2. Setup Mobile App Events

On the web we used Facebook pixel events (ViewContent, AddToCart, Purchase) for tracking events interactions. On mobile we can track the same events with App Events.

The same three required events (ViewContent, AddToCart, Purchase) that are sent from the Facebook pixel need to also be sent from the app.

Dynamic Product Ads requires three events in order to work correctly.

iOS Event Android Event Web Equivalent

FBSDKAppEventNameViewedContent

AppEventsConstants:: EVENT_NAME_VIEWED_CONTENT

ViewContent

FBSDKAppEventNameAddedToCart

AppEventsConstants:: EVENT_NAME_ADDED_TO_CART

AddToCart

[FBSDKAppEvents logPurchase:(double) currency:(NSString *) parameters:(NSDictionary *)];

AppEventsConstants:: EVENT_NAME_PURCHASED

Purchase

Below is an example of a ViewContent event being fired when someone views a product within an app.

[FBSDKAppEvents logEvent:FBSDKAppEventNameAddedToCart
  valueToSum:54.23
  parameters:@{
    FBSDKAppEventParameterNameCurrency    : @"USD",
    FBSDKAppEventParameterNameContentType : @"product",
    FBSDKAppEventParameterNameContentID   : @"123456789"
  }
];
Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "product");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, "1234");

logger.logEvent(AppEventsConstants.EVENT_NAME_VIEWED_CONTENT,
                120.00,
                parameters);

NOTE For iOS: You must always provide FBSDKAppEventParameterNameContentType and FBSDKAppEventParameterNameContentID for all events otherwise these will not be considered for DPA. Possible values for FBSDKAppEventParameterNameContentType is product or product_group.

NOTE For Android: You must always provide AppEventsConstants.EVENT_PARAM_CONTENT_TYPE and AppEventsConstants.EVENT_PARAM_CONTENT_ID for all events otherwise these will not be considered for DPA. Possible values for AppEventsConstants.EVENT_PARAM_CONTENT_TYPE is product or product_group.

The product ID field can also take a JSON array of values for when an event should occur for multiple products, such as with the Purchase event.

[FBSDKAppEvents logPurchase:54.23 currency:@"USD" parameters:@{
  FBSDKAppEventParameterNameContentID   : @"["1234","5678"]",
  FBSDKAppEventParameterNameContentType : @"product"
  }
];
Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "product");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, "['1234', '5678']");

logger.logEvent(AppEventsConstants.EVENT_NAME_PURCHASED,
                180.00,
                parameters);

Multiple content IDs

if you have multiple content IDs, you should provided these in an escaped json array e.g.

"[\"1234\",\"5678\"]"

Optional Parameters

For every app events, you can send additional parameters, and it is strongly recommended that you send this when a purchase is made.

Field Name Description Type Required

_valueToSum

The value of the product of purchase amount

string

no

fb_currency

The currency of the product or purchase amount

string

no

Testing App Events

The easiest way to test that your integration is correct is to use the App Ads Helper which lets you see the events and paramters being reported by your event in realtime.

After selecing an app, you will see two tools at the bottom of the page. Select "Test App Events":

This will present you a modal window with two options allowing you to choose to either see events being reported by you or by a specific Advertising ID. In most cases, selecting "Me" will be sufficient. You should make sure you have Facebook installed on your device and that you are logged in.

As you perform actions in your app, you should see events appear within the tool, along with their parameters.

In the app ads helper, you should see the following three event names if your integration is successful:

App Ads Helper Event Names

FB_MOBILE_CONTENT_VIEW

FB_MOBILE_ADD_TO_CART

FB_MOBILE_PURCHASE

Learn more about iOS and Android app events.

To ensure your app events are being sent correctly, you can check your recent events in Facebook Analytics for Apps.

3. Setup Deep Linking

By providing deep links in your product feed, users who interact with your ad on Facebook can be sent directly into a specific location of your app if deep linking has been set up. For instance, clicking a dynamic product ad from the Facebook mobile app would open that product directly in your mobile app.

Fallback to Web vs Appstore

If you're creating Dynamic Product Ads with deeplink support, you have the ability to specify the fallback behavior if the user does not have the app installed on their phone. If deep links are present in your product feed, the default behavior will send users to the web url for the product in the ad.

Since the objective of remarketing is to increase catalog sales, it's recommended to fallback to sending users to product pages, rather than app installs. This is why we default to web urls, though you can specify the fallback behavior for more control.

Deep Link Fallback Behavior

The fallback behavior for someone who does not have the app installed can be set using the applink_treatment field when creating a Dynamic Product Ad.

The following fallback options are available:

Field Name Description

web_only

Always send the user to the given web URL. This will override any deeplinks in the feed.

deeplink_with_web_fallback

If the app is installed on the user's phone and we have corresponding deep link information, send the user to the app. If one of these conditions is not met, send them to the website url for product.

deeplink_with_appstore_fallback

If the app is installed on the user's phone and we have corresponding deep link information, send the user to the app. If the app is not installed, send them to the app store for the app.

4. Setup Product Feed

Once deep linking has been set up you will need to setup the deep links for your dynamic ads, follow the specifications listed on the Product Catalog set up page.

5. Tracking specs

To measure conversion events from both your website and mobile apps, make sure any DPA ads have the correct tracking specs set for tracking both events.

Event Tracking Spec

offsite_conversion

{ 'action.type': 'offsite_conversion', 'fb_pixel': FB_PIXEL_ID }

app_custom_event

{'action.type':'app_custom_event','application':APP_ID}

mobile_app_install

{'action.type':'mobile_app_install','application':APP_ID}

This will ensure any events occuring as the result of a Dynamic Product Ad will be tracked accordingly, regardless of if the user is viewing the website, or within an app.

To set these tracking specs when creating an ad:

curl \
-F "tracking_spec=[{'action.type':['app_custom_event'],'application': ['<APP_ID>']},{'action.type': ['offsite_conversion'], 'offsite_pixel': ['<FB_PIXEL_ID>']}, {'action.type': ['mobile_app_install'], 'application': ['<APP_ID>']}" \ 
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<AD_GROUP_ID>"