Appearance
Flutter SDK
Deliver sponsored push notifications in your Flutter app on Android. The plugin is a thin wrapper — registration, notification display and tracking all run in the native Android SDK.
Android only. There is no iOS implementation.
What you need first
- Flutter 3.10+ with an Android build target. Any Android Gradle plugin from 7.3 through 9.x works, with or without its built-in Kotlin. Your Android app also needs:
- minSdk 23 (Android 6.0+). Apps created before Flutter 3.35 default to 21 — set
minSdk = 23inandroid/app/build.gradle(.kts). - compileSdk 34+. Apps created on Flutter 3.16 or earlier default to 33.
- Kotlin Gradle plugin 1.8+. Apps created on Flutter 3.22 or earlier pin 1.7.10 — raise it in
android/settings.gradle(orext.kotlin_versioninandroid/build.gradle).
- minSdk 23 (Android 6.0+). Apps created before Flutter 3.35 default to 21 — set
- A Firebase project with
google-services.jsoninandroid/app/and thecom.google.gms.google-servicesplugin applied. - Your Firebase service-account JSON uploaded to your dlserve placement in the dashboard. We send through your own Firebase project, so until that file is uploaded devices register fine and nothing 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.
1. Add the dlserve repository
The plugin depends on the native core ai.dlserve:dlserve-android:0.6.0, served from https://maven.dlserve.ai. Declare the repository in your app's Android project; the plugin deliberately does not declare it for you, because a repository declared inside a plugin module is a build failure on current Gradle setups.
Flutter's current template keeps repositories in android/build.gradle.kts:
kotlin
allprojects {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.dlserve.ai")
content { includeGroup("ai.dlserve") }
}
}
}Older projects have the same block in Groovy, in android/build.gradle:
groovy
allprojects {
repositories {
google()
mavenCentral()
maven {
url 'https://maven.dlserve.ai'
content { includeGroup 'ai.dlserve' }
}
}
}If your project instead resolves repositories in android/settings.gradle.kts under dependencyResolutionManagement, put the same maven { ... } block there — in that mode Gradle refuses a repository declared anywhere else.
2. Add the plugin
dlserve_flutter is served from the dlserve package repository, https://pub.dlserve.ai — not pub.dev. Add it to pubspec.yaml:
yaml
dependencies:
dlserve_flutter:
hosted: https://pub.dlserve.ai
version: ^0.1.6Or let Flutter write that entry for you:
bash
flutter pub add dlserve_flutter --hosted-url https://pub.dlserve.aiThen run flutter pub get.
3. Route push messages to dlserve
Sponsored notifications arrive as push messages, and something in your app has to hand them to dlserve. Skip this step and devices register fine, but no notification is ever shown. Pick the case that matches your app.
Your app has no push handling of its own
The plugin ships its message handler switched off, so it can never clash with an app that has one. Switch it on in android/app/src/main/AndroidManifest.xml: add the xmlns:tools line to your <manifest> tag and the <service> inside your <application> — tools:replace needs that xmlns:tools line.
xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<application>
<!-- Keep everything already here; add this service. -->
<service
android:name="ai.dlserve.sdk.DlserveMessagingService"
android:enabled="true"
tools:replace="android:enabled" />
</application>
</manifest>Your app uses firebase_messaging (or another push package)
Do not switch the service above on — two handlers for the same messages collide, and one of them never gets its messages. Forward each message instead, both while your app is open (onMessage) and while it is in the background or closed (your onBackgroundMessage handler):
dart
import 'package:dlserve_flutter/dlserve_flutter.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter/material.dart';
@pragma('vm:entry-point')
Future<void> onBackgroundMessage(RemoteMessage message) async {
if (await Dlserve.handleMessage(message.data)) return;
// Your own background handling.
}
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
FirebaseMessaging.onBackgroundMessage(onBackgroundMessage);
FirebaseMessaging.onMessage.listen((RemoteMessage message) async {
if (await Dlserve.handleMessage(message.data)) return;
// Your own foreground handling.
});
runApp(const MyApp());
}handleMessage returns true when the message was a sponsored notification (shown, or skipped because the user turned them off) and false when it was not — pass those on to your own handling. Sponsored pushes are sent at high priority with no notification part, so your background handler runs for them even when your app is closed. With another push package, call Dlserve.handleMessage(data) from wherever it hands you a message's data, in the foreground and in the background.
4. Initialize
dart
import 'package:dlserve_flutter/dlserve_flutter.dart';
// Call once ads are allowed: at startup when consent is already stored,
// or right after the user gives it.
Future<void> startSponsoredNotifications() => Dlserve.init('your-app-id');your-app-id is the App ID shown on your placement in the dashboard. Device registration, FCM token management and notification display are all handled natively from there.
init registers the device and sends its details straight away — before any notification permission is asked. If your app needs no consent, call it at startup. 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, call it at startup while the consent is stored. - Consent withdrawn: call
Dlserve.setPushEnabled(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(true), theninit.
5. Ask for the notification permission (Android 13+)
Android 13 and newer post nothing until the user grants POST_NOTIFICATIONS. Request it with whichever permission package your app already uses, before you expect notifications to appear.
Sponsored notifications post to their own "Sponsored offers" channel, which the user can turn off without touching your app's other notifications.
The plugin tells dlserve whether the device can show sponsored notifications. It reports this at every launch, and again when the user answers your prompt or turns notifications or that channel on or off. A device that can't show them gets only an occasional check-in instead of the full schedule.
Letting users turn notifications off
dart
// Off: unregisters the device, even if init has not run since the app started.
await Dlserve.setPushEnabled(false);
// Back on: switch it on, then init registers the device again.
await Dlserve.setPushEnabled(true);
await Dlserve.init('your-app-id');
final bool on = await Dlserve.isPushEnabled(); // 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 registers nothing and sponsored pushes that still arrive are not shown, so don't call init while it is off; to turn it back on, call setPushEnabled(true), then init. Give users this switch somewhere in your settings screen.
Turning off the "Sponsored offers" channel in Android settings only hides the notifications: the device stays registered, so ads are still requested for it. setPushEnabled(false) is the switch that takes the device out.
Privacy
Consent. No consent yet: don't call
init— before it, the plugin sends nothing. Consent given: callinit, and on later launches at startup while the consent is stored. See step 4.Firebase start-up. Adding the plugin makes Firebase Messaging fetch a push token at every launch, before your app has called
init. To stop that, add this inside<application>inandroid/app/src/main/AndroidManifest.xml:xml<meta-data android:name="firebase_messaging_auto_init_enabled" android:value="false" />Dlserve.initasks for the token itself, so devices still register once you call it. If your app has push of its own, check that it asks for its token itself too.Withdrawn consent. Call
Dlserve.setPushEnabled(false)— it unregisters the device even ifinithas not run since the app started. Don't callinitwhile consent is withdrawn. If the user consents again, callDlserve.setPushEnabled(true), theninit.
Users and tags
dart
Dlserve.login('user-123');
Dlserve.logout();
Dlserve.setTags({'plan': 'premium', 'trial': null}); // a null value deletes the keyLimits: user id ≤ 256 characters, ≤ 20 tags, key ≤ 64 characters, value ≤ 128 characters.
logout() is local-only — it clears the stored user id on the device, sends nothing, and is not an opt-out.
API reference
| Method | Description |
|---|---|
Dlserve.init(String appId) | Initialize and register the device. Call once ads are allowed — step 4. Does nothing while sponsored notifications are off. |
Dlserve.handleMessage(Map<String, dynamic> data) | Hand a push message's data to dlserve. true = it was a sponsored notification (shown, or skipped because they are off); false = not ours, handle it yourself. |
Dlserve.setPushEnabled(bool enabled) | Turn sponsored notifications on or off for this device. Off unregisters the device, even before init. After turning them back on, call init. Stored on the device. |
Dlserve.isPushEnabled() | Whether they are on. Default true. |
Dlserve.login(String externalId) | Associate a user id. |
Dlserve.logout() | Clear the association. Local only. |
Dlserve.setTags(Map<String, String?> tags) | Set tags; a null value deletes the key. |
handleMessage and isPushEnabled return Future<bool>; the others return Future<void>. All of them complete when the native call returns.
Updating
A new SDK version reaches your app when you update this plugin. New versions are published to https://pub.dlserve.ai: run flutter pub upgrade dlserve_flutter to move to the newest version your version: constraint allows, or raise the constraint for a newer minor version. Then rebuild and release a new version of your app. The current version is built on the native core 0.6.0 — see what changed in 0.6.0.
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.
If your project already built with plugin 0.1.6, Gradle keeps the copy of the native core it downloaded then. To fetch the current 0.6.0, run a release build once with --refresh-dependencies in your project's android/ folder, for example ./gradlew --refresh-dependencies :app:bundleRelease; ./gradlew --refresh-dependencies on its own downloads nothing. Later builds, flutter build included, keep the current copy, so then build and release a new version of your app as usual. If you release from CI with a restored Gradle cache, run the same command there before your build, or clear that cache once.
Troubleshooting
| What you see | Why | Fix |
|---|---|---|
Could not find ai.dlserve:dlserve-android:0.6.0 | The repository is missing from your Android project | Step 1 |
Build was configured to prefer settings repositories over project repositories | It was declared in the wrong file for your resolution mode | Step 1, the settings form |
could not find package dlserve_flutter at https://pub.dev | The hosted: line is missing, so Flutter looked on pub.dev | Step 2 — use the hosted: form |
minSdkVersion 21 cannot be smaller than version 23 declared in library | Your app's minSdk is below 23 | Set minSdk = 23 |
checkDebugAarMetadata … requires … compileSdk 34 | Your app compiles against an older Android SDK | Set compileSdk to 34 or higher |
Module was compiled with an incompatible version of Kotlin … expected version is 1.7.1 | Your app's Kotlin Gradle plugin is older than 1.8 | Raise it to 1.8 or newer |
| Devices register, nothing arrives | Push messages never reach dlserve: the service is not switched on, or your handlers do not forward them | Step 3 |
| Devices register, nothing arrives | The service-account JSON is not on the placement | Upload it in the dashboard |
| Notifications show while the app is open, never when it is closed | Your onBackgroundMessage handler does not forward to dlserve | Step 3 |
| No device appears at all | The google-services plugin or google-services.json is missing | "What you need first" |
| No device appears, the Firebase setup is fine | init has not run yet (for example, no consent yet), or setPushEnabled(false) turned it off | Step 4; if isPushEnabled() is false, call setPushEnabled(true), then init |
Next: Android (Kotlin) · Troubleshooting