Microsoft Conversions API

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 for Microsoft custom event type (See Quick reference). Please refer to this LINK, showing how to set the value for the event_id in the UET client-side JavaScript tag. 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

Properties can be remapped using our Smart Mapping feature.

Smart Mapping Fields	Commanders Act Default Properties	Microsoft Properties
-	event_name	eventType [1]
Event Id	context.event_id	eventId [2]
Event Action	event_name	eventName
Event Timestamp	context.event_timestamp	eventTime
Page URL	context.page.url	eventSourceUrl
Page Load Id	context.device.lifecycle.session_id	pageLoadId [3]
Page Referrer	context.page.referrer	referrerUrl
Page Title	context.page.title	pageTitle
Microsoft Keyword	partners.microsoft.keyword	keywords
Ad Storage Consent	partners.microsoft.ad_storage_consent	adStorageConsent
Device User Agent	context.device.user_agent	clientUserAgent [4]
User Anonymous Identifier	user.consistent_anonymous_id	anonymousId
User Identifier	user.id	externalId
User Email	user.email	em [5]
User Phone	user.phone	ph [5][6]
Device IP	context.device.ip	clientIpAddress
Microsoft Msclkid - Page URL	partners.microsoft.msclkid Click Id Cookie Name context.page.url	msclkid [7]
Device Mobile Identifier	context.device.advertising_id	gaid [8] idfa [9]
Event Category	event_category	eventCategory [10]
Event Label	event_label	eventLabel [10]
Transaction Value Ecommerce Total Value Hotel Booking Value	value	eventValue [10] ecommTotalValue [10] hotelData.totalPrice [10]
Transaction Revenue Hotel Booking Revenue	revenue partners.microsoft.hotel_revenue	value [10] hotelData.basePrice [10]
Search Term	search_term	searchTerm [10]
Transaction Id	id	transactionId [10]
Currency	currency	currency [10]
Item Id	items.X.id	items.X.id [10] itemIds [10][11]
Item Price	items.X.product.price	items.X.price [10]
Item Quantity	items.X.quantity	items.X.quantity [10]
Item Name	items.X.product.name	items.X.name [10]
Page Type -	page_type event_name	pageType [10][12]
Category Identifier	item_list_name	ecommCategory [10]
Hotel CheckIn Date	partners.microsoft.hotel_checkin_date	hotelData.checkinDate [10]
Hotel CheckOut Date	partners.microsoft.hotel_checkout_date	hotelData.checkoutDate [10]
Hotel Length of Stay	partners.microsoft.hotel_length_stay	hotelData.lengthOfStay [10]
Hotel Partner Id	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 .