SDK Installation
Before You Start Make Sure:
- Inventory is set up on Retailer 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 in order to declare our Maven repository:
repositories { google() jcenter() maven { url "https://maven.display.io/" } }
Add the following dependency to your app-module’s build.gradle file:
implementation ‘com.brandio.ads:sdk:4.6.6.4’
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.**
SDK Initialization
Initialize the SDK upon app start: within your app’s main activity onCreate()method call the SDK’s Controller.init(Context activity, InitProperties properties, String appId) method, after you have to call 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>); } }
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);
Ads Requesting
To request an ad you should retrieve the placement object from the Controller:
Placement placement = Controller.getInstance().getPlacement(placementId);
Then issue a new AdRequest object from the Placement object using the newAdRequest()method.
To retrieve previously issued AdRequests, you should use the getLastAdRequest() and getAdRequestById() methods.
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();
Extra Ad Request Parameters
There is an option to set up additional parameter to the Ad Request for ad campaign targeting and other needs:
// set Customer ID to Ad Request
String[] customerID= new String[]{"172Rtk999"}; adRequest.setCustomerId(customerID);
// set Page to Ad Request
String page= "Food"; adRequest.setPage(page);
// set Cat to Ad Request
String[] cat= new String[]{"Food, Asia"}; adRequest.setCat(cat);
// set User Keywords to Ad Request
String[] userKeywords= new String[]{"Meal, Asia"}; adRequest.setUserKeywords(userKeywords);
// set Content Keywords to Ad Request
String[] contentKeywords= new String[]{"Lunch, Asia"}; adRequest.setContentKeywords(contentKeywords);
// set Filters to Ad Request
String[] filters= new String[]{"Lunch, NY"}; adRequest.setContentKeywords(filters);
// set Language to Ad Request
String[] language= new String[]{"en"};
adRequest.setLanguage(language);
// set Group to Ad Request
String[] group= new String[]{"food lovers, main"}; adRequest.setGroup(group);
// set Currency to Ad Request
String[] cur= new String[]{"usd"}; adRequest.setCur(cur);
// set Label(s) to Ad Request
String[] labels = new String[]{"premium, main"}; adRequest.setLabel(labels);
// set Year of birth to Ad Request
String yob="1989"; adRequest.setYob(yob);
// set Gender to Ad Request
String gender = "male"; adRequest.setGender(gender);
// set Custom Parameters (JSON format) to Ad Request
String customParams = {"param1: 1122, param2: “abcd” "}; adRequest.setCustomParams(customParams);
Note: Ad Request data should be added prior to executing the Ad Request.
Ads Loading
On the Ad Request’s successful response the registered callback onAdReceived(AdProvider adProvider) will be called.
Load ad by calling AdProvider’s loadAd() method: as a best practice, you should apply AdLoadListener to the AdProvider, in order to listen to onLoaded and onFailedToLoad events.
adProvider.setAdLoadListener(new AdLoadListener() { @Override public void onLoaded(Ad ad) { ((Shoppable) ad).setShoppableAction(new Shoppable.ShoppableAction() { @Override public void onActionPerformed(Shoppable shoppableAd) { // handle user interaction here } }); } @Override public void onFailedToLoad(DIOError error) { // integration code } }); try { adProvider.loadAd(); } catch(DioSdkException e) { // error handling }
If the ad is successfully loaded, the onLoaded() callback will be called along with the Ad object. You can retrieve ECPM of current ad calling getEcpm() on Ad object.
Get Ad Response Params
There is a list of parameters which can be extracted from Shoppable Ad object (in case the parameters presence):
Product Code: method getProductCode()
Retailer Taxonomy: method getRetailerTaxonomy()
Global Identifier: method getGlobalIdentifier()
Product Name: method getProductName()
Product Price: method getProductPrice()
Product Brand: method getProductBrand()
Custom Parameters: method getCustomParam()
eCPM: method getEcpm()