Android (Kotlin)

Zero third-party dependencies — uses HttpURLConnection + the platform org.json. minSdk 21.

Package	`co.theaimart.adx:adx-android`
Language	Kotlin
Distribution	Maven Central
Requirements	minSdk 21, Android SDK + JDK 17 to build.

Install

build.gradle.kts

kotlin

// settings.gradle.kts -> dependencyResolutionManagement { repositories { mavenCentral() } }
dependencies {
    implementation("co.theaimart:adx-android:1.0.0")
}

Usage

Drop-in banner + manual render

kotlin

import co.theaimart.adx.Adx
import co.theaimart.adx.AdRequest
import co.theaimart.adx.BannerAdView

val adx = Adx(apiKey = "pk_your_publisher_key")

// Option A — drop-in banner view:
val banner = BannerAdView(context)
banner.load(adx, AdRequest(slotId = "8b1f2c3d-....-uuid"))
container.addView(banner)   // viewability + click handled automatically

// Option B — request + render yourself:
adx.requestAd(AdRequest(slotId = "8b1f-uuid")) { ad ->
    if (ad.filled) {
        // render ad.creative ...
        if (ad.isTrackable) adx.reportViewable(ad.impId)
    }
}

Production hardening

Most ad SDKs pull in OkHttp, whose default User-Agent (okhttp/…) is on the backend's bot blocklist and causes silent no-fill. This SDK uses HttpURLConnection and always sends theaimart-adx-android/<ver> (Android <os>; <model>) — off the blocklist, with an Android token so the backend classifies the device correctly.
SQL-filter-safe-encodes free-text params and fails closed (errors -> no-fill, never a crash).

These behaviors come directly from the wire contract — see User-Agent rules and WAF-safe encoding for why they matter. Not getting fills? See Troubleshooting.

API

Member	Notes
`Adx(apiKey, baseUrl = …, timeoutMs = …, userAgent = …)`	Construct a client.
`adx.requestAd(request, callback)`	Callback fires on the main thread.
`adx.requestAdBlocking(request): Ad`	Call from a background thread / coroutine.
`adx.reportViewable(impId)`	Best-effort viewability beacon.
`adx.clickUrl(impId): String`	Build a click-tracker URL.
`BannerAdView(context).load(adx, request)`	with onAdLoaded / onAdFailed callbacks.

The normalized Ad model

filled, kind (IMAGE/HTML/NO_FILL), source (INTERNAL/OPENRTB/HOUSE), impId, creative, auction, reason, isTrackable.

Build & test

bash

cd packages/android
./gradlew :adx:test          # unit tests (Encoding + Models) on the JVM
./gradlew :adx:assembleRelease
./gradlew :adx:publishToMavenLocal

The Encoding and Ad parsing logic is covered by JVM unit tests; BannerAdView requires a device/emulator.

React Native

iOS (Swift)