Documentation

1.Getting Started #

Version 1.0

The following document provides detailed instructions on how to integrate the AdsUnlocksdk 1.0 into your Android Projects based on a simple Demo app. The AdsUnlock SDK is capable of displaying both traditional Banner Ads, Interstitials, Video Ads and also incorporates AdsUnlock’s proprietary Products like Caller ID©, Post Call and Unlock Action©

Supports Android OS 4.1.x (Jelly Bean) and up.

2.Content #

  • Prerequisites
  • Installation
    1. Jar Installation
  • Usage
    1. Banner Ad
    2. Interstitial Ad

2.1.Prerequisites #

You will need an AdsUnlock Publisher Account

Step 1: Set Up your Application in your AdsUnlock Control Panel

  • Log into your AdsUnlock Administration Control Panel
  • Click on Apps> Add App if you‘d like to create a new App.
  • Once done you will be provided with a unique Placement ID (Publisher ID in code) and a Request URL (Only when a new app with placement is created)
  • If you want to integrate into an existing App, navigate to Apps> View Apps> Edit Apps
  • If you want to Add a new placement for Existing App, Navigate to Add Placement> Select the respective app from the dropdown> Add the new placement details and Create Placement

Step 2: Download

The downloaded ZIP contains the following files:

  • PDF Documentation “AdsUnlocksdk_Integration_Guide.pdf” (this document)
  • The SDK Framework itself: AdsUnlockAdSdk.aar
  • Demo Application “SampleDemoApp” folder showcasing:
    • Request of Banner Ads, Interstitial Ads, Rewarded video
    • Some Coding and Customization options

Step 3: Create and define a new Android Project

Download and open the latest version of Android Studio. Update the Android Studio Tools and Revisions listed at the Android Studio. Import Sample project in your Android Studio.

2.2.Installation #

In your existing project in Android Studio, import the AdsUnlockSdk.aar file as a New Module :

File-> New->New Module->Import .aar/.jar file .   

Browse the AdsUnlockSdk.aar file path and click Finish.

This will add the sdk to your project.

Step 4: Initialize the SDK

Before loading ads, have your app initialize the Mobile Ads SDK by calling AdsUnlockAdSdk.initialize() with your AdsUnlock App and Placement ID. This only needs to be done once, ideally at app launch. You can find your app’s App ID in the AdsUnlock User Interface.

AdsUnlockAdSdk.initialise(activity, context, publisherId, stringTypes);

new Location(this).initLocation();
This method is called to initialize the process for getting the user location in the background while the impressions are served.
Note : GPS should be turned on to get the precise location of the user, also the dangerous permission to retrieve the location are:

<uses-permission android:name=”android.permission.ACCESS_COARSE_LOCATION” />

<uses-permission android:name=”android.permission.ACCESS_FINE_LOCATION” />

 

These run time permissions need to be asked before initializing the SDK

2.3.Usage #

Ad Types: “BANNER: INTERSTITIAL: REWARDED VIDEO” is a string that contains all the features required by the publisher separated by colon and respective feature is called upon as per the publishers needs or requirement based on usage.

In your project’s AndroidManifest.xml under the manifest tag, add the following permissions:

<uses-permission android:name=”android.permission.ACCESS_WIFI_STATE” />

<uses-permission android:name=”android.permission.INTERNET” />

<uses-permission android:name=”android.permission.READ_PHONE_STATE” />

<uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE” />

<uses-permission android:name=”android.permission.ACCESS_FINE_LOCATION” />

<uses-permission android:name=”android.permission.CALL_PHONE” />

<uses-permission android:name=”android.permission.ACCESS_COARSE_LOCATION” />

<uses-permission android:name=”android.permission.READ_CONTACTS” />

<uses-permission android:name=”android.permission.PROCESS_OUTGOING_CALLS” />

<uses-permission android:name=”android.permission.GET_ACCOUNTS” />

 

Note :
For Android version 6.0 (marshmallow) and above make sure dangerous permissions are handled at run time

Add dependencies to gradle :
compile ‘com.google.android.gms:play-services:7.5.0’
compile ‘com.jakewharton.timber:timber:4.5.1’
compile ‘com.jakewharton:butterknife:8.4.0’

2.3.1.Show Banner Ads #

Step 5: Show Banner Ads

Open activity_main.xml and add the Banner without adding additional code as shown in SampleDemoApp.
Alternatively create a button to call “onClickShowBanner” (copy/paste activity_main.xml in SampleDemoApp)
Instead of using a button display a Banner directly in MainActivity.java :

if (mAdView == null) { mAdView = new BannerView(this,
“ENTER_REQUEST_URL_HERE”,
“ENTER_PUBLISHER_ID_HERE”,
true, true);
mAdView.setAdListener(this);
layout.addView(mAdView); }

 

Add some code now to your Activity (copy/paste from MainActivity.java provided in the SampleDemoApp). This will initialize an instance of the Ad view with your Placement ID (called Publisher ID in code) and Request URL, initialize the button and set a listener on it to request an Ad. Listeners for the Ad view will handle events e.g. adLoadSucceeded

Please note to edit both placeholders “ENTER_REQUEST_URL_HERE” and “ENTER_APP_ID and PLACEMENT _ID_HERE” with provided strings from your AdsUnlock control panel.
Add these Banner Ad specific lines to the Manifest (copy/paste from AndroidManifest.xml):
(READ_PHONE_STATE and ACCESS_FINE_LOCATION are optional, but recommended)

<activity

android:name=”com.adsdk.sdk.banner.InAppWebView”

android:configChanges=”keyboard|keyboardHidden|orientation|screenLayout|

uiMode|screenSize|smallestScreenSize” />

2.3.2.Show Interstitial Ads #

Step 6: Show Interstitial Ads

In your activity set up the interstitial Ad interstitial :
Open activity_main.xml and create a button which calls when pressed the method “onClickShowVideoInterstitial” (copy/paste from activity_main.xml)
Instead of using a button display an ad directly in MainActivity.java :

mManager = new InterstitialManager(this,

“ENTER_REQUEST_URL_HERE”,

“ENTER_APP_ID_AND _PUBLISHER_ID_HERE”,

true);

 

Add some code now to your Activity (copy/paste from MainActivity.java provided in the AdsUnlockSdk_Demo ZIP).

The IntersitialManager initialized with your Placement ID (Publisher ID in code) and Request URL and a listener will request an Ad. Listeners for the Ad view will handle events e.g. adLoadSucceeded

Make sure to edit both placeholders “ENTER_REQUEST_URL_HERE” and “ENTER_APP_ID AND PLACEMENT_ID_HERE” with provided strings from your AdsUnlock control panel.

Add these Interstitial Ad specific lines to the Manifest (copy/paste from AndroidManifest.xml):

<activity android:name=”com.adsunlockadsdk.sdk.InterstitialActivity” />

 

Step 7: Show Rewarded Video Ads

In your activity set up the Rewarded Video  Ad:
Open activity_main.xml and create a button which calls when pressed the method “onClickShowRewadedVideoInterstitial”(copy/paste from activity_main.xml)
Instead of using a button display an ad directly in MainActivity.java :

RewardedVideoManager lRewardedVideoManager = new RewardedVideoManager(this, “rewardeduserid”,“ENTER_REQUEST_URL_HERE”,
“ENTER_APP_ID_AND _PUBLISHER_ID_HERE”, true);

lRewardedVideoManager.callNetwork();

 

Make sure to edit both placeholders “ENTER_REQUEST_URL_HERE” and “ENTER_APP_ID AND PLACEMENT_ID_HERE” with provided strings from your AdsUnlock control panel.

Add these Interstitial Ad specific lines to the Manifest (copy/paste from AndroidManifest.xml):

<activity android:name=”com.adsunlockadsdk.sdk. RewardedVideoActivity” />

 

Step 8: You’re done!
If you already created a campaign in your AdsUnlock Campaigns, you should now see the AD.
Note : Please always clear the heap before showing Ads and restore your apps orientation after an Ad is shown.

2.3.3.Feature list #

Invoking the Feature list for End Users

Now that you have completed setting up the SDK within your project you should be able to invoke AdsUnlock custom made features in the SDK.

  • Caller ID Feature©
  • Post Call Feature
  • Unlock Feature©
  • Lock Screen Widget

You would have to setup an UI for the end user to enable and disable the mentioned AdsUnlock features as per user’s wish.(Settings Page)

SETTINGS PAGE – To allow end user (app user) to turn any of the features (Caller ID©, Post Call, Unlock©, LockScreen) ON/OFF

AdsUnlockAdSdk.enableCallerIdFeature(context);
AdsUnlockAdSdk.disableCallerIdFeature(context);
AdsUnlockAdSdk.enablePostCallFeature(context);
AdsUnlockAdSdk.disablePostCallFeature(context);
AdsUnlockAdSdk.enableUnlockFeature(context);
AdsUnlockAdSdk.disableUnlockFeature(context);
AdsUnlockAdSdk.enableLockScreenFeature(context);
AdsUnlockAdSdk.disableLockScreenFeature(context);

3.Explanation of Methods #

Caller ID : AdsUnlock Customized Caller ID© is proprietary Product of AdsUnlock where the user gets Video Ads every time the user gets an incoming call. The user has the option to enable and disable this feature if he chooses to do so. The Publisher needs to provide an UI for the same in the app settings for the user to perform those actions. The Video Ads can be skipped or Closed at any point by the user if he wishes to do so.

Post Call : AdsUnlock Customized Post Call is another proprietary Product of AdsUnlock where the user gets a Video Ad every time an outgoing Call is ended. The user has the option to enable and disable this feature if he chooses to do so. The Publisher needs to provide an UI for the same in the app settings for the user to perform those actions. Just like Caller ID©, the Video Ads can be skipped or closed anytime during playback if the user wishes to do so.

Unlock : AdsUnlock Customized Unlock Action© is another proprietary Product of AdsUnlock where the user gets a Video Ad every time the phone is unlocked. The user has the option to enable and disable this feature if he chooses to do so. The Publisher needs to provide an UI for the same in the app settings for the user to perform those actions. Just like the Post Call and Caller ID© the Video Ads can be skipped or closed anytime during playback if the user wishes to do so.

LockScreen : AdsUnlock Customized LockScreen is another proprietary Product of AdsUnlock where the user gets an Ad every time the phone screen is switched on. The user has the option to enable and disable this feature if he chooses to do so. The Publisher needs to provide an UI for the same in the app settings for the user to perform those actions. There are two customizations to the LockScreen. In the ‘AdsUnlockAdSdk.setLockscreenLayout()’ function, if you pass 1 as the layoutId, then the LockScreen shows the user basic information and also a still ad. If 2 is passed, then it’s just a full screen ad. By default, the value is 1.

Note : Also add this code in the AndroidManifest for the LockScreen to work :

<service
android:name=”com.adsunlockadsdk.lockscreenwidget.LockScreenDetectionService”
android:enabled=”true”
android:exported=”false”>

<receiver
android:name=”com.adsunlockadsdk.lockscreenwidget.ServiceStoppedReceiver”
android:enabled=”true”
android:exported=”false”>
<intent-filter>
<action android:name=”com.android.ServiceStopped” />
</intent-filter>
</receiver>

<receiver
android:name=”com.adsunlockadsdk.lockscreenwidget.ScreenOnReceiver” android:enabled=”true”
android:exported=”false”>
<intent-filter>
<action android:name=”android.intent.action.SCREEN_ON” />
</intent-filter>
</receiver>

<activity
android:name=”com.adsunlockadsdk.lockscreenwidget.LockScreenActivity”
android:screenOrientation=”sensorPortrait”
android:showOnLockScreen=”true”
android:excludeFromRecents=”true”
android:launchMode=”singleInstance”
android:theme=”@style/Theme.AppCompat.NoActionBar” />

 

4.Explanation of Manifest #

Internet Access Permission (mandatory and needed for the SDK to work)

<uses-permission android:name=”android.permission.INTERNET” />

Read Phone State Permission (optional but highly recommended)

<uses-permission android:name=”android.permission.READ_PHONE_STATE” />

Network State Permission (to identify the connection type and improve your app’s user experience)

<uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE” />

Access Fine Location (Allows an app to access precise location)

<uses-permission android:name=”android.permission.ACCESS_FINE_LOCATION” />

Call Phone Allows an application to initiate a phone call without going through the Dialer user interface for the user to confirm the call.

<uses-permission android:name=”android.permission.CALL_PHONE” />

Access Coarse Location Allows an app to access approximate location.

<uses-permission android:name=”android.permission.ACCESS_COARSE_LOCATION” />

Read Contacts Allows an application to read the user’s contacts data.

<uses-permission android:name=”android.permission.READ_CONTACTS” />

Process outgoing Calls Allows an application to see the number being dialed during an outgoing call with the option to redirect the call to a different number or abort the call altogether.

<uses-permission android:name=”android.permission.PROCESS_OUTGOING_CALLS” />

Access Wifi State Allows applications to access information about Wi-Fi networks.

<uses-permission android:name=”android.permission.ACCESS_WIFI_STATE” />