Microsoft Advertising integration plan
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Bing Ads API | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ | ✅ |
Bing Ads API is the advertising API of Microsoft Advertising. Its Reporting API provides a series of APIs for querying ad data reports. The AE system currently supports pulling data of the AdPerformanceReport report type.
Integration process
The process for connecting Microsoft Advertising data is as follows:
- Log in to the Azure portal, create an app, and generate the app's Client Secret
- Log in to the AE backend, go to the Third-party Integration module, add a Microsoft Advertising plan, enter the authorization information such as the Client ID and Client Secret, and complete the related configuration
- Add the authorization URL in the Authorization Information pop-up as a redirect URI of the Azure app, then go back to the AE backend and log in to your Microsoft account to complete authorization
- Check whether the AE system receives the data successfully, and build reports
1. Register an app and get the authorization information
1.1 Register an app and get the Client ID and Secret
Before you use Bing Ads API to pull data, you need an Azure app. If you haven't created one yet, follow this section to create it
- Log in to the Azure portal with your Microsoft account
- Click Register an application
- On the Register an application page, enter an app name (custom). Under Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox), and click Register to create the app
- After the app is created, you can view the app's Application (client) ID (the Client ID) in the Essentials section of the Overview page
- Click Add a certificate or secret. On the Certificates & secrets page, click + New client secret, enter a description and an expiration (no specific requirements), and create the client secret (the Client Secret). Before you leave the page, copy and save the secret value in the red box in the image below.
If you aren't sure how to return to the app settings page after creating the app, search for App registrations in the top search bar of the Azure portal
1.2 Get the Developer Token
Next, if you also need to get a Developer Token, go to the Microsoft Advertising developer portal (if you aren't logged in, log in with the Microsoft account of the ad account). Click Request Token to apply for a Developer Token. After the application succeeds, save the Developer Token. (If you are managing someone else's account, it may take up to five business days to get the Developer Token)
1.3 Get the account ID and customer ID of the ad account
Finally, you also need to get the account ID and customer ID of the ad account from which you want to pull data. Log in to the Microsoft Advertising dashboard and switch to the ad account you want to pull data from in the upper-left corner of the page. In the browser address bar, you can see the aid and cid parameters: aid is the account ID of the ad account, and cid is its customer ID. Save both IDs.
You have now completed all the preparation for integrating Microsoft Advertising data. Here is a summary of all the authorization information you obtained:
- Client ID
- Client Secret
- Developer Token
- Ad account Account ID
- Ad account Customer ID
2. Plan configuration
After completing the preparation on the Microsoft Advertising platform, you can log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the Microsoft Advertising configuration page. Follow this section to create the plan
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information and enter the information you obtained in the previous step in the pop-up:
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull Microsoft Advertising Bing Ads API data on a schedule. You can choose to pull data for a period of time at a specific time every day. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Receive Settings
You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.
2.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable |
| source | metrics | Metrics in the data; list type; customizable |
| group_by | Grouping dimensions in the data; list type; customizable |
The following lists commonly used fields available in AdPerformanceReport. For all fields, see the Bing Ads API official documentation:
- Grouping dimensions
The following are commonly used grouping dimensions. To change them, enter the field names in source.group_by:
| Field | Description | Default |
|---|---|---|
| TimePeriod | Time | Yes |
| AccountName | Ad account name | Yes |
| AccountNumber | Ad account number | Yes |
| AccountId | Ad account ID | Yes |
| AccountStatus | Ad account status | |
| CampaignName | Campaign name | Yes |
| CampaignId | Campaign ID | Yes |
| CampaignStatus | Campaign status | |
| CampaignType | Campaign type | Yes |
| AdGroupName | Ad group name | Yes |
| AdGroupId | Ad group ID | Yes |
| AdGroupStatus | Ad group status | |
| AdTitle | Ad name | Yes |
| AdId | Ad ID | Yes |
| AdDescription | Ad description 1 | |
| AdDescription2 | Ad description 2 | |
| AdType | Ad type | Yes |
| AdStatus | Ad status | |
| AdLabels | Ad labels | |
| CurrencyCode | Billing currency code | Yes |
| AdDistribution | Media source type | Yes |
| Network | Media source | Yes |
| TopVsOther | Impression position (placement) | Yes |
| BidMatchType | Bid match type | |
| CustomerId | Customer ID of the ad account | |
| CustomerName | Customer name of the ad account | |
| CustomParameters | Custom parameters | |
| DestinationUrl | Destination URL | |
| DisplayUrl | Ad display URL | |
| DeliveredMatchType | Delivered match type | |
| DeviceType | Device Type | Yes |
| Language | Language | Yes |
| DeviceOS | Device OS | Yes |
| Goal | Conversion goal | |
| GoalType | Conversion goal type |
- Metric fields
The following are commonly used metric fields. To change them, enter the metric field names in source.metrics:
| Metric field | Description | Remarks | Default |
|---|---|---|---|
| Impressions | Impressions | Yes | |
| Clicks | Clicks | Yes | |
| Ctr | Click-through rate | Yes | |
| AverageCpc | Average CPC | Yes | |
| AverageCpm | Average CPM | Yes | |
| Spend | Total spend | Yes | |
| Conversions | Conversions (deprecated) |
| |
| ConversionsQualified | Conversions (new version, may be unavailable) | ||
| ConversionRate | Conversion rate | ||
| Revenue | Revenue | ||
| RevenuePerConversion | Average conversion revenue | ||
| CostPerConversion | Average conversion cost | ||
| ReturnOnAdSpend | ROAS | ||
| AllConversions | All conversions (deprecated) |
| |
| AllConversionsQualified | All conversions (new version, may be unavailable) | ||
| AllConversionRate | All conversion rate | ||
| AllRevenue | Total revenue | ||
| AllRevenuePerConversion | Average all-conversion revenue | ||
| AllCostPerConversion | Average all-conversion cost | ||
| AllReturnOnAdSpend | All-conversion ROAS | ||
| Assists | Assists | ||
| CostPerAssist | Average cost per assist | ||
| RevenuePerAssist | Average revenue per assist | ||
| AbsoluteTopImpressionRatePercent | Absolute top impression rate | Share of total impressions shown in the first position of search results | |
| TopImpressionRatePercent | Top impression rate | Share of total impressions shown in the search results | |
| ViewThroughConversionsQualified | View-through conversions (new version, may be unavailable) | ||
| ViewThroughConversions | View-through conversions (deprecated) |
2.5 Data ingestion rules
- The TimePeriod field in the data, that is, the date of the data, is used as the #event_time of the aggregated data
- The event name is bing_ads_adperformance
- All other fields are stored
2.6 Complete authorization
After completing the configuration, click Save and authorize in the upper right corner to save the plan configuration. Next, you need to complete the final authorization:
First, in the Authorization Information page that pops up, copy the URL in the first step
Next, go to the Azure portal. In the Essentials section of the app's Overview page, click Add a Redirect URI. On the new page, click Add a platform, enter the authorization URL in the Redirect URIs box, and click Configure and then Save to finish configuring the callback URL.
After configuring the callback URL, go back to the AE backend and click the Go to authorization button in the Authorization Information pop-up. On the page that opens, log in to the Microsoft account bound to the ad account you want to connect, and complete authorization.
After completing authorization, in Authorization Information, click I have completed the above two steps in the lower-left corner, and then click Complete Authorization in the lower-right corner to finish the configuration. You have now completed the Microsoft Advertising data integration.
2.7 Standardized fields
The AE system standardizes some fields in Microsoft Advertising Bing Ads API data:
| Field | Standardized field | Description |
|---|---|---|
| accountid | te_ads_object.ad_account_id | Ad account ID |
| campaignname | te_ads_object.campaign_name | Campaign name |
| campaignid | te_ads_object.campaign_id | Campaign ID |
| adgroupname | te_ads_object.ad_group_name | Ad group name, or the Unit name for monetization ads |
| adgroupid | te_ads_object.ad_group_id | Ad group ID, or the Unit ID for monetization ads |
| adtitle | te_ads_object.ad_name | Ad name |
| adid | te_ads_object.ad_id | Ad ID |
| topvsother | te_ads_object.placement | Ad placement |
| network | te_ads_object.media_source | Media source or monetization channel |
| currencycode | te_ads_object.currency | Currency of the cost or revenue |
| impressions | te_ads_object.impressions | Impressions |
| clicks | te_ads_object.clicks | Clicks |
| spend | te_ads_object.cost | User acquisition cost |
| revenue | te_ads_object.revenue | Revenue |