Back to News for Developers

Preparing our Partners for iOS 14: Changes to Marketing API and Ads Insights API beginning January 19th, and beyond

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:

  • Cannot aggregate conversion metric values across different attribution settings.

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:

  • mixed: indicates when a campaign or account has ad sets using multiple attribution settings
  • skan: indicates when SKAdNetwork attribution setting is used for iOS 14 app install campaigns
  • na: indicates when a campaign or account doesn’t have an ad set within

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):

  • Block Creation of an Ad Set with App Install, App Events, or Value Optimization targeting iOS 14+ devices.
  • If an Ad Set is created using the default targeting string and the optimization goal is App Install, App Events or Value, we will automatically filter out iOS 14+ devices.

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: