This version of Microsoft Advertising reached end of life on October 31, 2018 and is no longer functioning.
Upgrade to the latest version (v2) to continue replicating data.
Microsoft Advertising feature snapshot
A high-level look at Stitch's Microsoft Advertising (v1) integration, including release status, useful links, and the features supported in Stitch.
STITCH | |||
Release status |
Sunset on October 31, 2018 |
Supported by | |
Stitch plan |
Standard |
API availability |
Not available |
Singer GitHub repository | |||
REPLICATION SETTINGS | |||
Anchor Scheduling |
Supported |
Advanced Scheduling |
Unsupported |
Table-level reset |
Unsupported |
Configurable Replication Methods |
Unsupported |
DATA SELECTION | |||
Table selection |
Supported |
Column selection |
Supported |
Select all |
Supported |
||
TRANSPARENCY | |||
Extraction Logs |
Supported |
Loading Reports |
Supported |
Microsoft Advertising replication
There are two types of tables in Stitch’s Microsoft Advertising integration: Core Object and Report.
-
Core Object tables contain foundational data that’s useful for analysis. These are the
accounts
,ad_groups
,ads
, andcampaigns
tables. With the exception of theaccounts
table, these tables are replicated using Full Table Replication. -
Report tables are the various Microsoft Advertising reports. The replication process for these tables is a bit unlike that of other tables:
- Extraction: Data is extracted using a Conversion Window. A Conversion Window is a period of time after a customer clicks an ad that a conversion (ex: a purchase) is recorded in Microsoft Advertising.
Stitch currently uses a Conversion Window of 30 days.
This means that data from the past 30 days will be replicated during every replication job.
- Loading: Data is loaded into your data warehouse using Append-Only Replication.
For Report tables, this means that:
-
Due to the Conversion Window, a high Replication Frequency may not be necessary. Because Stitch will replicate data from the past 30 days during every replication job, recent data will be re-replicated and count towards your row quota.
To reduce your row usage and replicating redundant data, consider setting the integration to replicate less frequently. For example: every 12 or 24 hours.
-
Querying for the latest data in Report tables will require a different strategy than you might usually use. Stitch will add a column named
_sdc_report_datetime
to Report tables to help you identify the most recent records in a table. See the Query for the Latest Data section for more info and a sample query.
Each part of the replication process for Report tables is explained below.
Report Tables: Data Extraction & Conversion Windows
Every time Stitch runs a replication job for Microsoft Advertising, the last 30 days’ worth of data will be replicated for any Report tables currently being tracked.
Stitch replicates data in this way to account for updates made during the Conversion Window.
For historical and full re-replications of Microsoft Advertising data, Stitch will query for and extract data newer than or equal to the date defined in the Start Date field in the Integration Settings page.
The Start Date, in conjunction with the Conversion Window, defines the minimum date Stitch should query for when extracting historical data. This is calculated as:
Start Date - Conversion Window = Minimum Extraction Date
Example
During the initial set up, the Start Date field is set to July 3, 2017
, or 2017-07-03 00:00:00
.
To account for the Conversion Window, Stitch would calculate the Minimum Extraction Date value as: 2017-07-03 00:00:00 - 30 days = 2017-06-03 00:00:00
If you were to write a SQL query using this date for the ad_performance_report
table, it might look like this:
SELECT *
FROM bing_ads.ad_performance_report
WHERE TimePeriod >= '2017-06-03 00:00:00' /* Min. Extraction Date */
ORDER BY TimePeriod
For ongoing replication jobs, Stitch will query for and extract data using the last saved maximum value in the table’s Replication Key column and the Conversion Window for the table.
Note: This applies to every replication job that takes place after the historical replication job.
Example
The last maximum saved Replication Key value for the ad_performance_report
table is 2017-10-01 00:00:00
.
To account for the Conversion Window of 30 days, we’d subtract this from the last maximum saved Replication Key value:
2017-10-01 00:00:00 - 30 days = 2017-09-01 00:00:00
In this case, Stitch would query for and extract data that is newer than or equal to 2017-09-01 00:00:00
and older than or equal to 2017-10-01 00:00:00
.
If this were a SQL query, it might look like this:
SELECT *
FROM ad_performance_report
WHERE TimePeriod >= '2017-09-01 00:00:00'
/* max Replication Key value - Conversion Window */
AND TimePeriod <= '2017-10-01 00:00:00'
/* max Replication Key value from previous job */
ORDER BY TimePeriod
Report Tables: Data Loading & Append-Only Replication
When Stitch loads the extracted data for Report tables into your destination, it will do so using Append-Only Replication. This is a type of Incremental Replication where existing rows aren’t updated, but appended to the end of the table.
Additionally, the number of rows loaded into the table during each replication job is dependent on the combination of unique values in the dimension columns you track. See the Column Selection and Statistic Aggregation section for more info and examples.
Example
Let’s say these columns are tracking in the ad_performance_report
table:
campaignId
(dimension) - This is the ID associated with a campaign. In this example, there are two campaigns:929007494
and929599581
deviceType
(dimension) - The device type. There are two values for this example:Computer
andTablet
impressions
(metric) - The total number of impressions.
Every time Stitch replicates and loads data, a row for each unique combination of the dimension columns will be appended to the end of the table:
_sdc_report_datetime | TimePeriod | AccountId | campaignId | deviceType | impressions |
---|---|---|---|---|---|
2017-10-01 17:48:26.791 | 2017-09-10 00:00:00 | 71086605 | 929007494 | Computer | 61 |
2017-10-01 17:48:26.791 | 2017-09-10 00:00:00 | 71086605 | 929007494 | Tablet | 15 |
2017-10-01 17:48:26.791 | 2017-09-10 00:00:00 | 71086605 | 929599581 | Computer | 37 |
2017-10-01 17:48:26.791 | 2017-09-10 00:00:00 | 71086605 | 929599581 | Tablet | 9 |
Report Tables: Query for the Latest Data
You may need to alter this query
The query below is meant to act as a foundation for writing your own. Depending on your SQL syntax and the dimensions contained in a given table, you may need to alter this query for your own usage.
When querying your Microsoft Advertising data, you’ll want to include the Dimensions you’re analyzing in the partition. For example: If you’re analyzing campaigns over time, you’d include columns like campaignId
and date
.
If you want only the most recently replicated data for any Microsoft Advertising Report table, you can use the sample query below to account for the Append-Only Replication Stitch uses.
This query uses two columns - which are automatically included for every Report table - to return the latest data:
TimePeriod
- The day that the record pertains to._sdc_report_datetime
- The starting time of the Stitch job that extracted the record.
SELECT *
FROM (
SELECT *,
RANK() OVER (PARTITION BY TimePeriod,
ORDER BY _sdc_report_datetime DESC)
FROM ad_performance_report
ORDER BY TimePeriod ASC
) AS latest
WHERE latest.rank = 1
In this query:
- A subquery first uses a window function to create a ‘window’ of data for each
TimePeriod
, - The values of the
_sdc_report_datetime
column are ranked within each window partition, and - Then, in the outer query, only the rows with
_sdc_report_datetime
values ranked as1
- which is equal to the maximum timestamp - are returned.
Microsoft Advertising table reference
Schemas and versioning
Schemas and naming conventions can change from version to version, so we recommend verifying your integration’s version before continuing.
The schema and info displayed below is for version 1 of this integration.
Report Tables: Column Selection and Statistic Aggregation
The dimension columns selected for replication in Report tables can impact how performance statistics are aggregated. Additionally, this can also affect the number of rows replicated and loaded into your destination.
For example: if gregorianDate
, accountId
, campaignId
, deviceType
, and impressions
were selected, the impressions
column would contain the total number of impressions for the device type for that date:
gregorianDate | accountId | campaignId | deviceType | impressions |
---|---|---|---|---|
2018-01-05 00:00:00 | 71086605 | 240531207 | Computer | 4 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Smartphone | 3 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Tablet | 3 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Unknown | 1 |
If the network
column were also selected, a row for every unique combination of deviceType
and network
would be created and impressions
would be aggregated accordingly:
gregorianDate | accountId | campaignId | deviceType | network | impressions |
---|---|---|---|---|---|
2018-01-05 00:00:00 | 71086605 | 240531207 | Computer | AOL Search | 3 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Smartphone | AOL Search | 1 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Tablet | AOL Search | 0 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Unknown | AOL Search | 0 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Computer | Bing and Yahoo! search | 1 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Smartphone | Bing and Yahoo! search | 2 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Tablet | Bing and Yahoo! search | 3 |
2018-01-05 00:00:00 | 71086605 | 240531207 | Unknown | Bing and Yahoo! search | 1 |
Table and column names in your destination
Depending on your destination, table and column names may not appear as they are outlined below.
For example: Object names are lowercased in Redshift (CusTomERs
> customers
), while case is maintained in PostgreSQL destinations (CusTomERs
> CusTomERs
). Refer to the Loading Guide for your destination for more info.
accounts
Replication Method : |
Key-based Incremental |
Replication Key |
lastModifiedTime |
Primary Key |
id : lastModifiedTime |
Official docs : |
The accounts
table contains high-level information about each of the ad accounts you selected during setup. Each row in this table corresponds to a single account.
id
The account ID. Reference:
|
|||
lastModifiedTime
The time (in UTC) the account was last updated. Note: The date and time value reflects the date and time at the Bing server, not the client. |
|||
accountFinancialStatus
The financial status of the account. |
|||
accountLifeCycleStatus
The status of the account. |
|||
accountType
The type of the account. |
|||
billToCustomerId
The ID of the customer that is billed for the charges that the account generates. This is either the reseller that manages the account on behalf of the owner or the ID of the customer that owns the account. |
|||
countryCode
The code of the country/region in which the account operates. See Microsoft’s documentation for a list of country code values. |
|||
currencyType
The type of currency used to settle the account. |
|||
forwardCompatibilityMap
Details about the forward compatibility settings for the account.
|
|||
language
The language used to render the invoice for the account, if invoice is used as the payment method. |
|||
lastModifiedByUserId
The ID of the user who last updated the account’s information. |
|||
name
The name of the account. |
|||
number
The account number generated by Bing Ads used to identify the account in the Bing Ads web app. This value is alphanumeric. |
|||
parentCustomerId
The ID of the customer that owns the account. |
|||
pauseReason
Indicates the reason the account is paused. Possible values include:
|
|||
paymentMethodId
The ID of the payment instrument used to settle the account. |
|||
paymentMethodtype
The type of payment instrument used to settle the account. |
|||
primaryUserId
The ID of the account manager who is primarily responsible for managing the account. By default, this value is set to the reseller’s user ID. |
|||
timestamp
The timestamp value used internally by Bing Ads to reconcile updates between account update and delete operations. |
|||
timezone
The default timezone value to use for campaigns in this account. If left unspecified when the account is created, this value will default to |
adgroup_performance_report
Official docs : |
The adgroup_performance_report
table contains performance data for ad groups, aggregated by day.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
ads
Replication Method : |
Full Table |
Primary Key |
id |
API endpoint : |
The ads
table contains info about the following ad types:
AppInstall
DynamicSearch
ExpandedText
Product
Text
Image
id
The ad ID. Reference: |
|||
adFormatPreference
Indicates whether or not the ad copy is shown to users as a search or native ad. Search ads tend to be written as a call to action, whereas intent ads are written in a more informational style. Possible values are:
|
|||
devicePreference
Determines the device preference for showing the ad. |
|||
editorialStatus
The editorial review status of the ad, which indicates whether the ad is pending review, approved, or disapproved. |
|||
finalAppUrls
The last or final URL where a user who clicks on an in-app ad is taken.
|
|||
finalMobileUrls
The last or final URL where a user who clicks on a mobile ad is taken.
|
|||
finalUrls
The last or final URL where a user is taken, whether or not the click to final URL path included any redirects.
|
|||
forwardCompatibilityMap
Details about the forward compatibility settings for the ad.
|
|||
status
The status of the ad. Possible values are |
|||
trackingUrlTemplate
The tracking template to use as a default for all landing page URLs. |
|||
type
The type of the ad. |
|||
urlCustomParameters
The custom collection of key and value parameters for URL tracking. |
ad_groups
Replication Method : |
Full Table |
Primary Key |
id |
API endpoint : |
The ad_groups
table contains info about the ad groups associated with the campaigns in your Bing Ads account.
id
The ad group ID. Reference:
|
|||
adDistribution
Determines whether the ads within the ad group will be displayed on the content distribution channel, search distribution channel, or both. |
|||
adRotation
Determines how often ads in the ad group show in relation to each other. If there are multiple ads within an ad group, the ads will rotate because only one ad from your account can show at a time. Possible values are:
|
|||
biddingScheme
The bid strategy type for how bids are managed. |
|||
contentMatchBid
The bid to use when the keywords that the service extracts from the content page and the ad group’s keywords match by using an exact match comparison. |
|||
endDate
The date that the ads in the ad group will expire. |
|||
forwardCompatibilityMap
Details about the forward compatibility settings for the ad group.
|
|||
language
The language of the ads and keywords in the ad group. |
|||
name
The name of the ad group. |
|||
nativeBidAdjustment
The percent amount by which to adjust the bid for intent ads above or below the base ad group or keyword bid. |
|||
network
The search networks where the ads will display. Possible values are:
|
|||
pricingModel
The pricing model for the ad group. The only supported pricing model in Bing Ads is based on cost per click, or CPC. This field has been deprecated by Bing Ads. |
|||
remarketingTargetingSetting
The targeting setting that is applicable for all audiences, or custom audiences and remarketing lists associated with the ad group. Possible values are:
|
|||
searchBid
The default bid to use when the user’s query and the ad group’s keywords match by using either a broad, exact or phrase match comparison. |
|||
settings
Details about the settings applied to the ad group.
|
|||
startDate
The date that the ads in the ad group can begin serving. |
|||
status
The status of the ad group. Possible values are:
|
|||
trackingUrlTemplate
The tracking template to use as a default for all URLs in your ad group. |
|||
urlCustomParameters
The custom collection of key and value parameters for URL tracking. |
ad_performance_report
Official docs : |
The ad_performance_report
table contains performance info about ads, including clicks and conversions. This data can be used to identify and improve under-performing ads.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
accountId
The Bing Ads-assigned ID of the account. |
_sdc_report_datetime
The start time of the Stitch replication job that replicated this record. |
gregorianDate
The day the record pertains to. |
adGroupId
The ID of the ad group the ad is a part of. Reference:
|
adId
The ad ID. Reference: |
campaignId
The ID of the campaign the ad is a part of. Reference: |
Custom Fields
Columns selected by you. For descriptions of available columns, refer to Microsoft’s documentation. |
age_gender_performance_report
Official docs : |
The age_gender_performance_report
table contains info about the age and gender demographics of people interacting with your campaigns and ad groups.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
campaigns
Replication Method : |
Full Table |
Primary Key |
id |
API endpoint : |
The campaigns
table contains info about the campaigns in your Bing Ads account.
id
The campaign ID. Reference: |
|||
biddingScheme
Details about the bid strategy type used to manage the campaign.
|
|||
budgetId
The ID of the budget that the campaign shares with other campaigns in the account. Refer to Microsoft’s documentation for more info on budgets. |
|||
budgetType
The budget type that determines how the budget is spent. |
|||
campaignType
The type of campaign. |
|||
dailyBudget
The amount to spend daily on the campaign. |
|||
description
The description of the campaign. |
|||
forwardCompatibilityMap
Details about the forward compatibility settings for the campaign.
|
|||
languages
The languages of the ads and keywords in the campaign. |
|||
name
The name of the campaign. |
|||
nativeBidAdjustment
The percent amount by which to adjust the bid for intent ads above or below the base ad group or keyword bid. |
|||
settings
The settings for the campaign.
|
|||
status
The status of the campaign. Possible values are |
|||
timeZone
The timezone where the campaign operates. |
|||
trackingUrlTemplate
The tracking template to use as a default for all URLs in the campaign. |
|||
urlCustomParameters
The custom collection of key and value parameters for URL tracking. |
campaign_performance_report
Official docs : |
The campaign_performance_report
table contains performance data for campaigns, aggregated by day..
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
accountId
The Bing Ads-assigned ID of the account. |
_sdc_report_datetime
The start time of the Stitch replication job that replicated this record. |
gregorianDate
The day the record pertains to. |
campaignId
The ID of the campaign. |
Custom Fields
Columns selected by you. For descriptions of available columns, refer to Microsoft’s documentation. |
geographic_performance_report
Official docs : |
The geographic_performance_report
table contains info about the physical locations of people searching for an ad or the locations people are searching for. This data can be used to validate or improve location targeting strategies.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
goals_and_funnels_report
Official docs : |
The goals_and_funnels_report
table contains information about your audience’s progression through your conversion funnel. Use this report to determine the point at which users leave the funnel, thereby allowing you to improve and increase conversion.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
keyword_performance_report
Official docs : |
The keyword_performance_report
table contains performance data about keywords.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
search_query_performance_report
Official docs : |
The search_query_performance_report
table contains performance data for search terms that resulted in a significant number of clicks in the last 30 days. As this data may change over time, use the keyword_performance_report
table to analyze the overall performance of keywords.
Note: This data in this table is not applicable to Bing Shopping campaigns.
This is a Report table. See the Replication section for information on how data is replicated and loaded for this table.
Related | Troubleshooting |
Questions? Feedback?
Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.