Bing UET Conversions API
Server-side event delivery to Microsoft Advertising's Universal Event Tracking (UET) Conversions API for enhanced conversion tracking in Microsoft Ads campaigns. Sending from the server avoids browser limitations and improves match quality.
Bing UET CAPI is a server destination in the walkerOS flow:
Sends events server-side to Microsoft's UET Conversions API using raw HTTP (no SDK). Identity fields (`em`, `ph`) are SHA-256 hashed before sending, emails with Microsoft-specific normalization. Events include a stable `eventId` for deduplication with the UET JavaScript tag.
Installation
npm install @walkeros/collector @walkeros/server-destination-bing- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationBing from '@walkeros/server-destination-bing';
await startFlow({
destinations: {
bing: {
code: destinationBing,
config: {
settings: {
accessToken: process.env.BING_ACCESS_TOKEN,
tagId: 'UET-12345',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"bing": {
"package": "@walkeros/server-destination-bing",
"config": {
"settings": {
"accessToken": "$secret.BING_ACCESS_TOKEN",
"tagId": "UET-12345"
}
}
}
}
}
}
}Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
accessToken | string | Long-lived Bing UET CAPI access token from Microsoft Advertising | |
tagId | string | Microsoft Advertising UET tag ID | |
url | string | Custom Bing UET CAPI base URL, ending in / (default https://capi.uet.microsoft.com/v1/) | |
doNotHash | Array<string> | User data fields to skip hashing | |
user_data | Record<string, string> | Mapping for user data fields with Microsoft's key names (em, ph, anonymousId, externalId, msclkid, idfa, gaid), like { em: 'user.email' }. Only em and ph are hashed; any other key is sent unhashed | |
dataProvider | string | Identifier of the data source (default "walkerOS") | |
continueOnValidationError | boolean | When true, Microsoft continues to ingest events despite validation errors | |
ip | any | boolean | Client IP, sent as userData.clientIpAddress. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped userData.clientIpAddress wins. | |
userAgent | any | boolean | Client user agent, sent as userData.clientUserAgent. Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off. A mapped userData.clientUserAgent wins. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
eventType | 'pageLoad' | 'custom' | Override event type: "pageLoad" for page views, "custom" (default) otherwise |
Examples
Add to cart
A product add is sent to Bing UET as an add_to_cart event with value, currency, item details and the visitor's anonymous ID.
{
"name": "product add",
"data": {
"id": "SKU-B2",
"name": "Running Shoes",
"price": 89.99,
"color": "blue"
},
"context": {
"shopping": [
"intent",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"device": "device-456"
},
"nested": [
{
"entity": "product",
"data": {
"id": "SKU-B2",
"name": "Running Shoes",
"price": 89.99,
"quantity": 1
}
}
],
"consent": {
"functional": true
},
"id": "b1c2d3e4f5a60004",
"trigger": "click",
"entity": "product",
"action": "add",
"timestamp": 1700000903000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://shop.example.com/products/running-shoes"
}
}{
"name": "add_to_cart",
"data": {
"map": {
"customData": {
"map": {
"value": "data.price",
"currency": {
"value": "EUR"
},
"items": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
},
"map": {
"id": "data.id",
"name": "data.name",
"price": "data.price",
"quantity": {
"key": "data.quantity",
"value": 1
}
}
}
]
}
}
},
"userData": {
"map": {
"anonymousId": "user.device"
}
}
}
}
}sendServer("https://capi.uet.microsoft.com/v1/UET-12345/events", "{\"data\":[{\"eventType\":\"custom\",\"eventId\":\"b1c2d3e4f5a60004\",\"eventTime\":1700000903,\"adStorageConsent\":\"G\",\"userData\":{\"anonymousId\":\"device-456\"},\"eventName\":\"add_to_cart\",\"eventSourceUrl\":\"https://shop.example.com/products/running-shoes\",\"customData\":{\"value\":89.99,\"currency\":\"EUR\",\"items\":[{\"id\":\"SKU-B2\",\"name\":\"Running Shoes\",\"price\":89.99,\"quantity\":1}]}}],\"dataProvider\":\"walkerOS\"}", {
"headers": {
"Authorization": "Bearer s3cr3t",
"Content-Type": "application/json"
}
})Lead
A newsletter form submission is sent to Bing UET as a lead event with the SHA-256 hashed email.
{
"name": "form submit",
"data": {
"type": "newsletter"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"email": "user@example.com"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "b1c2d3e4f5a60003",
"trigger": "test",
"entity": "form",
"action": "submit",
"timestamp": 1700000902000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://example.com/contact"
}
}{
"name": "lead",
"data": {
"map": {
"userData": {
"map": {
"em": "user.email"
}
}
}
}
}sendServer("https://capi.uet.microsoft.com/v1/UET-12345/events", "{\"data\":[{\"eventType\":\"custom\",\"eventId\":\"b1c2d3e4f5a60003\",\"eventTime\":1700000902,\"adStorageConsent\":\"G\",\"userData\":{\"em\":\"b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514\"},\"eventName\":\"lead\",\"eventSourceUrl\":\"https://example.com/contact\"}],\"dataProvider\":\"walkerOS\"}", {
"headers": {
"Authorization": "Bearer s3cr3t",
"Content-Type": "application/json"
}
})Page view
A page view is sent to the Bing UET CAPI with eventType pageLoad, the visitor's anonymous ID and the source URL.
{
"name": "page view",
"data": {
"domain": "www.example.com",
"title": "walkerOS documentation",
"referrer": "https://www.walkeros.io/",
"search": "?foo=bar",
"hash": "#hash",
"id": "/docs/"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"device": "device-456"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "b1c2d3e4f5a60002",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000901000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://example.com/docs/"
}
}{
"settings": {
"eventType": "pageLoad"
},
"data": {
"map": {
"userData": {
"map": {
"anonymousId": "user.device"
}
}
}
}
}sendServer("https://capi.uet.microsoft.com/v1/UET-12345/events", "{\"data\":[{\"eventType\":\"pageLoad\",\"eventId\":\"b1c2d3e4f5a60002\",\"eventTime\":1700000901,\"adStorageConsent\":\"G\",\"userData\":{\"anonymousId\":\"device-456\"},\"eventSourceUrl\":\"https://example.com/docs/\"}],\"dataProvider\":\"walkerOS\"}", {
"headers": {
"Authorization": "Bearer s3cr3t",
"Content-Type": "application/json"
}
})Purchase
A completed order is sent to the Bing UET CAPI with transaction id, value, items and the visitor's anonymous ID.
{
"name": "order complete",
"data": {
"id": "ORD-300",
"value": 249.99,
"currency": "EUR"
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "user-123",
"device": "device-456"
},
"nested": [
{
"entity": "product",
"data": {
"id": "SKU-A1",
"name": "Widget Pro",
"price": 124.99,
"quantity": 2
}
}
],
"consent": {
"functional": true
},
"id": "b1c2d3e4f5a60001",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000900000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "browser",
"platform": "web",
"url": "https://shop.example.com/checkout/complete"
}
}{
"name": "purchase",
"data": {
"map": {
"customData": {
"map": {
"value": "data.value",
"currency": {
"key": "data.currency",
"value": "EUR"
},
"transactionId": "data.id",
"pageType": {
"value": "purchase"
},
"items": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
},
"map": {
"id": "data.id",
"name": "data.name",
"price": "data.price",
"quantity": {
"key": "data.quantity",
"value": 1
}
}
}
]
}
}
},
"userData": {
"map": {
"anonymousId": "user.device"
}
}
}
}
}sendServer("https://capi.uet.microsoft.com/v1/UET-12345/events", "{\"data\":[{\"eventType\":\"custom\",\"eventId\":\"b1c2d3e4f5a60001\",\"eventTime\":1700000900,\"adStorageConsent\":\"G\",\"userData\":{\"anonymousId\":\"device-456\"},\"eventName\":\"purchase\",\"eventSourceUrl\":\"https://shop.example.com/checkout/complete\",\"customData\":{\"value\":249.99,\"currency\":\"EUR\",\"transactionId\":\"ORD-300\",\"pageType\":\"purchase\",\"items\":[{\"id\":\"SKU-A1\",\"name\":\"Widget Pro\",\"price\":124.99,\"quantity\":2}]}}],\"dataProvider\":\"walkerOS\"}", {
"headers": {
"Authorization": "Bearer s3cr3t",
"Content-Type": "application/json"
}
})Failures
A response outside the 2xx range, a network error, or no answer within 5 seconds fails the event: the push answers failed with the code transport (with the HTTP status) or timeout, the event goes to the dead-letter queue, and the collector logs one ERROR line. Any 2xx answer counts as delivered: the destination does not read the response body. Microsoft answers 200 when it removes an optional field it cannot accept (an em or ph that is not a SHA-256 hash, for example), and with continueOnValidationError: true also when it skips the invalid events of a request, so those events count as delivered too. Without accessToken or tagId the destination does not start: every push answers failed with the code config, and the collector logs destination init failed. A rule with silent: true sends nothing.
Client IP and user agent
The destination sends the client IP as userData.clientIpAddress and the user agent as userData.clientUserAgent by default. The ip and userAgent settings resolve against { ingest, event } and default to ["ingest.ip", "event.user.ip"] and ["ingest.userAgent", "event.user.userAgent"], so they fill in whenever the source provides them (see the config.ingest recipe on the Express source). A value your mapping sets for userData.clientIpAddress or userData.clientUserAgent wins. A value that resolves to nothing is not sent. Set either setting to false to turn it off, or to another mapping value to read it elsewhere.
Consent
Every event this destination sends carries adStorageConsent: "G" (granted), and Microsoft processes an event as granted unless it says D. The quickstart sets no config.consent, so Microsoft receives every event marked as granted, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).
Event types
Bing UET distinguishes two event types. Set the type via mapping.settings.eventType:
eventType | When to use |
|---|---|
pageLoad | Page view events (no eventName required) |
custom | All other conversion events (default, requires eventName) |
"mapping": {
"page": {
"view": {
"settings": { "eventType": "pageLoad" }
}
},
"order": {
"complete": {
"name": "purchase",
"data": {
"map": {
"customData": {
"map": {
"value": "data.value",
"currency": "data.currency",
"transactionId": "data.id",
"pageType": { "value": "purchase" }
}
}
}
}
}
}
}customData structure
Map event properties under customData; every other key of config.data and of a rule's data except userData lands in customData too. Common fields include value, currency, transactionId, items, itemIds, pageType, eventCategory, eventLabel, eventValue, searchTerm.
Hashing
Map identity fields with Microsoft's key names under userData in a rule's data or the destination's config.data, or in settings.user_data. No identifier is read from event.user on its own; only the client IP and user agent are filled in from it (see Client IP and user agent). The destination SHA-256 hashes em (email) and ph (phone) before sending.
- Every other key is sent in clear text.
anonymousId,externalId,msclkid,clientIpAddress,clientUserAgent,idfaandgaidare sent as mapped, and so is any other key: nothing checks the names underuserData, soemailorphoneinstead ofemandphreaches Microsoft unhashed. Every other key ofconfig.dataand of a rule'sdata, auser_dataobject included, lands incustomData, unhashed. anonymousIdandexternalIdare not hashed. Microsoft asks never to send real user IDs, so map an anonymized or hashed ID there, such as the walkerOSuser.device, not a login or customer ID.- Every event needs an identifier. Microsoft requires at least one of
em,ph,anonymousId,externalId,msclkid,idfaorgaidinuserData. The client IP and user agent do not count, and the quickstart maps none, so map at least one. - Phone numbers are hashed as mapped, only trimmed: map them in E.164 format (
+14255551234), as Microsoft requires. - Map one value per key. A list is joined with commas and hashed as one string.
Microsoft-specific email normalization
Before hashing, emails are normalized to match Microsoft's canonicalization:
- Trim whitespace
- Lowercase the entire address
- Remove dots from the user portion (
a.b.c@example.combecomesabc@example.com) - Strip
+aliassuffix (user+promo@example.combecomesuser@example.com)
- Emails can be mapped raw; the destination normalizes them as above.
If a value is already hashed or you want to skip hashing for a specific field, use doNotHash. A doNotHash key is sent exactly as mapped, and Microsoft removes an em or ph that is not a SHA-256 hash:
"settings": {
"accessToken": "$secret.BING_ACCESS_TOKEN",
"tagId": "YOUR_UET_TAG_ID",
"doNotHash": ["em"]
}Deduplication
Each event is sent with eventId set to the walkerOS event id. If you also run the UET JavaScript tag in the browser, Microsoft deduplicates server and browser events that share the same eventId and eventName, so conversions are not double-counted. Use the same UET tag on both sides and set the rule's name to the UET event action: without a name, the walkerOS event name (like order complete) is sent as eventName.