Skip to content

React Native SDK ​

Deliver sponsored push notifications in your React Native app on Android. The package 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 ​

  • 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.
  • The dlserve Maven repository declared in your Android project — next section.

1. Add the dlserve repository ​

The wrapper 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 package deliberately does not declare it for you, because a repository declared inside a library module is a build failure on current Gradle setups.

If your project resolves repositories in android/settings.gradle:

groovy
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.dlserve.ai'
            content { includeGroup 'ai.dlserve' }
        }
    }
}

If it still declares them in the top-level android/build.gradle:

groovy
allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.dlserve.ai'
            content { includeGroup 'ai.dlserve' }
        }
    }
}

content { includeGroup 'ai.dlserve' } keeps every other dependency lookup away from our host, so your build stays as fast as it was.

2. Add the package ​

@dlserve/react-native is not published to npm yet — ask your dlserve contact for it and add it as a file dependency:

json
{
  "dependencies": {
    "@dlserve/react-native": "file:../dlserve-react-native"
  }
}

Rebuild the Android app; autolinking picks the module up. If it does not, register it by hand in MainApplication:

kotlin
import com.dlserve.reactnative.DlserveRnPackage

// inside getPackages():
packages.add(DlserveRnPackage())

3. Initialize ​

tsx
import { useEffect } from 'react';
import Dlserve from '@dlserve/react-native';

export default function App() {
  useEffect(() => {
    Dlserve.init('your-app-id');
  }, []);

  // ...
}

your-app-id is the App ID shown on your placement in the dashboard.

4. Ask for the notification permission (Android 13+) ​

Android 13 and newer post nothing until the user grants POST_NOTIFICATIONS:

tsx
import { PermissionsAndroid, Platform } from 'react-native';

if (Platform.OS === 'android' && Number(Platform.Version) >= 33) {
  await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
}

Sponsored notifications post to their own "Sponsored offers" channel, which the user can turn off without touching your app's other notifications.

The wrapper 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.

Users and tags ​

tsx
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
init(appId)Initialize and register the device. Call once, early.
login(externalId)Associate a user id.
logout()Clear the association. Local only.
setTags(tags)Set tags; a null value deletes the key.

Two things live in the native Android SDK and are not surfaced through this wrapper yet: the notification callbacks (onDisplayed / onOpened) and the per-device opt-out (Dlserve.setPushEnabled). addNotificationListener is exported by the package but the native module does not emit events yet, so do not build on it. Users can always turn off the "Sponsored offers" channel in Android settings.

Updating ​

A new SDK version reaches your app when you update this package: ask your dlserve contact for the current copy, replace your local one, rebuild, and release a new version of your app. The current copy 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 on native core 0.6.0, Gradle keeps the files it downloaded then. To fetch the current 0.6.0, run your release build once with --refresh-dependencies in your project's android/ folder, for example ./gradlew --refresh-dependencies :app:bundleRelease, and release that build as a new version of 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.

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 inside a moduleStep 1, the settings form
The package '@dlserve/react-native' doesn't seem to be linkedAutolinking did not runRebuild the Android app, or register the package by hand
Devices register, nothing arrivesThe service-account JSON is not on the placementUpload it in the dashboard

Next: Android (Kotlin) · Troubleshooting