Microsoft Conversions API

This destination is currently under final review and will be available soon.

Microsoft Advertising (formerly Bing Ads, Microsoft adCenter and MSN adCenter) is an online advertising platform developed by Microsoft. Using this destination, you can leverage Microsoft Conversions API and the Universal Event Tracking (UET) framework to send user actions, in form of events, via server-side tracking hits, enabling features such as conversion tracking (E.g., purchases or leads), audience targeting (E.g., remarketing), automated bidding, and integration with Microsoft Bing for Commerce.

Key features

The Microsoft Conversions API destination provides the following key features:

• Events structure: our Events reference supports Microsoft's Server-side UET events, meaning that your data is properly bridged to the expected fields in an optimized way.

• Prebuilt mappings: data mapping for event-based destinations happens automatically, which simplifies user inputs.

• Automatic hashing: information is automatically hashed matching partner specifications.

• Custom events and properties: you can freely push custom events and properties based on your specific needs.

• Smart mapping: data mapping can be readjusted using your datalayer defined fields.

• Support for multi-item data: information included in the item array is bridged to Microsoft.

• Support batch mode: send multiple events in one single request.

Destination setup

Ensure you have access to Microsoft Advertising.

This destination can be used as a stand-alone or together with the UET client-side JavaScript tracking. While data is captured using this destination, a client-side user identification sync pixel can also be used to connect Microsoft and customer-assigned user identifiers. The sync pixel can be found in our client-side template library with the name Bing - Client-side id-sync and data capture and is recommended for conversion measurement as it’s required for remarketing and audience building because these features rely on user identity resolution. More details are available at the following LINK.

In the scenario where you use the same UET Tag Id (See Configuration) for both UET client-side JavaScript and this destination, it's important to set up the deduplication. Please refer to this LINK, showing how to set the value for the event_id in the UET client-side JavaScript. The eventId (See Field mappings) can be set using the "Smart Mapping" field Event Id . Both event_id and eventId must be set with the same value.

Configuration

Settings	Description
Access Token	Required Input your Access Token. You can find it in Microsoft Advertising Ads UI by selecting Conversions (left-side menu) → EUT tag → hover over the tag name and click the pencil → In Edit UET tag , click Save and next → Select Use Conversions API .
UET Tag Id	Required Your UET Tag Id . You can find it in Microsoft Advertising Ads UI by selecting Conversions (left-side menu) → EUT tag → column Tag ID .
Click Id Cookie Name	The msclkid (Click Id) is used in conversion attribution and is generated at ad click time. This id is appended to the landing page URL when Microsoft auto-tagging is enabled. It should be stored in a first party cookie and persisted for each user for 90 days or until the user generates a new msclkid by clicking on another ad, whichever comes first. Input your cookie name holding the value. Default: _uetmsclkid. More details are available at the following LINK. You can also add the value in a property and use the "Smart Mapping" field Microsoft Msclkid which has priority over the Click Id Cookie Name . This destination also tries to get the value from the page URL using the property mapped in the "Smart Mapping" field Page URL .

Quick reference

Commanders Act Events	Microsoft Event Types
page_view	pageLoad
[Any other event]	custom

Field mappings

Most properties can be remapped using our "Smart Mapping" feature.

Commanders Act Properties	Microsoft Properties
(event_name)	eventType [1]
context.event_id	eventId [2]
event_name	eventName
context.event_timestamp	eventTime
context.page.url	eventSourceUrl
context.device.lifecycle.session_id	pageLoadId [3]
context.page.referrer	referrerUrl
context.page.title	pageTitle
partners.microsoft.keyword	keywords
partners.microsoft.ad_storage_consent	adStorageConsent
context.device.user_agent	clientUserAgent [4]
user.consistent_anonymous_id	anonymousId
user.id	externalId
user.email	em [5]
user.phone	ph [5][6]
context.device.ip	clientIpAddress
partners.microsoft.msclkid Click Id Cookie Name (context.page.url)	msclkid [7]
context.device.advertising_id	gaid [8]
context.device.advertising_id	idfa [9]
event_category	eventCategory [10]
event_label	eventLabel [10]
value	eventValue [10] ecommTotalValue [10] hotelData.totalPrice [10]
revenue	value [10] hotelData.basePrice [10]
search_term	searchTerm [10]
id	transactionId [10]
currency	currency [10]
items.X.id	items.X.id [10]
items.X.product.price	items.X.price [10]
items.X.quantity	items.X.quantity [10]
items.X.product.name	items.X.name [10]
items.X.id	itemIds [10][11]
(page_type) (event_name)	pageType [10][12]
item_list_name	ecommCategory [10]
partners.microsoft.hotel_checkin_date	hotelData.checkinDate [10]
partners.microsoft.hotel_checkout_date	hotelData.checkoutDate [10]
partners.microsoft.hotel_length_stay	hotelData.lengthOfStay [10]
partners.microsoft.hotel_partner_id	hotelData.partnerHotelId [10]

[1] See Quick reference for more details. [2] Used for deduplication. See Destination setup for more details. [3] Page load identifier that links your custom events from the same page. Format as a v4 UUID. [4] Set in the userData . [5] Automatically normalized and hashed via SHA256 when provided in clear text. [6] Normalized using E.164 format with country code. [7] Priority on the left column. You use the field Click Id Cookie Name (See Configuration) to set a different cookie name instead of the default _uetmsclkid . The value will be automatically retrieved from the context.page.url if present. [8] Set if context.device.os.name is set with Android (Case insensitive). [9] Set if context.device.os.name is set with iOS (Case insensitive). [10] Set in the customData . [11] All product identifiers are taken into account. [12] Priority on the left column. This is set depending on the following: • If page_type is home , product , cart , category , other , purchase or searchresults then pageType is set with the same value . • If page_type is product_list then pageType is category . • If page_type is funnel_confirmation then pageType is purchase . • If page_type is search then pageType is searchresults . • If event_name is search then pageType is searchresults . • If event_name is view_item_list then pageType is category . • If event_name is view_item then pageType is product . • If event_name is view_item or add_to_cart then pageType is product . • If event_name is view_cart then pageType is cart . • If event_name is purchase then pageType is purchase .