Appearance
Android SDK (Kotlin)
Deliver sponsored push notifications in your Android app. The SDK handles device registration, notification display, click tracking and impression measurement — with the ad source fully concealed.
Current version: 0.6.0 — ai.dlserve:dlserve-android:0.6.0.
What you need first
- minSdk 23 (Android 6.0+) and a Java 17 toolchain.
- A Firebase project for your app with:
google-services.jsonin your app module (app/google-services.json), and- the
com.google.gms.google-servicesGradle plugin applied. Without the plugin the JSON is never read, the app gets no FCM token, and no device ever registers.
- Your Firebase service-account JSON uploaded to your dlserve placement — in the dashboard, open your Android placement and upload it there. We send through your own Firebase project, so until that file is uploaded devices register fine and not a single notification is ever delivered.
- Your app's App bundle ID on the placement — in the dashboard, open your Android placement's Settings and enter your package name (for example
com.example.app). Ad partners see it as the site your ads run on.
The Firebase plugin
Root build.gradle.kts:
kotlin
plugins {
id("com.google.gms.google-services") version "4.4.2" apply false
}App module build.gradle.kts:
kotlin
plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android")
id("com.google.gms.google-services")
}The SDK depends on com.google.firebase:firebase-messaging:24.0.0 and exposes it on your compile classpath, so you do not have to declare it yourself. If you already use the Firebase BOM, keep it and pin 33.1.0 or newer — an older BOM pins an older firebase-messaging, and mixing the two is the usual cause of a duplicate-class or NoSuchMethodError build failure.
1. Add the dlserve repository
The SDK is served from https://maven.dlserve.ai. Declare it at settings level — current Android templates run FAIL_ON_PROJECT_REPOS, where a repository declared inside a module fails the build.
settings.gradle.kts:
kotlin
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.dlserve.ai")
content { includeGroup("ai.dlserve") }
}
}
}Older projects that still resolve per project declare it in the root build.gradle instead:
groovy
allprojects {
repositories {
google()
mavenCentral()
maven {
url 'https://maven.dlserve.ai'
content { includeGroup 'ai.dlserve' }
}
}
}content { includeGroup(...) } keeps every other dependency lookup away from our host, so your build stays as fast as it was.
2. Add the dependency
In your app module's build.gradle.kts:
kotlin
dependencies {
implementation("ai.dlserve:dlserve-android:0.6.0")
}3. Initialize
Register the notification listener in Application.onCreate() — a push can wake your process with no Activity alive, and the listener is what tells you a notification was shown or tapped. Call init once ads are allowed in your app (see below); with no consent to wait for, that is onCreate() too.
kotlin
import ai.dlserve.sdk.Dlserve
import ai.dlserve.sdk.NotificationListener
import android.app.Application
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Dlserve.setNotificationListener(object : NotificationListener {
override fun onDisplayed(title: String, body: String) {
// A sponsored notification was posted to the tray.
}
override fun onOpened(title: String, body: String, clickUrl: String) {
// The user tapped it; the browser is opening.
}
})
Dlserve.init(this, appId = "your-app-id")
}
}appId is the App ID shown on your placement in the dashboard. init does its network work on a background thread and never blocks the main thread.
init registers the device and sends its details straight away — before any notification permission is asked. If your app needs no consent, call it from Application.onCreate(). If your users must consent first (for example under GDPR):
- No consent yet: don't call
init. Nothing is sent. - Consent given: call
init— and on later launches, fromApplication.onCreate()while the consent is stored. - Consent withdrawn: call
Dlserve.setPushEnabled(context, false). It unregisters the device even ifinithas not run since the app started. Don't callinitwhile consent is withdrawn. - Consent given again: call
Dlserve.setPushEnabled(context, true), theninit.
The same two calls are your in-app switch — see Letting users turn notifications off.
Adding the SDK also makes Firebase Messaging fetch a push token at every launch, before init. To stop that, add this inside <application> in your AndroidManifest.xml — init asks for the token itself, so devices still register once you call it:
xml
<meta-data
android:name="firebase_messaging_auto_init_enabled"
android:value="false" />4. Route FCM messages
Option A — you already have a FirebaseMessagingService (recommended)
kotlin
class MyMessagingService : FirebaseMessagingService() {
override fun onMessageReceived(msg: RemoteMessage) {
if (Dlserve.handleMessageIfDlserve(this, msg)) return
// Your own message handling.
}
override fun onNewToken(token: String) {
Dlserve.onNewToken(token)
// Forward to your own backend too, if you have one.
}
}handleMessageIfDlserve returns true and renders the notification when the message is ours, false otherwise. It never throws into your service: a render failure is logged and swallowed.
If you have already deserialized the payload into a plain map (a game engine or a cross-platform runtime typically has), call Dlserve.handleMessageFromData(context, data) instead — same contract.
Option B — you have no messaging service
The SDK ships ai.dlserve.sdk.DlserveMessagingService disabled, so it can never collide with an app that has its own. Enable it with a manifest-merge override in your app's AndroidManifest.xml — note the xmlns:tools declaration, which tools:replace requires:
xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<application>
<service
android:name="ai.dlserve.sdk.DlserveMessagingService"
android:enabled="true"
tools:replace="android:enabled" />
</application>
</manifest>5. Ask for the notification permission (Android 13+)
Android 13 and newer will not post a notification until the user grants POST_NOTIFICATIONS. The SDK declares the permission; your app asks for it:
kotlin
if (Dlserve.needsNotificationPermission(context)) {
// Launch your runtime permission request for POST_NOTIFICATIONS.
}Sponsored notifications post to their own "Sponsored offers" channel, which the user can turn off without touching your app's other notifications. While the permission is missing or that channel is off, nothing is posted — and nothing is counted as shown.
The SDK also tells dlserve whether the device can show sponsored notifications (0.4.0+). It reports this every time your app starts. It reports again when the user answers your permission prompt, or turns your app's notifications or the "Sponsored offers" channel on or off. The change is picked up the next time your app comes to the foreground or a notification arrives. A device that can't show notifications gets only an occasional check-in instead of the full schedule. It gets the full schedule again as soon as the user turns notifications back on.
6. Choose the status-bar icon
Android masks the small icon to its alpha channel, so it must be a flat white-on-transparent silhouette. The SDK ships one (ic_dlserve_notification). To use your own:
kotlin
Dlserve.setSmallIcon(R.drawable.ic_stat_myapp)Users and tags
kotlin
Dlserve.login("user-123") // associate this device with your user id
Dlserve.logout() // clear the association — local only, see below
Dlserve.setTags(mapOf(
"plan" to "premium",
"trial" to null, // a null value deletes the key
))Limits — exceeding one throws IllegalArgumentException on the calling thread, so a bad value is caught in development instead of vanishing:
| Field | Limit |
|---|---|
externalId | ≤ 256 characters |
| number of tags | ≤ 20 |
| tag key | ≤ 64 characters |
| tag value | ≤ 128 characters |
logout() is local-only. It clears the stored user id on the device and sends nothing. It does not stop notifications and is not an opt-out.
Letting users turn notifications off
kotlin
// Off: unregisters the device, even if init has not run since the app started.
Dlserve.setPushEnabled(context, false)
// Back on: switch it on, then init registers the device again.
Dlserve.setPushEnabled(context, true)
Dlserve.init(context, appId = "your-app-id")
Dlserve.isPushEnabled(context) // current state, default trueThe choice is stored on the device and survives restarts. Off unregisters the device straight away — init does not have to run first; if the device is offline then, the SDK retries on the next dlserve push it receives or the next init — and on a device that never registered it sends nothing. While it is off, init, onNewToken and the message handlers register and show nothing, so don't call init while it is off; to turn it back on, call setPushEnabled(context, true), then init. Give users this switch somewhere in your settings screen — the system-level "Sponsored offers" channel toggle is a fallback, not a substitute: it only hides the notifications, the device stays registered and ads are still requested for it.
API reference
| Method | Description |
|---|---|
Dlserve.init(context, appId) | Initialize the SDK and register the device. Call once ads are allowed — step 3. Does nothing while sponsored notifications are off. |
Dlserve.login(externalId) | Associate a user id (≤ 256 chars). Throws IllegalArgumentException if longer. |
Dlserve.logout() | Clear the user association. Local only — not an opt-out. |
Dlserve.setTags(Map<String, String?>) | Set tags; a null value deletes the key. Throws IllegalArgumentException over the limits. |
Dlserve.setPushEnabled(context, enabled) | Turn sponsored notifications on or off for this device. Persisted. Off unregisters the device, even before init. After turning them back on, call init. |
Dlserve.isPushEnabled(context) | Whether they are on. Default true. |
Dlserve.onNewToken(token) | Forward an FCM token rotation. |
Dlserve.handleMessageIfDlserve(context, msg) | Route a RemoteMessage; true = handled by us. |
Dlserve.handleMessageFromData(context, data) | Same, for an already-deserialized data map. |
Dlserve.needsNotificationPermission(context) | Whether POST_NOTIFICATIONS still has to be requested. |
Dlserve.setNotificationListener(listener) | Observe onDisplayed / onOpened. Set it in Application.onCreate(). |
Dlserve.setSmallIcon(resId) | Override the status-bar icon. |
Troubleshooting
| What you see | Why | Fix |
|---|---|---|
Could not find ai.dlserve:dlserve-android:0.6.0 | The repository is missing | Step 1 — and check it is in settings.gradle.kts, not a module |
Build was configured to prefer settings repositories over project repositories | The repository was declared inside a module | Move it to settings.gradle.kts |
Logcat: Dlserve: no FCM token — apply the com.google.gms.google-services plugin and put google-services.json in your app module | The google-services plugin or google-services.json is missing | "What you need first" |
| Devices register, no notification ever arrives | The service-account JSON is not on the placement | Upload it in the dashboard |
| Devices register, no notification ever arrives | Push messages never reach the SDK: no service routes them | Step 4 |
Logcat: Dlserve: config unavailable for appId '…' — dropping this push | The App ID is wrong, or it is not an Android placement — the push was dropped | Copy the App ID from the placement again, step 3 |
Nothing on Android 13+, logcat: Dlserve: not shown: notifications are off for this app or its Sponsored offers channel | POST_NOTIFICATIONS was never granted, or the user turned off your app's notifications | Step 5 |
| Nothing although the permission is granted | The user turned off "Sponsored offers" in system settings | Nothing to fix — to unregister the device too, offer setPushEnabled |
IllegalArgumentException from login / setTags | A value is over a limit | "Users and tags" |
Duplicate class / NoSuchMethodError around Firebase | An old Firebase BOM | Pin BOM 33.1.0 or newer |
What changed in 0.6.0
Notifications now prepare their offer when they arrive on the device, so the offer is current even if the phone was offline for a while. No code changes are needed: update the dependency version and rebuild.
Notifications that arrive while your app is closed now identify the device the same way as the SDK's other requests, so they are counted even if init has not run yet in that process. On Android 9 and later this covers your app's main process: a messaging service you run in its own process (android:process) without init keeps the earlier identification there, because starting WebView in a second process can crash your app.
If your project already built with 0.6.0, Gradle keeps the copy it downloaded then. Run your release build once with --refresh-dependencies to fetch the current 0.6.0, for example ./gradlew --refresh-dependencies :app:bundleRelease, and release that build as a new version of your app. The flag must go on a build that compiles your app: ./gradlew --refresh-dependencies on its own downloads nothing. If you release from CI with a restored Gradle cache, add the flag to that build too, or clear that cache once.
Upgrading
Change the dependency to the current version:
kotlinimplementation("ai.dlserve:dlserve-android:0.6.0")Sync Gradle and release a new version of your app. No code changes are needed.
Your users move to the current version as they update your app from Google Play. Devices on an older release keep working; their notifications just don't show the ad's own icon.
What changed in 0.5.0
- Notifications now show the ad's own icon beside the text. When the ad also has a picture, it appears when the user expands the notification, as before. Loading the icon is part of how a view of the ad is measured, so more of the notifications your users see are counted.
- The icon and the picture download at the same time, and each download gives up after five seconds, so a slow picture can't hold a notification back for long. A notification whose icon or picture doesn't arrive in time is shown without it.
- The report that a notification was shown, and the ad's own view measurement that follows it, now try again, up to twice within a few seconds, when the device can't connect or the server is briefly unavailable. Fewer shown notifications go uncounted, and a report that may already have arrived is never sent twice, so nothing is counted twice.
- A device that can't show notifications still downloads nothing.
- No API changes.
What changed in 0.4.0
- The SDK now tells dlserve whether the device can show sponsored notifications. That means your app's notifications are on (on Android 13+, the notification permission is granted) and the "Sponsored offers" channel is not turned off. It reports this at every launch, and again when it changes: when the user answers your permission prompt or changes the setting in system settings. A device that can't show notifications gets only an occasional check-in instead of the full schedule — see step 5.
- A device that can't show a notification no longer downloads the notification's image.
- No API changes.
What changed in 0.3.1
setPushEnabled(context, false)now unregisters the device even ifinithas not run since the app started, so withdrawn consent takes effect without callinginitfirst. Before, an opt-out made beforeinitwas only stored, and the device stayed registered.- If that unregister fails — the device is offline, say — the SDK retries it on the next dlserve push the device receives or the next
init. An opt-out made whileinitis still registering the device now takes effect too. - No API changes.
What changed in 0.3.0
- The device language is now reported, so ads can be matched to the language your users read. Devices on older versions are treated as English.
- The SDK now identifies itself as the device's built-in browser on every request, so the ad request and the impression describe the device the same way and impressions are counted. Taps still open the user's default browser.
- No API changes.
What changed in 0.2.0
0.1.0 was never published to a repository — 0.2.0 is the first version you can resolve. If you were building against a local copy, note:
- The impression pixel and
onDisplayednow fire only when the notification was really shown. - Tapping a notification now calls
onOpenedbefore the browser opens; the callback used to be inert. loginandsetTagsnow throw on invalid input instead of dropping the call silently.- New:
setPushEnabled/isPushEnabled(opt-out) andsetSmallIcon. - The render path can no longer throw into your
FirebaseMessagingService.
Next: Flutter · React Native · Troubleshooting