In our previous blog post, we discussed Amazon’s Unified Ad Marketplace, its benefits, shortcomings, differences from the Transparent Ad Marketplace, and more. The biggest advantage of UAM is the unique demand from Amazon, other benefits include the integration of top SSPs, unified payments, lightweight server to server setup, and the potential to improve your overall revenue.
So, if you’ve decided to move forward with it, then this article will help you with Prebid and UAM integration.
Table of Content:
- How to Integrate UAM with GAM?
- How Does it Work?
- How to Integrate UAM with Prebid?
- Sequential and Parallel Calls
- Ideal Setup
- Conclusion
How to Integrate UAM with GAM?
If you are integrating your site only with UAM (no other header bidder) then just go to your UAM account > Set Up DFP > Add New DFP Account and follow the steps for UAM and Ad Manager integration. Next, go to Resources > Add Javascript > ‘Integrate UAM alone’ to find the javascript that has to be copied and pasted into your site’s header.
How Does it Work?
The working procedure of the setup is fairly simple. Just as always, Prebid will send its winning bids to GAM as Price Priority line items. Similarly, UAM will send its winning bids as Price Priority line items from the server-side. Once sent, these bids then face competition from Exchange Bidding (if enabled) and Google AdX through dynamic allocation. Ultimately, the winning bid from this auction delivers the ad.
How to Integrate UAM with Prebid?
Publishers can integrate UAM with Prebid in 2 steps.
- Create a Service Account for API Access
- Website’s Integration with UAM.
Step #1: Create a Service Account for API Access
Since the Unified Ad Marketplace works on the server-side, the integration takes place with the help of API. You need to give API access to Amazon UAM, for that you need to create a service account.
- Go to the Google Cloud platform by visiting console.cloud.google.com
- In the left-hand navigation bar, hover over IAM and Admin and select Service Account
- Then click on the Create Service Account button.
- Fill in all the details, furnish, and download the created JSON file.
- Copy the email value for your service account
- Now sign in to your GAM account
- Go to Admin> Global Settings
- Check the box that says “API Access”
- Select Add A Service Account User
- Fill the details, paste the email values copied earlier in the ‘Email’ field.
- Click Save.
After enabling the API access, you can follow the steps mentioned in “How to integrate UAM with GAM? (at the start of this article)” to let Amazon generate the required line items. Wait for a few hours for the process to complete. If you face any issues related to the API setup with Google Ad Manager, you can visit https://developers.google.com/ad-manager
Step #2: Website’s Integration with UAM
Now, coming to your website’s side:
- Integrate your site with Amazon from the setup page.
- Deploy the Ads.txt file.
- Add the javascript to your site. Here are the steps to successfully add Amazon’s javascript to your site:
- Copy the APS (Amazon Publisher Services) javascript from UAM’s setup page
- Choose the integration configuration from “Integrating alongside prebid”, “Integrating alongside any other header bidders” and “Integrate UAM alone”.
- Add your Publisher ID.
- Add your “slotID’s, slotName’s, and sizes”.
- Test your integration with Amazon’s Debug Console.
- Update your Ads.txt file.
- Validate your integration.
While integrating with prebid, the calls can either be made sequentially or parallelly. Parallel integration is generally the preferred mode because parallel requests are faster than sequential ones.
Sequential and Parallel Calls
Sequential Calls
When the calls are made sequentially, you have to manage three API calls:
- The bid requests from each bidder, ie apstag.fetchBids() and pbjs.requestBids()
Please note that when the calls are being made sequentially, then you should place the above functions as together as possible so that both Prebid and UAM get an equal amount of time to complete their auctions. - Setting key-value pairs with bid information (APS: apstag.setDisplayBids(), Prebid: pbjs.setTargetingForGPTAsync()).
- GAM request: googletag.pubads().refresh()
Parallel Calls
Making parallel calls is the ideal method for integration as we mentioned above. You have to apply logic to initiate the ad request to GAM when both APS and Prebid have returned the bids or when the failsafe timeout has been reached.
Amazon has already created a request manager for easy parallel integration. The executeParallelAuctionAlongsidePrebid() function will manage the calls to Prebid, APS, and GAM.
In your prebid configuration, first you have to move your pbjs.requestBids() code block into the requestHeaderBids() function, and then remove the pbjs.sendAdserverRequest() code block. We are removing it because now this call will be made inside the executeParallelAuctionAlongsidePrebid()function. This function will include:
- Set universal timeout.
- Request config settings
- biddersBack()function: It’ll be called once when APS returns and again when Prebid returns. After the last bidder returns, the sendAdserverRequest()is called.
- sendAdserverRequest(): It’ll make a request to GAM either when both bidders have returned or when FAILSAFE_TIMEOUT has been reached.
- requestHeaderBids(): It’ll initiate the bid requests to APS and Prebid
- FAILSAFE_TIMEOUT: It’ll set the time frame for the GAM auction
Example code from Amazon
<script>
/** Executes a parallel auction with prebid **/
function executeParallelAuctionAlongsidePrebid() {
var FAILSAFE_TIMEOUT = 2000;
var requestManager = {
adserverRequestSent: false,
aps: false,
prebid: false
};
// when both APS and Prebid have returned, initiate ad request
function biddersBack() {
if (requestManager.aps && requestManager.prebid) {
sendAdserverRequest();
}
return;
}
// sends adserver request
function sendAdserverRequest() {
if (requestManager.adserverRequestSent === true) {
return;
}
requestManager.adserverRequestSent = true;
googletag.cmd.push(function() {
googletag.pubads().refresh();
});
}
// sends bid request to APS and Prebid
function requestHeaderBids() {
// APS request
apstag.fetchBids({
slots: [{
slotID: ‘your-gpt-div-id’,
slotName: ‘12345/yourAdUnit’,
sizes: [[300, 250], [300, 600]]
}]
},function(bids) {
googletag.cmd.push(function() {
apstag.setDisplayBids();
requestManager.aps = true; // signals that APS request has completed
biddersBack(); // checks whether both APS and Prebid have returned
});
}
);
// put prebid request here
pbjs.que.push(function() {
pbjs.requestBids({
bidsBackHandler: function() {
googletag.cmd.push(function() {
pbjs.setTargetingForGPTAsync();
requestManager.prebid = true; // signals that Prebid request has completed
biddersBack(); // checks whether both APS and Prebid have returned
})
}
});
});
}
// initiate bid request
requestHeaderBids();
// set failsafe timeout
window.setTimeout(function() {
sendAdserverRequest();
}, FAILSAFE_TIMEOUT);
};
</script>
What’s the Ideal UAM Setup with Header Bidding?
The ideal setup would be to make Amazon UAM compete with Prebid as well as EBDA on your site. All three sources will send their winning bids to the Ad Manager and you’ll get the highest rates. Such a setup generally yields the best results for most publishers.
It’ll be possible when both Prebid and UAM will be set to send their winning bids simultaneously as Price Priority Line Items. The bids will then compete with the bids sent by AdX via Dynamic Allocation.
Conclusion
The setup can be complicated for a few publishers as it requires a certain level of technical expertise as well as coding skills. The best course of action is to work with a wrapper technology provider / managed service provider for the setup. Such service providers will already have all the requirements fulfilled for you. For instance, once your site is whitelisted and Adx.txt is verified by Amazon, then Automatad can do all the integration work within a day.
So you can contact us for the UAM integration without any worries.
At Automatad, we help publishers to monetize better without hampering the user experience. Our products are live across hundreds of publishers, earning them incremental ad revenue with every passing second. You can request a free audit to get an estimated revenue uplift today.
