Preparing our Partners for iOS 14: Changes to Marketing API and Ads Insights API beginning January 19th, and beyond
Updated on April 26, 2021: On Tuesday, April 27, 2021 Facebook will begin rolling out new ad measurement protocols --Apple’s SKAdNetwork API and Facebook’s Aggregated Event Measurement -- following the release of iOS 14.5. Advertisers and partners will then begin to experience the changes described in this blog post. For the latest update visit the Facebook for Business blog.
Updated on April 21, 2021: On Tuesday, April 20, 2021, Apple confirmed that the release of general availability of iOS 14.5 will begin next week, and that it will start requiring apps in the App Store to obtain permission to “track” users across apps and websites owned by third parties for advertising and measurement purposes through it’s App Tracking Transparency (ATT) prompt. Apple’s prompt requirement will also prohibit certain data collection and sharing by businesses unless people opt in. As part of these changes, we’re implementing new ad measurement protocols, including Apple’s SKAdNetwork API and Facebook’s Aggregated Event Measurement and the changes described in this blog post will begin rolling out with the expected general availability of iOS 14.5 next week. We will provide an update with a specific date once more details are available from Apple. For the latest update, visit the Facebook for Business blog.
As we continue to prepare for the changes created by Apple’s iOS 14 requirements, we’re sharing an update to guidance we shared last month via a non-versioned changelog on changes coming to Marketing API and Ads Insights API endpoints.
The following details are best viewed on desktop.
Breaking Changes to All campaigns on January 19, 2021
The changes below to Ads Insights API will result in immediate changes to your current campaign reporting, if you are not already specifying specific attribution windows.
Affected endpoints | Breaking Change |
GET /{ad-account-id}/insights GET /{ad-id}/insights GET /{ad-set-id}/insights GET /{campaign-id}/insights POST /{ad-account-id}/insights POST /{ad-id}/insights POST /{ad-set-id}/insights POST /{campaign-id}/insights | If you do not provide action_attribution_windows when pulling results we will use 7d_click and 1d_view by default instead of 28d_click and 1d_view. The use_account_attribution_setting param will be ignored, as we will be replacing the account-level setting with a new attribution setting that can be set at the ad set level during ads creation. Below you will find details for two new fields related to attribution settings that can be used: use_unified_attribution_setting and attribution_setting. Please note, when Apple enforces the AppTrackingTransparency prompt, we will update the default to 7d_click only due to limitations in view-through signal. New use_unified_attribution_setting param: This field can be used in GET and POST requests to /adcampaigngroup/insights, /adcampaign/insights, /adgroup/insights, and /adaccount/insights. If you set use_unified_attribution_setting to true, your query's conversion metric attribution and campaign optimization will use the attribution_setting of the ad object(s) being queried — a single period of time during which conversions are credited to ads and used to inform campaign optimization. If use_unified_attribution_setting is set to true, we:
New attribution_setting field: This field can be used in GET and POST requests to /adcampaigngroup/insights, /adcampaign/insights, /adgroup/insights, and /adaccount/insights. This field is used to indicate which attribution setting is used by a conversion metric. The attribution setting is set at the ad set level during ads creation, and ensures the conversions our system optimizes for are the same ones you want to measure. For queries of ad objects that are using mixed or SKAdNetwork-dependent settings, attribution_setting will return the following:
atribution_setting will return values only when use_unified_attribution_setting is true, else response will not return attribution_setting. |
POST /{adaccount} | You will no longer be able to create or update ad accounts with the attribution_spec parameter. The following error will be triggered: ‘Updating account attribution window is not supported. |
GET /{adaccount} | You will no longer be able to read the attribution_spec parameter. It will return an empty result. |
A New Requirement for all Campaigns
The changes below will be available on January 19, 2021, however the requirement described will not go into effect until Apple requires their AppTrackingTransparency prompt. When Apple enforces the prompt requirement (Date: TBD), an error will be triggered if the value is not set.
Affected endpoints | New Requirement for All Campaigns |
POST /{ad-campaign-id} | Target Cost bid strategy is no longer supported for Campaign Budget Optimization campaigns |
POST /{ad-account-id}/ads POST /{ad-id} | These endpoints have a new conversion_domain field. This new field stores web domains (eLTD+1) and is mandatory for new ads optimized for conversions. An error will be generated during a create if this field is not set. This new field must match the domain tracked by the pixel:event pair on the ad set level, and does not need to match with the domain of the destination link. The format for this field is a single string. To create or update an ad in a campaign that shares data with a pixel, conversion_domain is required. For existing ads, conversion_domain will be auto-populated using destination URLs. |
POST / {ad-account-id}/adsets | Target Cost bid strategy is no longer supported Mobile App Install CPA Billing will no longer be supported. The billing event cannot be App Install if the Optimization goal is App Install |
Changes to SKAdNetwork Campaigns
The changes below will go into effect for SkAdNetwork campaigns. Please note these specifics will be enforced when Apple enforces the prompt requirement (Date: TBD).
Ad campaigns that target iOS 14 must set the new is_skadnetwork_attribution field to true.
Affected endpoints | Changes for SkAdNetwork Campaigns |
POST /{ad-id} | New iOS 14 ad campaigns will not be able to use Deferred Deep Links. If a Deferred Deep Link is provided, the following error will be triggered: ‘Deferred deep links aren't available for this ad.’ |
POST /{ad-account-id}/adsets | New iOS 14 ad campaigns will not be able to use Mobile App Custom Audiences for inclusion targeting, but may continue using them for exclusion, though these audiences will become less effective at excluding iOS 14 users over time. New iOS 14 app install campaigns will no longer be able to use app connections targeting; additional in-product guidance will suggest alternative targeting tactics. |
GET /{ad-account-id}/insights GET /{ad-id}/insights GET /{ad-set-id}/insights GET /{campaign-id}/insights POST /{ad-account-id}/insights POST /{ad-id}/insights POST /{ad-set-id}/insights POST /{campaign-id}/insights | Facebook will no longer be able to aggregate non-inline conversion metric values across iOS 14 and non-iOS 14 campaigns due to differences in attribution logic. Querying across iOS 14 and non-iOS 14 campaigns will result in no data getting returned for non-inline conversion metrics (i.e. app installs, purchases). Inline event metrics like impressions, link clicks, and video views, however, can still be aggregated. Also note that because iOS 14 campaigns rely on SKAdNetwork data and associated attribution logic, results for those campaigns can only be queried using the default or new unified attribution setting. |
POST /{ad-campaign-id} | For cost bidding campaigns with bid strategy COST_CAP and LOWEST_COST_WITH_MIN_ROAS, duration must be set to at least 3 days. |
Pending Changes Affecting All Ad Campaigns
The changes below will go into effect when Apple enforces the prompt requirement (Date: TBD).
Affected endpoints | Upcoming Changes |
POST /{ad-account-id}/adsets | Mobile App Install Ads (non SKAdNetwork) will have the following validation changes for Ad Set (API errors on failure):
|
GET /{ad-account-id}/insights GET /{ad-id}/insights GET /{ad-set-id}/insights GET /{campaign-id}/insights POST /{ad-account-id}/insights POST /{ad-id}/insights POST /{ad-set-id}/insights POST /{campaign-id}/insights | When changes go into effect, we will no longer support offsite web conversion metrics over the following attribution windows: 7d_view, 28d_view, and 28d_click. These windows will still remain available to access historical data — data prior to when the changes go into effect. |
GET /{ad-account-id}/ios_fourteen_campaign_limits | This new endpoint provides iOS 14 campaign limit information. This includes the number of available slots that can be used for new campaigns and ad sets. |
To learn more about how Apple’s iOS 14 requirements will impact Facebook advertising, reviewing the following articles:
