To get started you need to set up your Application and Placements on display.io Platform:
1. Log in to your account.
2. Go to the Inventory section:
3. Create new inventory by selecting OS and SDK integration:
4. Add a new Placement
Important:
Create a separate ad unit placement for each actual placement in your app or site.
Ensure each ad unit placement has a name that corresponds with its actual place in your app or site.
For example: Homepage – Gallery 1, Homepage – Gallery 2
Placements allow you to set ads in different locations of your app. For example, you could add one placement upon app launch and another placement in a page that gets alot of traffic.
Placements are bound to a specific Ad Unit type.
See below for a list of our currently supported Ad Units/Ad Formats/Ad Sizes:
Interscroller (in-feed, 320×480) – Video and Display ad formats
Headline (in-feed, 320×250) – Video and Display ad formats
Interstitial (320×480 / 480×320) – Video and Display ad formats
Infeed (in-feed, 300×250 / 320×250) – Video and Display ad formats
Medium Rectangle (300×250) – Display ad format
Banner (320×50) – Display ad format
When testing an integration set status to “Testing” on your new placement to get a test ad response for each ad request sent.
Interscroller placement setup
Installing the SDK
Before You Start Make Sure:
- App and Placement are added on Publisher Portal
- Android Studio 3.2 or later
- minSdkVersion 14 or later
- compileSdkVersion 28 or later
1. Import SDK to your Project
Edit your project’s build.gradle file (allprojects section) in order to declare our Maven repository:
repositories {
google()
mavenCentral()
maven { url "https://maven.display.io/" }
}
Add the following dependency to your app-module’s build.gradle file:
implementation ‘com.brandio.ads:sdk:4.7.8’
2. Update your AndroidManifest.xml
Recommended permissions (adds value to your impressions and in turn advertisers pay more for your traffic):
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
3. Proguard
If you are using proguard to obfuscate your code – add the following lines to your proguard-rules.pro file:
-keep class com.brandio.ads.Controller.** { *;}
-dontwarn com.brandio.ads.Controller.**
Initializing the SDK
Before You Start Make Sure:
- At least one App and Placement are added on Developer Portal
- SDK is installed
Initialise the SDK upon app start. In order to do so – within your app’s main activity onCreate()method call the SDK’s Controller.init(Context activity, InitProperties properties, String appId) method, after you have called setContentView().
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Controller ctrl = Controller.getInstance();
if (!ctrl.isInitialized()) {
ctrl.setSdkInitListener(new SdkInitListener() {
@Override
public void onInit() {
// integration code
}
@Override
public void onInitError(DIOError error) {
// integration code
}
});
ctrl.init(MainActivity.this, initProperties, <Your App Id>);
}
}
Note:
You can find your App ID in your Account on the Developer Portal (Applications tab).
Important:
Do not try to initialise Controller more than once. Always validate if (!ctrl.isInitialized()) {….}before calling init().
We highly recommend to set InitProperties object in order to provide more info for better ad targeting:
InitProperties initProperties = new InitProperties();
// set user gender
initProperties.setGender(InitProperties.MALE);
// set user year of birth
initProperties.setYearOfBirth(1983);
// set user keywords
List<String> keywords = new ArrayList<>();
keywords.add("house of cards");
keywords.add("ronaldo");
initProperties.setKeywords(keywords);
// set if the user is a child, according to the local law
// (UNKNOWN (default), YES, NO)
initProperties.setChildCompliant(CompliantState.NO);
// set US Privacy String in case user from USA
initProperties.setUSPrivacyString("YOUR_STRING");
As a best practice, we advise our publishers to add as much user data to their ad requests as possible. The reason for that is that it gives advertisers visibility into the parameters of each user within your app and allows advertisers to bid more intelligently, meaning a higher CPM payout for developer.
Additional: Starting Android Pie (API 28), Google isn’t allowing using a single WebView instance in 2 different processes, so in case you are using multiple processes in your application, you have to call WebView.setDataDirectorySuffix(“dir_name_no_separator”), according to documentation. We also provide opportunity to handle this inside SDK, what you need is to notify Controller object about it before call init:
ctrl.setMultipleProcessApp(true);
Requesting & Loading Ads
Before You Start Make Sure:
- At least one App and Placement set up on Publisher Portal
- SDK is installed
- SDK is initialized
- Each Ad request has “Testing” status which enables it to test integrations.
1. Requesting Ads
To request an ad you should retrieve the placement object from the Controller.
Placement placement =
Controller.getInstance().getPlacement(placementId);
Note: You can find the Placement ID in your account on Developer Portal in the Application tab.
Then issue a new AdRequest object from the Placement object using the newAdRequest()method. To retrieve previously issued AdRequests, you may use the getLastAdRequest() and getAdRequestById() methods.
By default video ads are muted. This setting can be changed on placement level using setDefaultMute(false) method on placement object.
You an also use your custom mute/unmute button, to disable built-in sound control use setShowSoundControl(false) method on placement object.
Note: setDefaultMute(false) will not make effect for already loaded Ad, so the best way is to call the method before request.
To execute an Ad Request call the AdRequest object’s requestAd() method.
Apply AdRequestListener to your AdRequest object to get callback with AdProvider object that enables access to the retrieved ad.
adRequest.setAdRequestListener(new AdRequestListener() {
@Override
public void onAdReceived(AdProvider adProvider) {
// integration code
}
@Override
public void onNoAds(DIOError error) {
// integration code
}
});
adRequest.requestAd();
You may add the context keywords of the application to the Ad Request.
// set content keywords
List<String> contentKeywords = new ArrayList<>();
contentKeywords.add("searching");
contentKeywords.add("computing");
adRequest.setContentKeywords(contentKeywords);
You can also set up labels for Ad Request in order to run A/B testing:
// set label(s) to ad request
String[] labels = new String[]{"blue, red"};
adRequest.setLabel(labels);
You can also provide additional data to increase you’re fill rate:
// set user ID
adRequest.setUserId("USER_ID");
// set buyer ID
adRequest.setBuyerId("BUYER_ID");
// set IAB section and/or page categories
adRequest.setIABSectionCats( new String[] {"IAB1-2", "IAB12", "IAB3-1"});
adRequest.setIABPageCats( new String[] {"IAB2-1", "IAB4", "IAB3-1"});
In case you are requesting Banner or Medium Rectangle ads – define the expected position of the ad on the screen as follows:
// set ad position // 'ABOVE_THE_FOLD','BELOW_THE_FOLD' adRequest.setPosition(Banner.Position.ABOVE_THE_FOLD);
Note: Ad Request data should be added prior to executing the Ad Request.
2. Loading Ads
On the AdRequest’s successful response the registered callback onAdReceived(AdProvider adProvider) will be called.
Load the ad by calling the AdProvider’s loadAd() method: As a best practice, you should apply an AdLoadListener to the AdProvider, in order to listen to the onLoaded and onFailedToLoad events.
adProvider.setAdLoadListener(new AdLoadListener() {
@Override
public void onLoaded(Ad ad) {
// integration code
}
@Override
public void onFailedToLoad(DIOError error) {
// integration code
}
});
try {
adProvider.loadAd();
} catch(DioSdkException e) {
// error handling
}
If the ad successfully loaded, the onLoaded() callback will be called along with the Ad object. Use reference to Ad for showing current ad to user.
You can retrieve the available add data with the methods:
Log.d(TAG, "Ad advertiserName: " + ad.getAdvertiserName()); Log.d(TAG, "Ad advertiserClickUrl: " + ad.getAdvertiserClickUrl()); Log.d(TAG, "Ad crid: " + ad.getCreativeId()); Log.d(TAG, "Ad cid: " + ad.getCampaignId()); Log.d(TAG, "Ad adomain: " + ad.getAdvertiserDomain()); // ArrayList<String> Log.d(TAG, "Ad auctionId: " + ad.getAuctionId()); Log.d(TAG, "Ad msessId: " + ad.getUserSessionId()); Log.d(TAG, "Ad ecpm: " + ad.getEcpm());
Note:
We provide GDPR compliance through the IAB’s GDPR Transparency and Consent framework. If you use a CMP that implements this IAB standard, we will be able to pick the consent state from your integrated CMP and apply it in our ad serving.
Rendering Ads from oRTB Response
Starting from version 4.7.0 display.io SDK supports rendering and showing ads from oRTB response. SDK supports both formats display and video. You can request ads from display.io server or any other 3rd party server and use display.io SDK to show the ads.
Before start make sure you initialised SDK and have active placements within your inventory on display.io Platform.
Once you got an oRTB response string you can load the ad for one of your placement. You can create any Ad Unit you want, supported Ad Unit list you can find at Ad Units Integration section.
Note: you are responsible for creating Ad Unit that match retrieved ad size. E.g. if you got oRTB response with ad size 300×250 you should not create Interstitial or Interscroller ad from that markup.
To create the Ad from oRTB response follow the next sample:
Placement placement = Controller.getInstance().getPlacement(YOUR_PLACEMENT_ID);
if (placement == null) return;
switch (plcType) {
case BANNER: {
BannerPlacement bannerPlacement = (BannerPlacement) placement;
bannerPlacement.loadBannerFromORTB(ortbResp, new Placement.OnORTBLoadListener() {
@Override
public void onLoaded(Ad ad) {
View adView = bannerPlacement.getBanner(ORTBActivity.this, ad.getRequestId());
insertAdView(adView);
}
@Override
public void onFailToLoad(DIOError e) {
// handle FAILED_TO_LOAD_ORTB_AD event
}
});
break;
}
case MEDIUMRECTANGLE: {
MediumRectanglePlacement mediumRectanglePlacement = (MediumRectanglePlacement) placement;
mediumRectanglePlacement.loadMRECTFromORTB(ortbResp, new Placement.OnORTBLoadListener() {
@Override
public void onLoaded(Ad ad) {
View adView = mediumRectanglePlacement.getMediumRectangle(ORTBActivity.this, ad.getRequestId());
insertAdView(adView);
}
@Override
public void onFailToLoad(DIOError e) {
// handle FAILED_TO_LOAD_ORTB_AD event
}
});
break;
}
case INFEED: {
InfeedPlacement infeedPlacement = (InfeedPlacement) placement;
infeedPlacement.loadInfeedFromORTB(ortbResp, new Placement.OnORTBLoadListener() {
@Override
public void onLoaded(Ad ad) {
// the ad is ready to be rendered
}
@Override
public void onFailToLoad(DIOError e) {
// handle FAILED_TO_LOAD_ORTB_AD event
}
});
break;
}
case INTERSCROLLER: {
InterscrollerPlacement interscrollerPlacement = (InterscrollerPlacement) placement;
interscrollerPlacement.loadInterscrollerFromORTB(ortbResp, new Placement.OnORTBLoadListener() {
@Override
public void onLoaded(Ad ad) {
// the ad is ready to be rendered
}
@Override
public void onFailToLoad(DIOError e) {
// handle FAILED_TO_LOAD_ORTB_AD event
}
});
break;
}
case HEADLINE: {
HeadlinePlacement headlinePlacement = (HeadlinePlacement) placement;
headlinePlacement.loadHeadlineFromORTB(ortbResp, new Placement.OnORTBLoadListener() {
@Override
public void onLoaded(Ad ad) {
// the ad is ready to be rendered
}
@Override
public void onFailToLoad(DIOError e) {
// handle FAILED_TO_LOAD_ORTB_AD event
}
});
break;
}
case INTERSTITIAL: {
InterstitialPlacement interstitialPlacement = (InterstitialPlacement) placement;
interstitialPlacement.loadInterstitialFromORTB(ortbResp, new Placement.OnORTBLoadListener() {
@Override
public void onLoaded(Ad ad) {
ad.showAd(ORTBActivity.this);
}
@Override
public void onFailToLoad(DIOError e) {
// handle FAILED_TO_LOAD_ORTB_AD event
}
});
break;
}
}
Once the ad was loaded you can show it. Refer to Ad Units Integration section for displaying specific ad unit manual.
