Microsoft Invest - User ID mapping with getUID and mapUID
You may have internal offline data about users that you need to insert into the Microsoft Advertising Server Side Cookie Store so that it is available for decisioning. If so, we must first map your internal user IDs and Microsoft Advertising user IDs in order to be able to match user IDs on future requests. Depending on whether you will store the mapping in your system or in ours, there are two ways to do this through pixel calls: mapUID and getUID.
The getUID service retrieves the Microsoft Advertising ID so you can coordinate it with your own in-house ID server side or in your own cookie space. Then you can pass in an offline data feed that says, "update Microsoft Advertising user ABC with the following segment data." The mapUID service passes your internal ID to us for mapping to the Microsoft Advertising ID within the Microsoft Advertising cookie store.
Note
The Microsoft Advertising user ID macro described below is $UID. Unlike many of our other macros, it does not have curly braces.
Basic mapping example
| Field | ID/Value |
|---|---|
| Prostarr User ID | PS123 |
| Microsoft Advertising User ID | 2894234234 |
| Shoe buyer Segment ID | 0005 |
If the advertiser Prostarr tells us that user PS123 is in segment 0005, this will mean nothing to us. Instead, they have to tell us that user 2894234234 is in segment 0005.
To do this, Prostarr has done a previous mapping of all Microsoft Advertising and Prostarr Sportswear user IDs using the GetUID service and stored that mapping in its internal database. A getUID call looks like
https://ib.adnxs.com/getuid?URL
where the URL is the the one you want the mapping directed to. This pixel is placed on Prostarr's webpages, and when it fires, the Impression Bus inserts the Microsoft Advertising user ID into the URL by replacing the $UID macro.
Tip
For a detailed walk-through of how this works, see the User Mapping Visual and Walk-Through.
getUID service
A URL of your choice will receive a client-side call with the Microsoft Advertising user ID as a querystring parameter. During the ad call, Microsoft Advertising redirects the user to the member's desired URL. The Impression Bus inserts the Microsoft Advertising user ID into the URL, either by replacing a $UID macro, or by appending it to the end of the URL. When the user does not have an Microsoft Advertising cookie, "0" is returned and Microsoft Advertising attempts to create one. However, if the user is encountering the getuid call for the first time, "0" will not be returned.
Code
The format of the getUID Service is fairly simple:
https://ib.adnxs.com/getuid?URL
The secure version uses this format:
https://secure.adnxs.com/getuid?URL
Users without cookies or users who have opted out will be redirected with a user ID of 0. If you would prefer not to receive user IDs of 0, use this format:
https://ib.adnxs.com/getuidnb?URL
If you need the URL to remain URI-encoded, use this format:
https://ib.adnxs.com/getuidu?URL
JSON support
To return the Microsoft Advertising user ID in a JSON response with CORS support, use the format:
https://ib.adnxs.com/getuidj
You will receive a JSON-formatted response like this:
{"uid":1680598911678123849}
To return a JSONP response with CORS support:
https://ib.adnxs.com/getuidp?callback=ABC
where callback is the callback function as defined on the query string. You will receive a JSONP-formatted response like this:
ABC({"uid":1680598911678123849})
getUID example
In most cases, it will be necessary to pass the user ID into a specified parameter within the query string of the URL. To accomplish this, you may use the $UID macro:
https://ib.adnxs.com/getuid?https://ad.adserver.com/pixel?adnxs_uid=$UID&geo=35&referrer=https://www.website.com
The $UID macro will be replaced with the Microsoft Advertising user ID by the Impression Bus and the user will be directed to the following URL:
https://ad.adserver.com/pixel?adnxs_uid=19241908471992&geo=35&referrer=https://www.website.com
Use case: Piggyback on a pixel call
An easy way to create this mapping is to piggyback the getUID Service off of one of your existing pixel calls. You can adjust your pixel so that when the pixel call is made, there will be an immediate redirect to the Microsoft Advertising getUID service, which will pass back the user ID within the URL indicated by Microsoft Invest.
For example, let's assume the following pixel exists on a publisher site today:
<img src="media/pixel?id=234123" width=1 height=1/>
Instead, fire the Microsoft Advertising getUID pixel, providing the URL of the adserver.com pixel:
https://ib.adnxs.com/getuid?https://ad.adserver.com/pixel?id=234123&adnxs_uid=$UID
The getUID service redirects to the specified URL with the Microsoft Advertising user ID in place of the $UID macro:
https://ad.adserver.com/pixel?id=234123&adnxs_uid=19241908471992
When adserver.com receives this call, the Microsoft Advertising user ID can be inserted into adserver.com's server-side user data store where this mapping of user IDs can be used by future impression and pixel calls through the Microsoft Advertising Impression Bus.
mapUID service
Tip
The mapUID service has fees associated with it. If you're interested in using this option, speak with your Microsoft Advertising representative.
The mapUID Service inserts your in-house ID into the Microsoft Advertising Server Side Cookie Store.
The format for a client-side pixel that maps your ID to ours in our system is
https://ib.adnxs.com/mapuid?member=MEMBER_ID&user=USER_UD
where the member ID is the ID assigned to your company by Microsoft Advertising and the USER_ID is your company's user ID. If you don't know your member ID, you can find out by making a GET request to the Member Service.
If you have more than one user ID, you can separate them with semicolons; for example:
https://ib.adnxs.com/mapuid?member=123&user=ABC;DEF;GHI
Expiration of mappings
The average time to live (TTL) for mapUID mappings is around 2.5 weeks. Therefore, it's very important that you fire the mapUID pixel as frequently as possible and on as many pages as possible to keep your mappings live.
Piggyback a segment call off of a mapUID call
You can add user IDs to one or more segments in the Microsoft Advertising cookie store at the same time that you map their ID to ours.
Here is the syntax:
https://ib.adnxs.com/mapuid?member=[MEMBER_ID]&user=[USER_ID]&seg=[SEG_ID],[SEG_ID],[SEG_ID]
https://ib.adnxs.com/mapuid?member=123&user=12abc34565&seg=1,2,3
To pass in values for each segment use colons. This example uses segment codes instead of IDs.
https://ib.adnxs.com/mapuid?member=123&user=[USER_ID]&seg_code=[code1]:[code1value],[code2]:[code2value],[code3]:[code3value]
Send us your segment data offline
For more information about how to send us your segment data offline, see the API's Batch Segment Service.