Marketing API Version
Dynamic Ads for Mobile

Dynamic Ads for Mobile Apps

Set up Dynamic Ads on mobile with Facebook SDKs. You should incorporate deep linking and deferred deep linking into your app to provide people using your app with the best experience possible:

  1. Facebook Mobile SDK for iOS or Android
  2. Mobile App Events
  3. Deep Linking
  4. Product Feed
  5. Tracking Specs

1. Setup Facebook Mobile SDK for iOS/Android

Integrate Facebook SDK for iOS or Android. See Facebook SDK for iOS or Facebook SDK for Android.

2. Setup Mobile App Events

On the web, use Facebook Pixel events such as ViewContent for tracking events interactions. On mobile we can track the same events with App Events.

You must send the same three required events from your app as you do from Facebook pixel. These are: ViewContent, AddToCart, Purchase. Dynamic Ads requires these events to work correctly.

iOS EventAndroid EventWeb 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

For example,ViewContent event fires when someone views a product in an app:

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);
[FBSDKAppEvents logEvent:FBSDKAppEventNameViewedContent
  valueToSum:54.23
  parameters:@{
    FBSDKAppEventParameterNameCurrency    : @"USD",
    FBSDKAppEventParameterNameContentType : @"product",
    FBSDKAppEventParameterNameContentID   : @"123456789"
  }
];

NOTE For iOS: You must always provide FBSDKAppEventParameterNameContentType and FBSDKAppEventParameterNameContentID for all events otherwise we cannot deliver product ads. 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 we cannot deliver product ads. Possible values for AppEventsConstants.EVENT_PARAM_CONTENT_TYPE is product or product_group.

You can also provide a JSON array of values for product ID when an event occurs for multiple products For example, you can send multiple products with the Purchase event.

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);
[FBSDKAppEvents logPurchase:54.23 currency:@"USD" parameters:@{
  FBSDKAppEventParameterNameContentID   : @"['1234','5678']",
  FBSDKAppEventParameterNameContentType : @"product"
  }
];

Multiple Content IDs

If you have multiple content IDs, you provide an escaped JSON array, for example:

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

Optional Parameters

For every app event, you can send additional parameters, you should send them when someone makes a purchase:

Field NameDescriptionTypeRequired

_valueToSum

The value of the product of purchase amount

string

no

fb_currency

The currency of the product or purchase amount

string

no

Using a Mobile Measurement Partner (MMP)

If you use an approved Mobile Measurement Partner (MMP) to report events to Facebook, you can adjust your implementation to also send the required events. While this process varies by MMP, typically it looks like this:

  1. Adjust your integration to report the three required events to the MMP, along with the required parameters
  2. With your MMP, map your event names to the Facebook event names
  3. Test App Events

Required Events for MMP

The following events are required:

Event nameDescription

fb_mobile_content_view

When a person has viewed a product.

fb_mobile_add_to_cart

When a item has been added to the cart.

fb_mobile_purchase

When a item/items have been purchased.

You must also send two additional parameters for Dynamic Ads to function:

  • An id of the item viewed, added to cart or purchased and -Whether the id is a product or product group id.

The additional parameters available are:

Field NameDescriptionTypeRequired

fb_content_type

either 'product' or 'product_group'

string

yes

fb_content_id

The retailer's product or product group ids. String containing a JSON-encoded array of ids

string

yes

_valueToSum

Value of the product purchased

string

no

fb_currency

Currency of the product or purchase amount

string

no

You should also send _valueToSum and fb_currency parameters when someone purchases items.

Testing App Events

The easiest way to test your integration works is App Ads Helper. See the events and paramters reported to Facebook in realtime.

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

You have two options: either see events being reported by you, or by a specific Advertising ID. In most cases, selecting "Me" is sufficient. Make sure you have Facebook installed on your device and that you are logged in.

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

In the tool, you see these 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 verify your app events function, you can check recent events in Facebook Analytics for Apps.

3. Setup Deep Linking

By providing deep links in your product feed, anyone who interact with your ad on Facebook can go directly to a specific location of your app. See App Ads, Deep Linking. For instance, when someone clicks an ad in Facebook on mobile, they see the product in your mobile app.

Deep Linking GuideVerify Deep Linking

Fallback to Web versus Appstore

If you use deeplinks, you can specify fallback behavior if someone does not have your app installed. When you provide deep links in your product feed, people without your app see the web URL for the product in the ad.

Since your likely goal is to increase catalog sales, you probably want people to see product pages, rather than your app to install. Therefore we default to web URLs, though you can specify different behavior for more control. Set the fallback behavior with applink_treatment when you create your Dynamic Ad. You have these options:

Field NameDescription

web_only

Always send someone to the given web URL. This overrides any deeplinks in your feed.

deeplink_with_web_fallback

If the app is installed and we have your corresponding deep links, send someone to your app. If one of these conditions is unfulfilled, send them to the website URL.

deeplink_with_appstore_fallback

If the app is installed and we have corresponding deep link information, send someone to the app. If the app is not installed, send them to the app store for the app.


4. Setup Product Feed

Now you need to provide actual deep links for your Dynamic Ads, see Product Catalog, Deep Linking.


5. Tracking Specs

To measure conversion events from both your website and mobile apps, make sure any Dynamic Ads have the correct Tracking Specs set for these events:

EventTracking 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}

Facebook can then track any events occurring from a Dynamic Ad, regardless of if someone views your website, or app. To set these tracking specs:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad(<AD_ID>);

$ad->{'tracking_spec'} = array(
  array(
    'action.type' => array('app_custom_event'),
    'application' => array($app_id),
  ),
  array(
    'action.type' => array('offsite_conversion'),
    'offsite_pixel' => array(<PIXEL_ID>),
  ),
  array(
    'action.type' => array('mobile_app_install'),
    'application' => array($app_id),
  ),

);
$ad->update();
curl \
  -F 'tracking_spec=[ 
    {"action.type":["app_custom_event"],"application":["101"]}, 
    {"action.type":["offsite_conversion"],"offsite_pixel":["<PIXEL_ID>"]}, 
    {"action.type":["mobile_app_install"],"application":["101"]} 
  ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<AD_ID>