Skip to content

Unity SDK ​

Deliver sponsored push notifications in your Unity game on Android. The SDK wraps the native Android push library — all registration, notification display, and event tracking happens automatically.

Prerequisites ​

  • Unity 2021.3 or later
  • Firebase Unity SDK installed and configured (google-services.json in your project)
  • Android build target
  • 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 game'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.game). Ad partners see it as the site your ads run on.

Install ​

  1. Download the SDK package — either from your dlserve dashboard via the per-channel Get SDK action, or directly: dlserve-unity-latest.unitypackage
  2. In Unity: Assets → Import Package → Custom Package → select the file.

Quick start ​

Add this to your first scene's script:

csharp
using DlserveSDK;
using Firebase.Messaging;

public class GameManager : MonoBehaviour
{
    void Start()
    {
        // Initialize once ads are allowed (after consent where required),
        // with your app ID from the dlserve dashboard.
        Dlserve.Init("your-app-id");

        // Optional: listen for notification events.
        Dlserve.OnNotification += evt =>
            Debug.Log($"dlserve: {evt.Type} — {evt.Title}");

        // Wire up Firebase message routing.
        FirebaseMessaging.TokenReceived += (s, e) =>
            Dlserve.OnNewToken(e.Token);

        FirebaseMessaging.MessageReceived += (s, e) =>
        {
            string json = MiniJson.Serialize(e.Message.Data);
            if (Dlserve.HandleMessageIfDlserve(json)) return;

            // Your own push handling here.
        };
    }
}

That's it. The SDK handles device registration, notification display (with a visible "Sponsored" label), click tracking, and display pixel firing.

Init registers the device and sends its details straight away. If your game needs no consent, call it at startup. If players 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: don't call Init while consent is withdrawn. The Unity package has no call that unregisters a device that already registered, so that device stays registered; the player can still hide sponsored notifications by turning off the "Sponsored offers" channel in Android settings.

Ask for the notification permission (Android 13+) ​

Android 13 and newer show no notification until the player allows notifications for your game. The package declares POST_NOTIFICATIONS; your game asks for it — ideally at a moment where the player sees why:

csharp
using UnityEngine;
using UnityEngine.Android;

public static class NotificationPermission
{
    const string PostNotifications = "android.permission.POST_NOTIFICATIONS";

    public static void RequestIfNeeded()
    {
#if UNITY_ANDROID && !UNITY_EDITOR
        using (var version = new AndroidJavaClass("android.os.Build$VERSION"))
        {
            if (version.GetStatic<int>("SDK_INT") < 33) return;   // older Android asks nothing
        }
        if (!Permission.HasUserAuthorizedPermission(PostNotifications))
        {
            Permission.RequestUserPermission(PostNotifications);
        }
#endif
    }
}

Call NotificationPermission.RequestIfNeeded() wherever it fits your game, before or after Dlserve.Init.

Sponsored notifications post to their own "Sponsored offers" channel, which the player can turn off without touching your game's other notifications. While the permission is missing or that channel is off, nothing is shown — and nothing is counted as shown.

The SDK tells dlserve whether the device can show sponsored notifications. It reports this at every launch, and again when the player answers the 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.

User identity & tags ​

Associate devices with your own user IDs and attach targeting tags:

csharp
Dlserve.Login("user-123");

Dlserve.SetTags(new Dictionary<string, string>
{
    { "plan", "premium" },
    { "level", "42" },
});

// Remove a tag by key.
Dlserve.RemoveTags("level");

// Clear user association.
Dlserve.Logout();

API reference ​

MethodDescription
Dlserve.Init(string appId)Initialize the SDK and register the device. Call once ads are allowed.
Dlserve.Login(string externalId)Associate a user ID (max 256 chars).
Dlserve.Logout()Clear user association (local-only).
Dlserve.SetTags(Dictionary<string, string>)Set targeting tags (max 20, key ≤64, value ≤128 chars).
Dlserve.RemoveTags(params string[])Delete tags by key.
Dlserve.OnNewToken(string)Forward FCM token rotations.
Dlserve.HandleMessageIfDlserve(string)Route FCM message; true = handled by dlserve.
Dlserve.OnNotificationEvent for displayed and opened lifecycle.

How it works ​

  • Push notifications arrive via Firebase Cloud Messaging (FCM).
  • The SDK checks each message for the dlserve marker. Non-dlserve messages are ignored — your own push handling runs normally.
  • Ad notifications display with a "Sponsored" label in a dedicated notification channel that users can independently disable.
  • Tapping a notification opens the link in the device's default browser.

Notification events ​

Subscribe to Dlserve.OnNotification to react when notifications are displayed or tapped:

csharp
Dlserve.OnNotification += (DlserveNotificationEvent evt) =>
{
    // evt.Type is "displayed" or "opened"
    // evt.Title, evt.Body — notification content
    // evt.ClickUrl — destination URL (only on "opened")
};

Updating ​

A new SDK version reaches your game when you import the new package: download it again (from Get SDK or the link above), import it over the old one with Assets → Import Package → Custom Package, rebuild, and release a new version of your game. The current package is 0.6.0: notifications now prepare their offer when they arrive on the device, and no code changes are needed. If you already imported 0.6.0, download and import it once more to get its current build. See what changed in 0.6.0.

Next: Android (Kotlin) · Troubleshooting