Skip to main content
Ask your AI

Bing UET Conversions API

Server Source code Package Beta

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.

Where this fits

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
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',
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
accessToken*stringLong-lived Bing UET CAPI access token from Microsoft Advertising
tagId*stringMicrosoft Advertising UET tag ID
urlstringCustom Bing UET CAPI base URL, ending in / (default https://capi.uet.microsoft.com/v1/)
doNotHashArray<string>User data fields to skip hashing
user_dataRecord<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
dataProviderstringIdentifier of the data source (default "walkerOS")
continueOnValidationErrorbooleanWhen true, Microsoft continues to ingest events despite validation errors
ipany | booleanClient IP, sent as userData.clientIpAddress. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off. A mapped userData.clientIpAddress wins.
userAgentany | booleanClient 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.
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

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

Event
{
  "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"
  }
}
Mapping
{
  "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"
        }
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "name": "lead",
  "data": {
    "map": {
      "userData": {
        "map": {
          "em": "user.email"
        }
      }
    }
  }
}
Out
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.

Event
{
  "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/"
  }
}
Mapping
{
  "settings": {
    "eventType": "pageLoad"
  },
  "data": {
    "map": {
      "userData": {
        "map": {
          "anonymousId": "user.device"
        }
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
        }
      }
    }
  }
}
Out
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.

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:

eventTypeWhen to use
pageLoadPage view events (no eventName required)
customAll 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, idfa and gaid are sent as mapped, and so is any other key: nothing checks the names under userData, so email or phone instead of em and ph reaches Microsoft unhashed. Every other key of config.data and of a rule's data, a user_data object included, lands in customData, unhashed.
  • anonymousId and externalId are not hashed. Microsoft asks never to send real user IDs, so map an anonymized or hashed ID there, such as the walkerOS user.device, not a login or customer ID.
  • Every event needs an identifier. Microsoft requires at least one of em, ph, anonymousId, externalId, msclkid, idfa or gaid in userData. 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:

  1. Trim whitespace
  2. Lowercase the entire address
  3. Remove dots from the user portion (a.b.c@example.com becomes abc@example.com)
  4. Strip +alias suffix (user+promo@example.com becomes user@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.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)