Filters

Facebook App Install Ads

Overview

Branch links can be used together with Facebook App Install Campaign ads, allowing you to track ad-driven installs on the Branch dashboard and deep link those new users directly to content the first time they open your app.

Note: This documentation applies for Ad placements across Facebook and the Audience Network.

This documentation supports the following Facebook Ad Campaign types:

Facebook Campaign CategoryCampaign Type/ObjectiveBranch Ad Format
ConsiderationApp InstallsApp Only: Install

Facebook Campaign Advert Format Support Table

Facebook Campaign TypePhotoVideoCarouselSlideshowCollectionDynamicCanvas
App Installs✔︎✔︎✔︎✔︎--✔︎

📘

Facebook Campaign Types

Looking for other Facebook Ad campaign types? Please check out our Facebook Ads Overview guide.

Setup

🚧

Prerequisites

  • To track installs from Facebook Ads you should integrate the Branch SDK into your app.
  • To use Branch links in Facebook App Install Ads ensure you have:
    • URI schemes configured on iOS
    • URI schemes configured on Android
    • iOS App Store ID set
    • Android Package Name set
    • Social Media Settings filled out (i.e. OG tags at the bottom of Link Settings)
  • If you want to deep link from your ads directly to content, you should configure deep link routing.
  • Ads is a premium product priced on Monthly Active Users. Sign up for the Ads product to enable this functionality.

Enable Facebook as an Ad Partner (for measurement)

📘

Enable Facebook as an Ad Partner

Completing this section -- Enable Facebook as an Ad Partner -- will result in Branch sending app events to Facebook in order to attribute them back to ad campaigns. This does not enable deep linking for the ad. Further work below is required for deep linking.

If you haven't enabled Facebook as an Ad Partner on the Branch dashboard follow this section to do so. Advanced options for sending events can be found here.

  1. Navigate to the Partner Management tab.

  1. Search for Facebook.

  2. Click Connect With Facebook

  1. Log in to Facebook if you are not logged in

  1. Confirm that Branch can receive your public profile

  1. Confirm that Branch can have permissions ads_read

ads_read is used to surface impressions and clicks on the Branch Dashboard.

  1. Select the ad accounts for which you want to run app install ads or app engagement ads

  1. Click to select a Facebook app id for which you want to run Facebook ads
1136
  1. Copy the app id

  1. Paste the app id and press Save

Add your Facebook App Secret to enable Deferred Deep Linking.

  1. Facebook is now enabled as an ad partner!

    Note that if you have different attribution windows between Facebook and Branch, those will be highlighted. The warning has a link to the docs on how to align these attribution windows.

  1. [Optional] Finally, to create a Facebook Ads link for deep linking click the Create Facebook Link button in the top right hand corner. Scroll down to the section on Deep link your app install campaign for more details.

📘

Connecting Multiple Accounts

All SANs - including Facebook - accept multiple accounts. However, only a single Branch user can authenticate the integration. This means that the single user must have access to all of the accounts you wish to connect.

Note: Do not authenticate a single ad account to multiple Branch apps (ex. Live and Test apps) as that will cause issues with authentication and Dashboard reports.

If you are having trouble finding or selecting the ad account(s) for which you want to run ads, please visit our FAQ.

👍

Agency-Managed Campaigns

Branch <> Facebook Field Mappings

Branch maps the following data fields from Facebook App Install Ads to Branch.

Facebook DataBranch DataPossible Values
n/a~advertising_partner_name“Facebook”
n/a~channel“Facebook” if null or last touch
n/a~feature"Paid Advertising"
campaign_name~campaignLight Bright Launch
campaign_id~campaign_id15292426
publisher_platform~secondary_publisherfacebook / instagram / audience_network
creative_name~creative_nameLight Bright Vertical
creative_id~creative_id1234567890
ad_set_name~ad_set_nameLight Bright
ad_set_id~ad_set_id12345567890
ad_name~ad_nameLight Bright
ad_id~ad_id123456789

📘

Cost Data Support

View Your Data

The Ads Analytics Page on the Branch dashboard provides an interactive time series graph and table to view the performance of your Ad campaigns.

The table shows summary data on the performance of each Ad campaign. On the right top side of the table you can find a download button to retrieve the chart's content as a CSV file.

📘

Interacting with your data

Breakdown and compare aspects of your Ad campaigns' performance by using the Compare by + button to add a parameter to split the data displayed data by.

Then use the and + button to refine the data displayed to gain deeper insight into the performance of your Ad campaigns.

Optional: Deep link your app install campaign

This section is not required for measurement if you are running app-only ads. We will automatically pull in campaign, ad set, ad, and creative information from Facebook. However, if you want users to be deep linked, you should follow the instructions in this section.

Configure your app to read Facebook App Install deep links

  1. Unfortunately, we've found that the direct S2S mechanism for retrieving deep links is rather unreliable. We recommend that you have the Facebook Android / iOS SDKs installed so Branch can work directly with them on the client side for the best outcome.
  2. On Android, if you are using Proguard, make sure you add the necessary inclusions to keep the Facebook SDK during build time.
-keep class com.facebook.applinks.** { *; }
-keepclassmembers class com.facebook.applinks.** { *; }
-keep class com.facebook.FacebookSdk { *; }
  1. Tell Branch to use the Facebook SDK to read the App Links on initialization
  • iOS - Objective C
// This goes BEFORE initSession is called in didFinishLaunchingWithOptions
[[Branch getInstance] registerFacebookDeepLinkingClass:[FBSDKAppLinkUtility class]]
  • Android - Java
// This goes in the getAutoInstance call in your Application class
Branch.getAutoInstance(this).enableFacebookAppLinkCheck();

Create an Ad Link for deep linking

  1. Create a Branch Ad link from the Partner Management page Create Facebook Link button under the Facebook Partner and select App Install or Engagement.
  2. Enter a Link Name for later reference.
  3. Configure the link with the Ad Format set to App Only, the Ad Partner set to Facebook, and the Secondary Ad Format set to App Install Ads.

  1. Under the Configure Options tab, use the deep link data input section to add your deep linking parameters. You can use this configuration section to specify custom link parameters that will be deep linked into the app after install. These could include a coupon code or a page identifier to route the user. Visit the Deep Link Routing page to learn more.
  2. Because this is an app install ad, the redirect section will be largely ignored. We highly recommend that you leave this section untouched.
  3. Analytics will be automatically pulled in from the direct Facebook integration above, and so you can ignore the analytics section of the configuration.

🚧

Disable Deepviews

In order for your campaign to run effectively, be sure to disable Deepviews. You can either disable Deepviews for your entire account or disable Deepviews for one link.

Configure your campaign to deep link the Ad Link

  1. Navigate to https://www.facebook.com/ads/create while logged in to the account that owns your Facebook app.
  2. Select App Installs as the campaign marketing objective.

  1. Continue with campaign creation selecting the app to advertise, audience, placement, and budget. Then press continue to enter the Advert creation step.
  2. Now select an advertisement format and customize your ad
  3. Under the Destination field, you can select to direct your advertisement to the App Store or a Facebook Canvas Advertisement.
    • If you select the App Store, fill in the Deep Link field with your Branch Ad link

- If you select Canvas, add your Branch Ad link as the <span class="notranslate">**Destination**</span> Website URL for your canvas advertisement components

  1. Complete the rest of the ad campaign setup.

Your Facebook Ad Campaign is now setup to use Branch Links to handle App Installs!

📘

Optional: Ad formats with Multiple Links

Some ad formats such as Carousel format can handle multiple deep links. To have link performance data on each image or component of the advertisement, create multiple Branch Ad links to be used in each part of the multiple link advertisement format. This format is useful if you want to drive customers to different content pieces or products.

Testing Deep Linking from Ads

Unfortunately, the demo/preview ads used during the ads creation flow on Facebook use a different mechanism than live Facebook ads. This prevents you from testing deep linking from your Facebook ads. Do not waste time trying to get this to work. We've confirmed with Facebook representatives that this is broken.

The only way to test the deep linking functionality is outside of the actual ads system is a helper tool from Facebook. Follow these instructions to test the deep linking functionality:

  1. Head to the Ads tester tool
  2. Choose the app that you're advertising with
  3. Scroll down to the button that says 'Test Deep Link'
  4. Paste in the Branch link
  5. Check 'Send Deferred'
  6. Click 'Send to iOS/Android'
  7. Install the app and it should deep link!

📘

Note the following common mistakes for testing

  1. If you reset the GAID or IDFA on a device, you must uninstall Facebook and re-install prior to testing. Facebook does not update the IDFA/GAID every time it's opened.
  2. Send deferred does not require a notification to be sent or to be clicked. Checking "Send Deferred" will automatically queue up a match for the test device with the deep link data. The notification is completely separate from deferred deep linking.
  3. The Facebook account on the desktop where you click "Send Deferred" must match the account logged into the test device for deferred deep link data to be queued up. Note that we've observed issues where you log in and out of multiple accounts on test devices that cause Facebook to not correctly queue up a match.
  4. If you see that someone liked your ad, do not bother trying to click and test it. Clicking your own, live advertisement that shows up in notifications will not deep link.

Troubleshooting

We now have a dedicated FAQ page for Facebook app ads. If you are having any issues with app ads, please review the FAQ.

If you are having issues with web-only ads, you can check out the FAQ.

Branch Cost data not matching the Ad Partner dashboard

Please ensure that you've selected the same time zone in your Ad Partner's dashboard and your Branch dashboard.

CPI metric doesn't match between Ad Partner and Branch, although cost metric does

Branch's last-click attribution model can lead to differences in install counts for Branch vs self-attributing networks (SANs) that in turn cause differences in CPI metrics. Verify whether your cost and install metrics match the Ad Partner's dashboard. If there is an install discrepancy, it is likely legitimate and due to differences in install counts, where Branch's number is more accurate. If the discrepancy is very large, investigate causes of install discrepancies through the usual troubleshooting steps.

Cost, click and impression data is all missing

Generally, reauthenticating a partner and waiting 24 hours will re-enable cost data.

When you reauthenticate, double check that you have selected the correct accounts. We will only pull cost data for accounts that you select as part of the authentication process.

Background:
Cost, click and impression data for SANs are generally sourced from Partner APIs (unless Branch impression pixels or links are being intentionally used for attribution, for example, in web campaigns). When you enable a SAN, you authenticate with your provider. Branch uses this authentication to retrieve click, cost and impression data. If the authentication token expires (for example, if you reset your password, or the partner force resets your token), then you may not see click, impression or cost data. In this case, simply reauthenticate and that will refresh your token.

Cost data is missing or incorrect for certain "compare by" breakdowns

Downstream events, such as installs, should always have the full range of compare by options in the dashboard. However, clicks, impressions and cost data for SAN are often imported via Partner APIs. These APIs do not necessarily provide the same breakdowns for cost data that Branch supports with raw install events, so there may be cases where the Branch Dashboard cannot compare by the same dimensions for cost data vs install data.

Troubleshooting deep linking

Intercepting Deep Links Before Branch

If you use Branch deep links in Facebook app ads, please check the following.

We recently discovered an issue where an app was calling Facebook's SDK to fetch the deferred app link within their iOS and Android app. Branch calls use this same mechanism via direct API integration, but if Facebook's SDK retrieves it before we do, Branch will not see any deep link data. Please ensure to comment out any calls to the following API within your app:

Issues Reading Facebook App Links

If Facebook is having trouble reading the App Links from the Branch link, you might see messages like these while trying to test out the flow. This means that there is something corrupted in the OG tags causing Facebook to not parse your link.

Rescrape the OG Tags

You can test the OG tags using the Sharing Debugger tool provided by Facebook:

  1. Paste the Branch Link into the Input URL box.
  2. Click on the Show existing scrape information button.
  3. Examine errors regarding App Links from the output window.
  4. Click on the Fetch New Scrape Information button. This last step typically resolves this problem if you are certain that your Branch Link Settings are correct.

📘

Automate Rescraping Process

You can further automate the rescraping process by using this command after you create a new link and before you use it for any ads:

curl --insecure "https://graph.facebook.com/?id=[YOUR-URL-TO-SCRAPE]&scrape=true"

If the OG tag tester continues to report problems

  1. Examine your Link Settings and ensure that for all platforms (for which an app is available), that a URI scheme and a link to the app in the Play/App Store is configured. If you are using a Custom URL for your iOS Redirect, then you need to append ?id[10-digit App Store ID] to the URL. This is necessary in order to fully generate the App Links and OG tags that the Facebook scraper expects to find.
    • For example, if your App Store URL is https://itunes.apple.com/us/app/my-app-name/id1234567890, then your Custom URL value should be https://example.com?id1234567890
  2. If errors from the output window pertain to OG tags i.e. missing title, description etc. then examine link OG tags by appending ?debug=true.
  3. If you haven't set OG tags on a per link level, then please check your Dashboard's global Social Media Display Customization settings from the Link Settings page.

Use a direct deep link

As a last resort, you can manually input a direct deep link. To retrieve this:

  1. Go to Facebook's Open Graph Object Debugger
  2. Input the Branch link you want to use for your ad
  3. Click Fetch new scrape information
  4. Find the al:ios:url line (it should look like <meta property="al:ios:url" content="myapp://open?link_click_id=link-242052337263342024" />)
  5. Copy the value of this (myapp://open?link_click_id=link-242052337263342024) and input it as the Deep Link value of your ad

If none of these approaches work, please reach out to our support team immediately.

Known Issue with App Restrictions

We recently discovered a bug within the Facebook system that prevents App Links from being read by the robot if you change any of these values from the defaults in your Advanced Facebook App Settings tab. Please make sure

  • Contains Alcohol is set to No
  • Age Restriction is set to Anyone (13+)
  • Social Discovery is set to Yes
  • Country Restricted is set to No

It has to look like this exactly:


What’s Next