Auctions¶
Usage¶
The Auction API runs an auction on a SmartLink and returns an updated destination URL for the link. You can use this API to write your own custom publisher Javascript tags. Be sure to read through the tutorial before proceeding.
Note
The Auction API does not require client authentication, but may be subject to rate-limiting if called an extreme number of times from the same origin.
Run Auction¶
Request¶
GET /api/v1/auction/
Query Param |
Type |
Description |
---|---|---|
a |
string |
Auction ID. This is the number at the end of your SmartLink.
For example, the SmartLink |
t |
integer |
Cache-busting parameter. Set this to a randomly-generated number to prevent HTTP caching of the auction request and response. |
uuid |
string |
Page Session UUID. The UUID v4 value that your client has generated for the current page session. |
Response¶
Auction result data¶
Field Name |
Type |
Description |
---|---|---|
auction_result . id |
string |
A unique identifier for the result of the auction. |
auction_result . product |
object |
Product information for the advertiser that won the auction. |
auction_result . redirect_url |
string |
The new destination URL for the SmartLink. |
auction_result . tracker_urls |
object |
Third-party event tracker URLs for this SmartLink placement. Your client is responsible for firing all trackers listed here when the applicable event(s) occur. |
impression_pixel_url |
string |
The primary impression event tracker URL for this SmartLink placement. Your client is responsible for firing this tracker after receiving the auction response. |
Product information (auction_result.product)¶
Auction API responses may provide the following information about the advertiser (retailer/merchant) and the product page that will be receiving the click on the rewritten SmartLink:
Field Name |
Type |
Description |
---|---|---|
id |
integer |
A unique identifier for the product that the destination URL refers to. |
name |
string |
The name of the product being sold. |
price |
string |
The price of the product being sold, in USD. |
url |
string |
The raw URL of the product page, for display purposes. (Do not rewrite the SmartLink with this URL.) |
image_url |
string |
The image URL of the product being sold, for display purposes. |
is_in_stock |
boolean |
The stock status of the product being sold. |
merchant . id |
integer |
A unique identifier for the advertiser. |
merchant . canonical_host |
string |
The host part of the advertiser’s website URL, for display purposes. |
merchant . name |
string |
The name of the advertiser. |
merchant . url |
string |
The full URL for the advertiser’s home page. |
Third-party event trackers (auction_result.tracker_urls)¶
Auction API responses may include the following set of third-party event trackers that apply to your SmartLink placement:
Event Tracker Type |
Event Description |
---|---|
impression |
Signals that at least one occurrence of this SmartLink has been loaded on the page. You may fire this event tracker immediately after receiving the auction response. |
viewable_impression |
Fire this event tracker once any occurrence of this SmartLink is scrolled into view on the page. |
Tracker URLs may include the template parameter {RAND}
, which must be
replaced with a randomly-generated number for cache-busting prior to firing
the tracker.
Do NOT fire a third-party event tracker more than once per page for the same event, even if the same SmartLink appears multiple times on that page.
Example¶
GET https://api.bam-x.com/api/v1/auction/
?a=1629223267830557131
&t=1517261651
&uuid=8132ac19-109a-466e-8037-540a9bd12798
HTTP/1.1 200 OK
Content-Type: application/json
{
"info": {
"error": false,
"status": 200
},
"data": [
{
"auction_result": {
"id": "1629224701990881693",
"auction_id": "1629223267830557131",
"redirect_url": "https://api.bam-x.com/api/v1/redirect/?a=1629223267830557131&uid_bam=1629224701957143181&ar=1629224701990881693&url=https%3A%2F%2Fwww.amazon.com.example%2F&uuid=8132ac19-109a-466e-8037-540a9bd12798",
"product": {
"merchant": {
"url": "https://www.amazon.com/",
"canonical_host": "amazon.com",
"id": 2186,
"name": "Amazon"
},
"bamx_product_category_id": 3,
"name": "Designer Handbag",
"url": "https://www.amazon.com.example/product/1234",
"image_url": "https://www.static.amazon.example/image/path/1234",
"is_in_stock": true,
"price": "299.99",
"id": 8030310
},
"tracker_urls": {
"viewable_impression": [
"https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=lv;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
"https://ad.atdmt.com.example/1111?r={RAND}"
],
"impression": [
"https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;kw=li;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?",
"https://ad.atdmt.com.example/2222?r={RAND}"
]
}
},
"impression_pixel_url": "https://ad.doubleclick.net.example/ddm/trackimp/N1234.1234567NARRATIV/B12345678.123456789;dc_trk_aid=123456789;dc_trk_cid=12345678;ord=1629147433127336253;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=?"
}
]
}