Microsoft Ads
This integration is currently in beta. Contact your MetaRouter support team to get started.
What Is Microsoft Ads?
Microsoft Ads is a digital advertising platform that enables businesses to create and manage search, shopping, and audience-based ad campaigns. It provides advanced targeting options, including keyword-based bidding, remarketing, and automated optimizations to improve ad performance. The platform includes tools for budget management, performance tracking, and conversion measurement to help advertisers maximize their return on investment.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Type: Web
Capabilities and Considerations
- Tracks web events like page views, purchases, and cart interactions.
- ID Sync captures the Microsoft Click ID (msclkid) for conversion attribution.
- The
msclkid(Microsoft Click ID) is only required for conversion events to ensure accurate attribution. It should not be mapped to non-conversion events, as doing so may cause Microsoft Ads to incorrectly classify non-conversion events as conversions. - By default,
msclkidhas been mapped to the Order Completed event. If you have additional conversion events, you must manually mapmsclkidto those events to ensure proper attribution.
- The
- Sends event data server-to-server without needing a browser tag.
- Supports user identification with hashed email, phone, and user IDs.
- Allows custom event mapping for additional conversion tracking.
- Includes referrer, page URL, and user agent for attribution.
Limitations
- Does not support app events—only web-based tracking is available.
Identity Sync
- Sync Available: Yes
- Required for Starter Kit: Yes
- Documentation: Microsoft Ads Sync
Sync Details
- The Microsoft Ads sync captures the values of the click ID (
msclkid). - The
msclkidis essential for conversion attribution and is required by Microsoft Ads for accurate conversion tracking. - Microsoft Ads requires that
msclkidonly be mapped to your conversion events within the starter kit. Please do not add the click ID to global mapping; otherwise, Microsoft Ads will consider all events a conversion. - The sync generates a
mid(Page Load ID) for each page view and attaches it to all related events. Themidis required to properly link events to a session.
Starter Kit Setup Guide
1. Deploy the Microsoft Ads Sync
- To collect the sync values (e.g.,
msclkid,mid), you must implement a Microsoft Ads ID sync. Refer to the following documentation to complete the setup: Microsoft Ads - ID Sync Guide.
2. Gather Credentials
- UET Tag ID
- From your Microsoft Ads account, go to Conversion > UET Tag. You may find your tag ID from an already existing tag in this view or create a new tag.
- There is no special S2S setting or requirement at the tag level, but Microsoft recommends creating a new UET tag for S2S events rather than mixing them with JavaScript-based UET events unless necessary.
3. Add a Microsoft Ads Integration
From the integration library, add a Microsoft Ads integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|---|
UET_TAG_ID | The UET tag ID is a unique identifier in Microsoft Ads that links event data to a specific Universal Event Tracking (UET) tag for tracking and attribution. |
3. Configure Event Mapping
- MetaRouter provides all of the event mappings that Microsoft Ads integrations typically require. You may add custom events, parameters or mappings in accordance with Microsoft Ad’s API standards. Please see below for details on event mapping.
4. Deploy to Pipeline
- In the Pipelines tab, add your Microsoft Ads integration.
- Select the correct integration revision
- Click Add Integration to finalize deployment.
Event Mappings
Global
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|---|---|
midRequired | String: Page Load ID used to link events to the same session. | context.providers.microsoftAds.mid |
vidRequired | String: Guest user anonymous ID. | anonymousId |
ipRequired | String: IP address of the user. | context.ip |
uaRequired | String: User Agent string of the browser. | context.userAgent |
tsRequired | Integer: Timestamp of the event in seconds. | Expression - Converts timestamp to Unix epoch. |
tiRequired | String: Microsoft Ads UET tag ID. | Enrichment- $$UET_TAG_ID$$ |
verRequired | String: UET version used in requests. | Enrichment - '2.2' |
el | String: Event name extracted from track call. | Expression - Extracts event from input. |
pid | String: Hashed user email and phone number. | Expression - SHA256 hash of email and phone. |
uid | String: Hashed user ID if available. | Expression - Hashes userId using MD5 if present. |
Event Specific
Page
| Output Key | Description | Expected Input |
|---|---|---|
pRequired | String: URL of the page being tracked. | context.page.url |
evtRequired | String: Event type. | Enrichment - 'pageLoad' |
r | String: Referrer URL of the page. | context.page.referrer |
tl | String: Title of the page being viewed. | context.page.title |
Cart Viewed
| Output Key | Description | Expected Input |
|---|---|---|
prodidRequired | String: Comma-separated product IDs in the cart. | Expression - Extracts product_id from properties.products |
ecomm_totalvalueRequired | Float: Total cart value. | Expression - Sums (price * quantity) of all items. |
evtRequired | String: Event type for cart viewed event. | Enrichment - 'custom' |
items | String: List of purchased items in URL-encoded format. | Expression - Maps products array into required format. |
gv | Float: Total cart value (used for revenue tracking). | Expression - Sums (price * quantity) of all items. |
gc | String: Three-letter currency code (e.g., USD). | properties.currency |
pageType | String: Page category type (cart). | Enrichment - 'cart' |
Product Added
| Output Key | Description | Expected Input |
|---|---|---|
prodidRequired | String: Product ID of the added product. | properties.product_id |
ecomm_totalvalueRequired | Float: Total price of added product. | Expression - price * quantity. |
evtRequired | String: Event type for product added event. | Enrichment - 'custom' |
eaRequired | String: Event action (add to cart). | Enrichment - 'add_to_cart' |
pageTypeRequired | String: Page category type (product). | Enrichment - 'product' |
items | String: Product details in URL-encoded format. | Expression - Maps product_id, price, quantity. |
gv | Float: Total price of added product. | Expression - price * quantity. |
gc | String: Three-letter currency code (e.g., USD). | properties.currency |
Product Viewed
| Output Key | Description | Expected Input |
|---|---|---|
prodidRequired | String: Product ID of the viewed product. | properties.product_id |
evtRequired | String: Event type for product viewed event. | Enrichment - 'custom' |
eaRequired | String: Event action (view item). | Enrichment - 'view_item' |
pageTypeRequired | String: Page category type (product). | Enrichment - 'product' |
items | String: Product details in URL-encoded format. | Expression - Maps product_id, price, quantity. |
Order Completed
| Output Key | Description | Expected Input |
|---|---|---|
transaction_idRequired | String: Unique order identifier. | properties.order_id |
prodidRequired | String: Comma-separated product IDs in the order. | Expression - Extracts product_id from properties.products. |
ecomm_totalvalueRequired | Float: Total order value. | Expression - Sums (price * quantity) of all items. |
evtRequired | String: Event type for order completed event. | Enrichment - 'custom' |
eaRequired | String: Event action (purchase). | Enrichment - 'purchase' |
pageTypeRequired | String: Page category type (purchase). | Enrichment - 'purchase' |
msclkidRequired | String: Microsoft Click ID for conversion attribution. | context.providers.microsoftAds.msclkid |
items | String: List of purchased items in URL-encoded format. | Expression - Maps products array into required format. |
gv | Float: Total order value (used for revenue tracking). | Expression - Sums (price * quantity) of all items. |
gc | String: Three-letter currency code (e.g., USD). | properties.currency |
Products Searched
| Output Key | Description | Expected Input |
|---|---|---|
search_termRequired | String: The search query entered by the user. | properties.query |
evtRequired | String: Event type for search results viewed. | Enrichment - 'custom' |
eaRequired | String: Event action (view search results). | Enrichment - 'view_search_results' |
pageTypeRequired | String: Page category type (search results). | Enrichment - 'searchresults' |
Product List Viewed
| Output Key | Description | Expected Input |
|---|---|---|
prodidRequired | String: Comma-separated product IDs in the list. | Expression - Extracts product_id from properties.products. |
evtRequired | String: Event type for product list viewed. | Enrichment - 'custom' |
eaRequired | String: Event action (view item list). | Enrichment - 'view_item_list' |
pageTypeRequired | String: Page category type (category). | Enrichment - 'category' |
items | String: List of product details. | Expression - Maps products array. |
ecomm_category | String: Category ID of the product list. | properties.list_id |
Required & Recommended Identifiers
These identifiers must be mapped to Microsoft Ads in order for successful user matching to occur. Without these IDs, any events sent to Microsoft Ads may not be accurately reflected in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.
| Attribute | Example | Sync Injector Required? |
|---|---|---|
| msclkid *Required | dd4afcccb1c9a4cad9544dd7e5006 | Yes |
| vid | b171a9b06ce011ecafcd1b209be8601b | No |
| ip | 192.168.1.1 | No |
| ua | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 | No |
| pid | em=ec81f3ac7b2b19675bab9d54cf416f9f18cff87c97da5cca82c0f0891bc40602&ph=c59475d96e9f01d7d18d06cfad84dd02333207f02c0c2c5663ef2782cda0390e | No |
| uid | e6f5c1a4c8b1440bb6a5a2c472c1d0fc | No |
*The msclkid (Microsoft Click ID) is only required for conversion events to ensure accurate attribution. It should not be mapped to non-conversion events, as doing so may cause Microsoft Ads to incorrectly classify non-conversion events as conversions.
By default, msclkid has been mapped to the Order Completed event. If you have additional conversion events, you must manually map msclkid to those events to ensure proper attribution.
Integration Validation
- To validate your integration, log in to your Microsoft Ads account and check the UET tag dashboard for the following:
- Events are appearing under the configured tag.
- Conversions are accurately attributed to campaigns and ad clicks.
- Verify that conversions are appearing correctly in your Microsoft Ads reporting.
Updated 7 days ago