Documentation

Microsoft Ads

Suggest Edits

📘

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 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. The mid 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 ParameterDescription
UET_TAG_IDThe 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 KeyDescriptionExpected 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'
elString: Event name extracted from track call.Expression - Extracts event from input.
pidString: Hashed user email and phone number.Expression - SHA256 hash of email and phone.
uidString: Hashed user ID if available.Expression - Hashes userId using MD5 if present.

Event Specific

Page

Output KeyDescriptionExpected Input
p
Required		String: URL of the page being tracked.context.page.url
evt
Required		String: Event type.Enrichment - 'pageLoad'
rString: Referrer URL of the page.context.page.referrer
tlString: Title of the page being viewed.context.page.title

Cart Viewed

Output KeyDescriptionExpected 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'
itemsString: List of purchased items in URL-encoded format.Expression - Maps products array into required format.
gvFloat: Total cart value (used for revenue tracking).Expression - Sums (price * quantity) of all items.
gcString: Three-letter currency code (e.g., USD).properties.currency
pageTypeString: Page category type (cart).Enrichment - 'cart'

Product Added

Output KeyDescriptionExpected 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'
itemsString: Product details in URL-encoded format.Expression - Maps product_id, price, quantity.
gvFloat: Total price of added product.Expression - price * quantity.
gcString: Three-letter currency code (e.g., USD).properties.currency

Product Viewed

Output KeyDescriptionExpected 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'
itemsString: Product details in URL-encoded format.Expression - Maps product_id, price, quantity.

Order Completed

Output KeyDescriptionExpected 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
itemsString: List of purchased items in URL-encoded format.Expression - Maps products array into required format.
gvFloat: Total order value (used for revenue tracking).Expression - Sums (price * quantity) of all items.
gcString: Three-letter currency code (e.g., USD).properties.currency

Products Searched

Output KeyDescriptionExpected 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 KeyDescriptionExpected 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'
itemsString: List of product details.Expression - Maps products array.
ecomm_categoryString: 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.

AttributeExampleSync Injector Required?
msclkid
*Required		dd4afcccb1c9a4cad9544dd7e5006Yes
vidb171a9b06ce011ecafcd1b209be8601bNo
ip192.168.1.1No
uaMozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36No
pidem=ec81f3ac7b2b19675bab9d54cf416f9f18cff87c97da5cca82c0f0891bc40602&ph=c59475d96e9f01d7d18d06cfad84dd02333207f02c0c2c5663ef2782cda0390eNo
uide6f5c1a4c8b1440bb6a5a2c472c1d0fcNo

*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.

Integration Change Log

Updated 21 days ago