Android SDK Integration Guide
This repository describes the LiftoffAds Android SDK technical integration. For help configuring and testing ad units or setting up reporting, please contact your Liftoff POC.
For any other questions, please email sdk@liftoff.io.
Overviewβ
Latest Releasesβ
- LiftoffAds SDK
- Mediation Adapter SDKs
Supported Devicesβ
- Phone
- Tablet
Supported Ad Sizesβ
- 320x480 (phone portrait interstitial)
- 480x320 (phone landscape interstitial)
- 768x1024 (tablet portrait interstitial)
- 1024x768 (tablet landscape interstitial)
- 320x50 (phone banner)
- 728x90 (tablet banner)
- 300x250 (medium rectangle)
- 0x0 (native)
Supported Ad Typesβ
- HTML and HTML video
- VAST video
- Rewarded
- Native
Development Requirementsβ
To integrate the latest version of the LiftoffAds display SDK, you will need at minimum:
- Android API >= 19
Integrating the SDKβ
If you use ironSource mediation, skip this section and follow ironSource's Liftoff Integration Guide.
Downloading the SDKβ
You can download the SDK through Maven Central or directly.
Maven Centralβ
The easiest way to add the LiftoffAds SDK to your project is via Maven Central.
Add Maven Central to the repositories
block of your project's build.gradle
:
repositories {
// ...
mavenCentral()
}
Add the LiftoffAds
SDK as a dependency to your app module's build.gradle
:
dependencies {
// Only if using custom mediation
implementation "io.liftoff:liftoffads:1.4.3"
}
Direct Downloadβ
If you aren't using Maven Central as described above, you can download the SDK and manually add it to your project:
- Download and unzip the LiftoffAds SDK.
- Move the extracted
liftoffads.aar
to your local repository.
repositories {
// ...
flatDir {
dirs "libs"
}
}
dependencies {
implementation(name:"liftoffads", ext:"aar")
}
Include Google Play Servicesβ
Including Google Play Services with your project is optional, but recommended. It enables Liftoff to provide a more customized ad experience to your end user. We recommend that you include basement and ads-identifier APIs, and that you use version Google Play Services v11.0.1 or higher.
To include Google Play Services, refer to Google's setup guide. In your app, ensure that the device has a sufficiently updated version of Google Play Services. The Liftoff SDK optionally uses the ads API from Google Play Services.
google.android.gms:play-services-basement:18.0.1
(Recommended)
google.android.gms:play-services-ads-identifier:18.0.1
(Required for AAID)
Code Changesβ
The following code samples may be used as reference for requesting and displaying ads. Adjust the logic as necessary to meet the requirements of your app.
import io.liftoff.liftoffads.Liftoff
import io.liftoff.liftoffads.banners.LOBanner
import io.liftoff.liftoffads.common.AdSize
import io.liftoff.liftoffads.interstitials.LOInterstitial
class MainActivity :
AppCompactActivity(),
LOInterstitial.LOInterstitialListener,
LOBanner.LOBannerListener {
lateinit var loInterstitial: LOInterstitial
lateinit var loBanner: LOBanner
lateinit var loNative: LONative
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Supported log levels: NONE, ERROR, INFO, DEBUG.
Liftoff.logLevel = Liftoff.LogLevel.DEBUG
// Contact your Liftoff POC to retrieve your API key. Define this constant
// elsewhere or replace with a hardcoded string.
Liftoff.initializeSDK(this, LIFTOFF_API_KEY)
Log.d("TAG", "Initialized LiftoffAds SDK ${Liftoff.SDK_VERSION}")
// Contact your Liftoff POC to retrieve your ad unit IDs.
// NOTE: Liftoff interstitial, banner, and native objects cannot be reused
// to request multiple ads. You must initialize a new object for each ad
// request.
this.loInterstitial = Liftoff.newInterstitial(this, LIFTOFF_INTERSTITIAL_AD_UNIT, this)
this.loInterstitial.load()
// The size argument may be one of the following (a 0 indicates a flexible
// dimension):
// AdSize.PHONE_BANNER // width: 320, height: 50
// AdSize.PHONE_BANNER_FLEX_WIDTH // width: 0, height: 50
// AdSize.TABLET_BANNER // width: 728, height: 90
// AdSize.TABLET_BANNER_FLEX_WIDTH // width: 0, height: 90
// AdSize.MRECT // width: 300, height: 250
// AdSize.MRECT_FLEX_WIDTH // width: 0, height: 250
// AdSize.FLEX_ALL // width: 0, height: 0
this.loBanner = Liftoff.newBanner(
this,
LIFTOFF_BANNER_AD_UNIT,
AdSize.PHONE_BANNER_FLEX_WIDTH,
this
)
this.loBanner.load()
this.loNative = Liftoff.newNative(
activity = this,
LIFTOFF_NATIVE_AD_UNIT,
LONative.ViewBinder(
layout = R.layout.native_ad,
parent = nativePlaceholderView,
title = R.id.nativeAdTitle,
desc = R.id.nativeAdDescription,
callToAction = R.id.nativeAdCTA,
icon = R.id.nativeAdIcon,
mainImage = R.id.nativeAdMainImage
),
listener = this
)
this.loNative.load()
}
// LOInterstitial.LOInterstitialListener implementation
// Called when the interstitial ad request is successfully filled.
override fun onInterstitialLoaded(interstitial: LOInterstitial) {
// This will display the interstitial immediately after the ad request is
// filled.
interstitial.showAd()
// To instead display the interstitial at an appropriate time as determined
// by your app UX:
// if (this.loInterstitial.ready) {
// this.loInterstitial.showAd()
// }
}
// Called when the interstitial ad request cannot be filled.
override fun onInterstitialFailed(interstitial: LOInterstitial, error: String?) {}
// Called when the interstitial ad fails during display.
override fun onInterstitialDisplayFailed(interstitial: LOInterstitial, error: String?) {}
// Called after the interstitial activity is shown.
override fun onInterstitialShown(interstitial: LOInterstitial) {}
// Called after the interstitial activity is dismissed.
override fun onInterstitialDismissed(interstitial: LOInterstitial) {}
// Called when the interstitial becomes visible to the user.
override fun onInterstitialImpression(interstitial: LOInterstitial) {}
// Called when the user will be directed to an external destination.
override fun onInterstitialClicked(interstitial: LOInterstitial) {}
// Called when the user has earned a reward by watching a rewarded ad.
override fun onRewardEarned(interstitial: LOInterstitial) {}
// LOBanner.LOBannerListener implementation
// Called when the banner ad request is successfully filled. The banner
// argument is a View.
override fun onBannerLoaded(banner: LOBanner) {
this.someView.addView(banner)
}
// Called when the banner ad request cannot be filled.
override fun onBannerFailed(banner: LOBanner, error: String?) {}
// Called when the banner ad fails during display.
override fun onBannerDisplayFailed(banner: LOBanner, error: String?) {}
// Called when the banner becomes visible to the user.
override fun onBannerImpression(banner: LOBanner) {}
// Called when the user will be directed to an external destination.
override fun onBannerClicked(banner: LOBanner) {}
// LONative.LONativeListener implementation
// Called when the ad has been loaded successfully.
override fun onNativeLoaded(native: LONative) {}
// Called when the ad view has been inflated and the text views are set to
// the values from the loaded ad.
override fun onNativeReady(native: LONative, adView: View) {}
// Called when the icon has been loaded successfully.
override fun onNativeIconLoaded(native: LONative) {}
// Called if loading the icon has failed.
override fun onNativeIconFailed(native: LONative, error: String?) {}
// Called when the main image has been loaded successfully.
override fun onNativeMainImageLoaded(native: LONative) {}
// Called if loading the main image has failed.
override fun onNativeMainImageFailed(native: LONative, error: String?) {}
// Called if loading has failed.
override fun onNativeFailed(native: LONative, error: String?) {}
// Called when the native ad fails during display.
override fun onNativeDisplayFailed(native: LONative, error: String?) {}
// Called when the ad view is actually shown.
override fun onNativeImpression(native: LONative) {}
// Called when the CTA element is clicked.
override fun onNativeClicked(native: LONative) {}
}
GDPR/CCPA and User Consentβ
LiftoffAds complies with the EU's General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA). However, LiftoffAds does not currently manage its own consent mechanism, so you will be required to pass user consent information to our SDK. The following code samples can be used as reference:
LOPrivacySettings.gdprApplicable = true
LOPrivacySettings.hasUserConsent = true
LOPrivacySettings.isAgeRestrictedUser = true
Test Ad Unitsβ
Use the following ad unit IDs to display a LiftoffAds test creative and verify successful integration.
Ad Unit ID | Size | Type |
---|---|---|
liftoff-banner-mrect-html-test | Banner / MRECT | HTML |
liftoff-banner-mrect-video-test | Banner / MRECT | VAST video |
liftoff-interstitial-html-test | Interstitial | HTML |
liftoff-interstitial-video-test | Interstitial | VAST video |
liftoff-rewarded-video-test | Rewarded Interstitial | VAST video |
liftoff-native-test | Native | Native |
COPPAβ
LiftoffAds does not serve end users who fall under the restrictions of the Childrenβs Online Privacy Protection Act (COPPA), specifically age 12 years and younger. If you collect information that indicates a user falls under this category, you must not use the LiftoffAds SDK for the user's sessions.
Troubleshootingβ
Set the log level to DEBUG
before troubleshooting:
Liftoff.logLevel = Liftoff.LogLevel.DEBUG
Observe the logs via logcat using Liftoff
as a filter:
adb logcat | grep Liftoff
Common integration issues:
"No API key provided"
: Missing API key. Verify that you've included the proper initialization code (see above)."Error authentication: Check API key"
: Incorrect API key. Check for any typos in your API key."Unable to fetch ad unit: <PROVIDED_AD_UNIT_ID>"
: Could not fill ad request. Check ad unit ID for typos.
Debugging failuresβ
Requires v1.3.1+.
You can observe the reason for an ad load failure as a toast message. To enable toast messages, turn on debug mode:
Liftoff.setDebug(true)
Reportingβ
Reporting is available via programmatic API or scheduled emails. To receive scheduled email reports, contact your Liftoff POC with your desired recipient email addresses. By default, you will receive daily and monthly reports. The columns below are included; for further customization, contact your Liftoff POC.
- Date
- OS
- Bundle
- Ad Unit
- Ad Unit ID
- Country
- Rewarded
- Size
- Requests
- Fills
- Fill Rate
- Impressions
- Clicks
- CTR
- Revenue
- eCPM