Adform OpenRTB Bid loader

📘 Adform OpenRTB Bid Loader Integration Guide

This guide explains how to integrate and use the OpenRTBBidLoader in your Android project for loading native ads via OpenRTB protocol.

Requirements

• Android API level 21+
• HeaderBiddingSDK integrated in your project

🚀 Integration Steps

1. Add the Header Bidding SDK to Your Project

Maven/Gradle:

repositories { maven { url "https://github.com/adform/adform-android-sdk/raw/master/releases/" } }

implementation 'com.adform:adform-header-bidding-sdk:2.21.0'

2. Create an OpenRTB Request

The OpenRTBBidLoader requires an OpenRTB request object that specifies the ad request details:

// Create a native ad request  
OpenRTBRequest.Native nativeAd = new OpenRTBRequest.Native();  
OpenRTBRequest.NativeRequest nativeRequest = new OpenRTBRequest.NativeRequest();  
  
// Create assets for the native ad (e.g., main image)  
NativeRequestAsset mainImageAsset = new NativeRequestAsset();  
mainImageAsset.id = 0;  
mainImageAsset.required = 1; // 1 means required, 0 means optional  
mainImageAsset.img = new OpenRTBRequest.RequestImgAsset();  
mainImageAsset.img.hmin = 166; // Minimum height  
mainImageAsset.img.wmin = 200; // Minimum width  
mainImageAsset.img.type = 3;   // 3 means main image  
  
// Add the asset to the request  
nativeAd.request = nativeRequest;  
List<NativeRequestAsset> assets = new ArrayList<>();  
assets.add(mainImageAsset);  
nativeRequest.assets = assets;  
  
// Create an impression  
OpenRTBRequest.Imp imp = new OpenRTBRequest.Imp();  
imp.id = "1";  
imp.tagid = "1151535";  
imp.nativeAd = nativeAd;  
  
List<OpenRTBRequest.Imp> list = new ArrayList<>();  
list.add(imp);  
  
// Build the complete request  
OpenRTBRequest request = new OpenRTBRequest.Builder()  
 .setId("322a0c8ff399a7")
 .setImpression(list)
 .build(this);  

3. Create and Use the OpenRTBBidLoader

Once you have your request object, you can create an OpenRTBBidLoader and request an ad:

// Create the loader 
OpenRTBBidLoader loader = new OpenRTBBidLoader(context, request);  
  
// Set a listener to handle success and failure 
loader.setListener(new NativeAdListener() {  
	@Override  
	public void onSuccess(OpenRTBResponse openRTBResponse) {  
		// Handle the successful response   
	}  
  
	@Override  
	public void onFail(String errorMessage) {  
		 // Handle the failure   
		Log.e("OpenRTBBidLoader", "Failed to load ad: " + errorMessage);  
	}  
});  
loader.requestAd();

🔧 Advanced Usage: Customizing Asset IDs

You can customize the asset IDs in your OpenRTB request to match your specific requirements:

// Title asset  
OpenRTBRequest.NativeRequestAsset assetTitle = new OpenRTBRequest.NativeRequestAsset();  
assetTitle.id = 1; // Custom ID for title  
assetTitle.required = 1;  
assetTitle.title = new OpenRTBRequest.RequestTitleAsset();  
assetTitle.title.len = 100;  
  
// Description asset  
OpenRTBRequest.NativeRequestAsset assetDescription = new OpenRTBRequest.NativeRequestAsset();  
assetDescription.id = 2; // Custom ID for description  
assetDescription.required = 0;  
assetDescription.data = new OpenRTBRequest.RequestDataAsset();  
assetDescription.data.type = 2; // 2 means description  
  
// Add all assets to the request  
List<OpenRTBRequest.NativeRequestAsset> assets = new ArrayList<>();  
assets.add(assetTitle);  
assets.add(assetDescription);  
// Add other assets...  
nativeRequest.assets = assets;  

🧩 Advanced Usage: User Data (Segments/Taxonomies)

You can enrich a request with user data segments (IAB Audience Taxonomy or first‑party data). The SDK supports providing an array of OpenRTBRequest.User.Data objects via the builder.

Example:

// Configure user data provider with IAB segtax and segments
OpenRTBRequest.User.Data data = new OpenRTBRequest.User.Data();
data.name = "dataprovider.com"; // Optional provider name

// Optional ext fields
java.util.Map<String, Object> dataExt = new java.util.HashMap<>();
dataExt.put("segtax", 4);               // IAB Audience Taxonomy v2.0 = 4 (example)
java.util.List<String> cids = new java.util.ArrayList<>();
cids.add("iris_c73g5jq96mwso4d8");      // Example provider/customer ID
dataExt.put("cids", cids);
data.ext = dataExt;

// Provide audience segments
OpenRTBRequest.User.Segment s1 = new OpenRTBRequest.User.Segment();
s1.id = "23"; // IAB segment ID
OpenRTBRequest.User.Segment s2 = new OpenRTBRequest.User.Segment();
s2.id = "48";
data.segment = new OpenRTBRequest.User.Segment[]{ s1, s2 };

// Build the request and attach user data array
OpenRTBRequest.Imp imp = new OpenRTBRequest.Imp();
imp.id = "1";
imp.tagid = "1151535";
imp.nativeAd = nativeAd;

OpenRTBRequest request = new OpenRTBRequest.Builder()
    .setId("322a0c8ff399a7")
    .setImpression(java.util.Collections.singletonList(imp))
    .setUserData(new OpenRTBRequest.User.Data[]{ data })
    .build(context);

Limits:

• Maximum distinct taxonomies (User.Data objects) in user.data: 5. If you provide more than 5 providers/taxonomies, extras are ignored during serialization (truncated).
• Maximum segments per taxonomy: 20. If more than 20 segments are supplied in data.segment, only the first 20 are serialized, preserving order.
• Truncation is logged (warnings) by the serializer.

➕ Advanced Usage: MultiBid

MultiBid - a solution that allows to receive multiple bid responses for single bid request. When enabled, the response may contain multiple bids. By default this option is disabled.

How to enable:

OpenRTBRequest request = new OpenRTBRequest.Builder()
    .setId("322a0c8ff399a7")
    .setImpression(java.util.Collections.singletonList(imp))
    .setMultiBid(true)
    .build(context);