Skip to content

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 Category Campaign Type/Objective Branch Ad Format
Consideration App Installs App Only: Install

Facebook Campaign Advert Format Support Table

Facebook Campaign Type Photo Video Carousel Slideshow Collection Dynamic Canvas
App Installs ✔︎ ✔︎ ✔︎ ✔︎ - - ✔︎

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)

Note

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.

    Ads Partner Management

  2. Search for Facebook.

  3. Click Connect With Facebook

    Connect with Facebook

  4. Login to Facebook if you are not logged in

    Login

  5. Confirm that Branch can receive your public profile

    Public profile

  6. Confirm that Branch can have permissions ads_read

    OAuth scopes

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

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

    Choose ad accounts

    Note

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

  8. Click to select a Facebook app id for which you want to run Facebook ads

    enter app id

  9. Copy the app id

    find app id

  10. Paste the app id and press Save

    paste app id

  11. 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.

    complete

  12. Finally, to create a Facebook Ads link click the Create Facebook Link button in the top right hand corner.

    Create Facebook Ad Link

Branch <> Facebook Field Mappings

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

Facebook Data Branch Data Possible Values
n/a ~advertising_partner_name “Facebook”
n/a ~channel “Facebook” if null or last touch
na/a ~feature "Paid Advertising"
campaign_name ~campaign Light Bright Launch
campaign_id ~campaign_id 15292426
publisher_platform ~secondary_publisher facebook / instagram / audience_network
creative_name ~creative_name Light Bright Vertical
creative_id ~creative_id 1234567890
ad_set_name ~ad_set_name Light Bright
ad_set_id ~ad_set_id 12345567890
ad_name ~ad_name Light Bright

Adding the Agency Tag to Campaign Name

Only agencies managing advertising campaigns on behalf of a client must prepend their Agency ID to the campaign name when creating advertising campaigns for Self-Attributing Networks (SANs).

Agency ID Required

Failure to append the campaign name with the Agency ID will result in any subsequent conversion not being properly attributed to the responsible agency.

Finding Your Agency ID

You can find your Agency ID under Account Settings in the Agency view.

Creating Your Agency Tag

Your agency tag must adhere to the following format:

`agency_{YOUR AGENCY ID HERE}_`

Example Campaign with Agency tag

agency_1234567890_My_SAN_Ad_Campaign

You can append the Agency Tag to either the beginning or the end of the campaign name.

Agency ID Removed When Exporting

The "~campaign" value displayed in exports/analytics will not include the agency_id. If you set up a campaign called test_campaign_agency_1234 in Facebook, and for any installs that came from that campaign, the "~campaign" value will be "test campaign".

Cost Data

Branch provides the following cost metrics for this ad partner:

Analytics Tag Description Used for
Cost Total cost (spend) for those dimensions (analytics tags, user data, time range), regardless of cost model Understanding the total amount spent
eCPI cost / installs Normalizing spend per install, to understand the average price of an install across networks or over time
eCPC cost / clicks Normalizing spend per click, to understand the average price of an click across networks or over time
eCPM cost / (impressions / 1000) Normalizing spend per thousand impressions, to understand the average price of 1000 impressions across networks or over time
eCPA cost / purchases [includes web and app purchases] Normalizing spend per purchase, to understand the average price of a purchase across networks or over time
Return On Investment (ROI) (revenue-cost / cost) * 100 Deriving return on investment, to understand the percentage "profit" made on ad spend
Return On Ad Spend (ROAS) (revenue / cost) * 100 Deriving return on investment by understanding the percentage revenue multiple for a given unit of spend

Info

All cost data is ingested in local currency and then translated to USD on the dashboard using the exchange rate for that currency on the day the data is stored. In effect, this means the dashboard shows the amount that campaign cost converted to USD at the time it ran.

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.

Example Ads Analytics Graph

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.

Example Ads Table

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.

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.

  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 { *; }
    
  3. 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();
      
  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 Link Creation
  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. Create Ad Link

  4. 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. Create Ad Link

  5. Because this is an app install ad, the redirect section will be largely ignored. We highly recommend that you leave this section untouched.

  6. Analytics will be automatically pulled in from the direct Facebook integration above, and so you can ignore the analytics section of the configuration.

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.

  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. Campaign Selection
  3. Continue with campaign creation selecting the app to advertise, audience, placement, and budget. Then press continue to enter the Advert creation step.
  4. Now select an advertisement format and customize your ad
  5. 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

    Deep Link Placement

    • If you select Canvas, add your Branch Ad link as the Destination Website URL for your canvas advertisement components

    Canvas Setup

  6. 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. Then please contact us and include "Facebook web-only ads issues" in the subject.

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

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 uses this same mechanism via a 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:

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.

Invalid App Links Troubleshooting

Rescrape the OG Tags

You can test the OG tags using the OG tag tester 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.

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 as described on the Integration Testing page.
  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 integrations@branch.io 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:

App Restrictions Troubleshooting