Migrate to Structured Data Files v7

Last update: 2023-10-18

This guide walks you through the process of migrating to Structured Data Files (SDF) v7 from a previous version and the changes, both required and suggested, that you can make to better optimize your integration.

See the release notes for an exhaustive list of differences between v6 and v7.

Migrate your Structured Data Files version

Migrating to Structured Data Files v7 from a previous version requires you to specify the new version, update the ID spaces for a subset of existing columns, and add integration with new columns.

Update Structured Data Files version

In order to update to a new Structured Data Files version, you need to update the version you assign to your parent Partner and Advertiser resources and your individual download tasks in the Display & Video 360 API.

Update parent resource settings

A default Structured Data Files version is set at the partner and advertiser resource level. This version is used as the default when downloading Structured Data Files through the interface or API.

Set in the interface
At the partner level
Navigate to the intended partner. Go to the Basic Details page under the Partner Settings menu in the left-hand navigation. Update the SDF version configuration in the Structured Data Files section to v7.
At the advertiser level
Navigate to the intended advertiser. Go to the Basic Details page under the Advertiser Settings menu in the left-hand navigation. Update the SDF version configuration in the Structured Data Files section to v7. If the default version is set at the Partner level, this setting may not be editable.
Set in the API
At the advertiser level
Make an advertisers.patch request to update the dataAccessConfig.sdfConfig.sdfConfig.version to SDF_VERSION_7 and, if needed, dataAccessConfig.sdfConfig.overridePartnerSdfConfig to True.

Update sdfdownloadtasks.create requests in the API

When making a sdfdownloadtasks.create request using the Display & Video 360 API, set the version field of the request body to SDF_VERSION_7.

Update IDs in required columns

In v7, the ID spaces used by a subset of columns have been updated to decouple Structured Data Files from the deprecated Entity Read Files product and further align with supported tools, such as the Display & Video 360 API.

This section lists every column using different IDs than v6 and instructions on how to retrieve reference information on the new values.

Insertion Order

v7 Migration instructions for columns

App Targeting - Exclude

App Targeting - Include

These columns have been updated to use app identifiers following the format "App Platform:App ID". Examples include: "APP:com.google.android.gm", "APP:422689480", "ANDROID_TV_APP:com.google.android.youtube.tvunplugged"

App platforms are identified by a string value. App IDs are the IDs provided by the relevant platform, such as a bundle ID from Android's Play store or App ID from Apple's App store.

Browser Targeting - Exclude

Browser Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under targeting type TARGETING_TYPE_BROWSER.

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Carrier Targeting - Exclude

Carrier Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under targeting type TARGETING_TYPE_CARRIER_AND_ISP.

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Channel Targeting - Exclude

Channel Targeting - Include

This column has been updated to use the channelId value of the Display & Video 360 API Channel resource.

Retrieve Channel resources individually or in paginated lists using the advertisers.channels and partners.channels services.

Device Targeting - Exclude

Device Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under the following targeting types:

  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DEVICE_MAKE_MODEL
  • TARGETING_TYPE_OPERATING_SYSTEM

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Measure DAR Channel

This column has been updated to use the channelId value of the Display & Video 360 API Channel resource.

Retrieve Channel resources individually or in paginated lists using the advertisers.channels and partners.channels services.

Site Targeting - Exclude

Site Targeting - Include

 This column has been updated to identify sites through URL strings.

Line Item

v7 Migration instructions for columns

App Targeting - Exclude

App Targeting - Include

These columns have been updated to use app identifiers following the format "App Platform:App ID". Examples include: "APP:com.google.android.gm", "APP:422689480", "ANDROID_TV_APP:com.google.android.youtube.tvunplugged"

App platforms are identified by a string value. App IDs are the IDs provided by the relevant platform, such as a bundle ID from Android's Play store or App ID from Apple's App store.

Bid Multipliers

This column has been updated to use new Criteria IDs for app and site row types.

The app row type has been updated to use concatenated string values of app platform and app platform ID, separated by a colon, for the criteria IDs. App platforms are identified by a string value. App IDs are the IDs provided by the relevant platform, such as a bundle ID from Android's Play store or App ID from Apple's App store.

The site row type has been updated to use URL strings as Criteria IDs.

Browser Targeting - Exclude

Browser Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under targeting type TARGETING_TYPE_BROWSER.

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Carrier Targeting - Exclude

Carrier Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under targeting type TARGETING_TYPE_CARRIER_AND_ISP.

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Channel Targeting - Exclude

Channel Targeting - Include

This column has been updated to use the channelId value of the Display & Video 360 API Channel resource.

Retrieve Channel resources individually or in paginated lists using the advertisers.channels and partners.channels services.

Device Targeting - Exclude

Device Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under the following targeting types:

  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DEVICE_MAKE_MODEL
  • TARGETING_TYPE_OPERATING_SYSTEM

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Site Targeting - Exclude

Site Targeting - Include

 This column has been updated to identify sites through URL strings.

Media Product

v7 Migration instructions for columns

Channel Targeting - Exclude

Channel Targeting - Include

This column has been updated to use the channelId value of the Display & Video 360 API Channel resource.

Retrieve Channel resources individually or in paginated lists using the advertisers.channels and partners.channels services.

Device Targeting - Include

This column has been updated to use targetingOptionId values of the Display & Video 360 API TargetingOption resources under the following targeting types:

  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DEVICE_MAKE_MODEL
  • TARGETING_TYPE_OPERATING_SYSTEM

Retrieve TargetingOption resources individually or in paginated lists using the targetingTypes.targetingOptions service.

Add integration with columns added since v6

If migrating from v6 to v7, you need to add the following columns to the relevant files:

File type Column
Line Item TrueView Target Frequency Count
Line Item TrueView Target Frequency Time Window
YouTube Ad Group Optimized Targeting

If you are migrating from a prior Structured Data Files version, reference the Structured Data Files release notes for information on additional columns added between your current version and SDF v6.

Additional changes

In v7, we've also instituted some superficial changes that should help you simplify your integration and move away from using deprecated Entity Read Files for reference.

New list ordering for a some columns

SDF v7 guarantees a stable ordering of certain list columns upon file generation. This results in more consistent behavior and easier review. This ordering is not enforced upon file upload, but is applied subsequently when generating the updated file.

Review the v7 release notes for a full list of columns that are now generated in either ascending numerical or alphabetical order.

New ID reference recommendations

We've updated the definitions of a number of columns to remove reference to deprecated Entity Read Files and instead recommend other means of ID lookup.

The values returned by the following columns are no different than in SDF v6, but we suggest that you update your integration to retrieve the IDs using the new recommended method, which can be found in their v7 column descriptions.

File types and their columns
Campaign
Geography Targeting - Exclude
Geography Targeting - Include
Inventory Source Targeting - Exclude
Inventory Source Targeting - Include
Language Targeting - Exclude
Language Targeting - Include
Insertion Order
Affinity & In Market Targeting - Exclude
Affinity & In Market Targeting - Include
App Collection Targeting - Exclude
App Collection Targeting - Include
Audience Targeting - Exclude
Audience Targeting - Include
Category Targeting - Exclude
Category Targeting - Include
Content Genre Targeting - Exclude
Content Genre Targeting - Include
Custom List Targeting
Geography Targeting - Exclude
Geography Targeting - Include
Inventory Source Targeting - Exclude
Inventory Source Targeting - Include
Keyword List Targeting - Exclude
Language Targeting - Exclude
Language Targeting - Include
Line Item
Affinity & In Market Targeting - Exclude
Affinity & In Market Targeting - Include
App Collection Targeting - Exclude
App Collection Targeting - Include
Audience Targeting - Exclude
Audience Targeting - Include
Category Targeting - Exclude
Category Targeting - Include
Combined Audience Targeting
Content Genre Targeting - Exclude
Content Genre Targeting - Include
Conversion Floodlight Activity IDs
Creative Assignments
Custom List Targeting
Geography Targeting - Exclude
Geography Targeting - Include
Inventory Source Targeting - Exclude
Inventory Source Targeting - Include
Keyword List Targeting - Exclude
Language Targeting - Exclude
Language Targeting - Include
Media Product
Audience Targeting - Exclude
Audience Targeting - Include
Category Targeting - Exclude
Category Targeting - Include
Geography Targeting - Include
Language Targeting - Exclude
Language Targeting - Include
YouTube Ad Group
Affinity & In Market Targeting - Exclude
Affinity & In Market Targeting - Include
Audience Targeting - Exclude
Audience Targeting - Include
Category Targeting - Exclude
Category Targeting - Include
Custom List Targeting