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 Detailspage under the Partner Settingsmenu in the left-hand navigation. Update the SDF versionconfiguration in the Structured Data Filessection to v7.
- At the advertiser level
- Navigate to the intended advertiser. Go to the Basic Detailspage under the Advertiser Settingsmenu in the left-hand navigation. Update the SDF versionconfiguration in the Structured Data Filessection 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.patchrequest to update thedataAccessConfig.sdfConfig.sdfConfig.versiontoSDF_VERSION_7and, if needed,dataAccessConfig.sdfConfig.overridePartnerSdfConfigtoTrue.
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
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.
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
Line Item
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.
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
Media Product
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.
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 subset of 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.
| Geography Targeting - Exclude |
|---|
| Geography Targeting - Include |
| Inventory Source Targeting - Exclude |
| Inventory Source Targeting - Include |
| Language Targeting - Exclude |
| Language Targeting - Include |
| 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 |
| 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 |
| Audience Targeting - Exclude |
|---|
| Audience Targeting - Include |
| Category Targeting - Exclude |
| Category Targeting - Include |
| Geography Targeting - Include |
| Language Targeting - Exclude |
| Language Targeting - Include |
| 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 |
