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 Source Type: Web

Event Scope: All Events

Capabilities

Tracks web events like page views, purchases, and cart interactions.
ID Sync captures the Microsoft Click ID (msclkid) for conversion attribution.
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.

Considerations

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.

Limitations

Does not support app events—only web-based tracking is available.

Identity Sync

Sync Available: Yes
Required for Starter Kit: Yes
Prerequisites: Client ID needed
Documentation: Microsoft Ads Sync

Sync Details

The Microsoft Ads sync captures the values of the click ID (msclkid).
The msclkid is essential for conversion attribution and is required by Microsoft Ads for accurate conversion tracking.
Microsoft Ads requires that msclkid only 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. Themid is 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
`mid` Required	String: Page Load ID used to link events to the same session.	`context.providers.microsoftAds.mid`
`vid` Required	String: Guest user anonymous ID.	`anonymousId`
`ip` Required	String: IP address of the user.	`context.ip`
`ua` Required	String: User Agent string of the browser.	`context.userAgent`
`ts` Required	Integer: Timestamp of the event in seconds.	Expression - Converts `timestamp` to Unix epoch.
`ti` Required	String: Microsoft Ads UET tag ID.	Enrichment- `$$UET_TAG_ID$$`
`ver` Required	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
`p` Required	String: URL of the page being tracked.	`context.page.url`
`evt` Required	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
`prodid` Required	String: Comma-separated product IDs in the cart.	Expression - Extracts `product_id` from `properties.products`
`ecomm_totalvalue` Required	Float: Total cart value.	Expression - Sums `(price * quantity)` of all items.
`evt` Required	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
`prodid` Required	String: Product ID of the added product.	`properties.product_id`
`ecomm_totalvalue` Required	Float: Total price of added product.	Expression - `price * quantity`.
`evt` Required	String: Event type for product added event.	Enrichment - `'custom'`
`ea` Required	String: Event action (add to cart).	Enrichment - `'add_to_cart'`
`pageType` Required	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
`prodid` Required	String: Product ID of the viewed product.	`properties.product_id`
`evt` Required	String: Event type for product viewed event.	Enrichment - `'custom'`
`ea` Required	String: Event action (view item).	Enrichment - `'view_item'`
`pageType` Required	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_id` Required	String: Unique order identifier.	`properties.order_id`
`prodid` Required	String: Comma-separated product IDs in the order.	Expression - Extracts `product_id` from `properties.products`.
`ecomm_totalvalue` Required	Float: Total order value.	Expression - Sums `(price * quantity)` of all items.
`evt` Required	String: Event type for order completed event.	Enrichment - `'custom'`
`ea` Required	String: Event action (purchase).	Enrichment - `'purchase'`
`pageType` Required	String: Page category type (purchase).	Enrichment - `'purchase'`
`msclkid` Required	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_term` Required	String: The search query entered by the user.	`properties.query`
`evt` Required	String: Event type for search results viewed.	Enrichment - `'custom'`
`ea` Required	String: Event action (view search results).	Enrichment - `'view_search_results'`
`pageType` Required	String: Page category type (search results).	Enrichment - `'searchresults'`

Product List Viewed

Output Key	Description	Expected Input
`prodid` Required	String: Comma-separated product IDs in the list.	Expression - Extracts `product_id` from `properties.products`.
`evt` Required	String: Event type for product list viewed.	Enrichment - `'custom'`
`ea` Required	String: Event action (view item list).	Enrichment - `'view_item_list'`
`pageType` Required	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.