Skip to content

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 = 23 in android/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 (or ext.kotlin_version in android/build.gradle).
  • A Firebase project with google-services.json in android/app/ and the com.google.gms.google-services plugin 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.6

Or let Flutter write that entry for you:

bash
flutter pub add dlserve_flutter --hosted-url https://pub.dlserve.ai

Then 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 if init has not run since the app started. Don't call init while consent is withdrawn.
  • Consent given again: call Dlserve.setPushEnabled(true), then init.

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 true

The 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: call init, 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> in android/app/src/main/AndroidManifest.xml:

    xml
    <meta-data
        android:name="firebase_messaging_auto_init_enabled"
        android:value="false" />

    Dlserve.init asks 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 if init has not run since the app started. Don't call init while consent is withdrawn. If the user consents again, call Dlserve.setPushEnabled(true), then init.

Users and tags ​

dart
Dlserve.login('user-123');
Dlserve.logout();
Dlserve.setTags({'plan': 'premium', 'trial': null}); // a null value deletes the key

Limits: 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 ​

MethodDescription
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 seeWhyFix
Could not find ai.dlserve:dlserve-android:0.6.0The repository is missing from your Android projectStep 1
Build was configured to prefer settings repositories over project repositoriesIt was declared in the wrong file for your resolution modeStep 1, the settings form
could not find package dlserve_flutter at https://pub.devThe hosted: line is missing, so Flutter looked on pub.devStep 2 — use the hosted: form
minSdkVersion 21 cannot be smaller than version 23 declared in libraryYour app's minSdk is below 23Set minSdk = 23
checkDebugAarMetadata … requires … compileSdk 34Your app compiles against an older Android SDKSet compileSdk to 34 or higher
Module was compiled with an incompatible version of Kotlin … expected version is 1.7.1Your app's Kotlin Gradle plugin is older than 1.8Raise it to 1.8 or newer
Devices register, nothing arrivesPush messages never reach dlserve: the service is not switched on, or your handlers do not forward themStep 3
Devices register, nothing arrivesThe service-account JSON is not on the placementUpload it in the dashboard
Notifications show while the app is open, never when it is closedYour onBackgroundMessage handler does not forward to dlserveStep 3
No device appears at allThe google-services plugin or google-services.json is missing"What you need first"
No device appears, the Firebase setup is fineinit has not run yet (for example, no consent yet), or setPushEnabled(false) turned it offStep 4; if isPushEnabled() is false, call setPushEnabled(true), then init

Next: Android (Kotlin) · Troubleshooting