Android SDK Implementation and Integration Overview

The AdCel Android SDK is a core component of the AdCel Intelligent Performance Platform, designed to provide mobile application developers with a high-performance, lightweight solution for programmatic ad mediation and real-time bidding (RTB). By integrating our Android library, publishers gain access to a global ecosystem of demand-side platforms (DSPs) and ad exchanges, ensuring maximum fill rates and optimised eCPMs through sophisticated auction dynamics.

For developers managing cross-platform applications, we recommend reviewing our recent iOS platform updates to maintain feature parity and performance consistency across both mobile operating systems.

This technical documentation outlines the necessary steps to successfully initialise and configure the AdCel SDK within a native Android environment. The SDK is built to be compatible with modern Android development standards, supporting both Java and Kotlin implementations while maintaining a minimal footprint on the final application size.

Prerequisites and System Requirements

Before commencing the integration process, ensure that your development environment meets the following minimum requirements to guarantee interoperability and stability:

• Android Studio Arctic Fox (2020.3.1) or higher.
• Android API Level 21 (Android 5.0 Lollipop) or higher.
• Gradle version 6.5 or higher.
• A valid AdCel Publisher Account and Application ID, obtainable via the AdCel Dashboard.

Dependency Management and Installation

The AdCel Android SDK is distributed via a secure Maven repository. To include the SDK in your project, you must first configure your project-level build.gradle file to include the AdCel repository URL. This ensures that the build system can resolve the specialised libraries required for mediation and RTB functionalities.

In your project-level build.gradle, add the following repository configuration:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://repo.adcel.co/artifactory/android-sdk/' }
    }
}

Subsequently, add the SDK dependency to your module-level build.gradle file. It is recommended to use the latest stable version to benefit from the most recent security patches and performance optimisations. Ensure that you also include necessary dependencies for third-party mediation adapters if you intend to utilise a multi-network waterfall approach alongside our programmatic bidding engine.

Manifest Configuration and Permissions

To facilitate the delivery of high-quality, relevant advertisements, the AdCel SDK requires certain system permissions. These must be declared within your AndroidManifest.xml file. While the SDK handles many requirements internally, explicit declaration of network state permissions is essential for the SDK to determine connectivity status and prevent unnecessary data consumption during offline periods.

The following permissions are mandatory for standard operation:

• INTERNET: Required to fetch ad creative and communicate with the AdCel RTB server.
• ACCESS_NETWORK_STATE: Used to verify if a connection is available before initiating an ad request.
• AD_ID: For applications targeting API level 33 or higher, this permission is required to access the Google Advertising ID for attribution and frequency capping.

SDK Initialisation and Lifecycle Management

Initialisation is a critical phase that prepares the SDK for ad serving. This should be performed as early as possible in the application lifecycle, typically within the onCreate method of your Application class or the main Activity. Asynchronous initialisation ensures that the main thread remains unblocked, providing a seamless user experience while the SDK synchronises configuration data and pre-caches necessary resources.

When initialising, you must provide your unique Application ID. The SDK will then communicate with the AdCel Intelligent Performance Platform to retrieve the latest mediation settings, authorised seller lists (app-ads.txt compliance), and privacy configurations. Failure to initialise the SDK correctly will result in failed ad requests and a lack of revenue reporting.

Implementation of Ad Formats

The AdCel Android SDK supports a diverse range of ad formats, each tailored for specific user engagement scenarios within a mobile application. Developers can choose from standard banners, full-screen interstitials, and rewarded video ads, all of which are managed through a unified API surface.

Standard Banner Integration

Banners are rectangular image or HTML5 ads that occupy a portion of the application layout. They can be placed within the XML layout file or instantiated programmatically. The SDK provides custom view classes that handle the automated refreshing of creatives based on the intervals defined in the AdCel dashboard, ensuring that the inventory is consistently monetised without manual intervention.

Interstitial and Rewarded Ads

Interstitial ads provide high-impact, full-screen experiences during natural transition points in an app. Rewarded ads, conversely, offer users an incentive—such as in-game currency or premium content—in exchange for viewing a video. Both formats require pre-loading to ensure instant playback. The AdCel SDK utilizes a listener-based architecture, allowing developers to track events such as onAdLoaded, onAdFailedToLoad, and onUserEarnedReward.

Privacy, Consent, and Regulatory Compliance

In accordance with global data protection standards such as the GDPR (General Data Protection Regulation) and CCPA (California Consumer Privacy Act), the AdCel SDK includes robust tools for managing user consent. It is the responsibility of the publisher to collect consent via a Consent Management Platform (CMP) and pass this information to the SDK.

The SDK supports the IAB TCF v2.0 framework, ensuring that consent strings are properly propagated to all downstream demand partners. Additionally, developers can manually set flags for COPPA (Children’s Online Privacy Protection Act) compliance to ensure that data collection is restricted for child-directed applications, maintaining the integrity of the Trust and Transparency Framework.

ProGuard and R8 Configuration

For applications that utilise code shrinking and obfuscation via ProGuard or R8, specific rules must be added to the configuration file to prevent the removal of essential SDK classes. Because the SDK uses reflection for certain mediation adapter optimisations, stripping these classes can lead to runtime exceptions or a total loss of ad revenue.

Ensure that your proguard-rules.pro file includes directives to keep the AdCel package and any associated third-party mediation libraries. This guarantees that the internal logic of the SDK remains intact while the rest of your application code is safely obfuscated for security and size reduction.