Skip to main content

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​

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:

build.gradle
repositories {
  // ...
  mavenCentral()
}

Add the LiftoffAds SDK as a dependency to your app module's build.gradle:

app/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:

  1. Download and unzip the LiftoffAds SDK.
  2. Move the extracted liftoffads.aar to your local repository.
app/build.gradle
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.

MainActivity.kt
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) {}
}

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:

MainActivity.kt
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 IDSizeType
liftoff-banner-mrect-html-testBanner / MRECTHTML
liftoff-banner-mrect-video-testBanner / MRECTVAST video
liftoff-interstitial-html-testInterstitialHTML
liftoff-interstitial-video-testInterstitialVAST video
liftoff-rewarded-video-testRewarded InterstitialVAST video
liftoff-native-testNativeNative

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:

MainActivity.kt
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:

MainActivity.kt
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