Android Push Notifications

The Alogame SDK uses Firebase Cloud Messaging (FCM) for push notifications. Firebase must be explicitly added to your game's build — the SDK declares it as implementation (internal only), so it is not exposed as a transitive dependency to consuming apps. You need: the Firebase library, the configuration file, the Gradle plugin, the manifest service, and one optional listener.

Step 1 — Get google-services.json

1. Open Firebase Console → select your project (or create one).
2. Go to Project settings → Your apps → Android.
3. Register your app with the same applicationId as your game.
4. Download google-services.json.
5. Place it in your app/ module folder (same level as app/build.gradle):

app/
├── google-services.json   ← here
├── src/
└── build.gradle.kts

Each game has its own Firebase project and its own google-services.json. Do not share files across games.

Step 2 — Add Firebase Messaging dependency

Add the Firebase BOM and messaging library to your app-level build file:

app/build.gradle.kts (Kotlin DSL)

dependencies {
    implementation(platform("com.google.firebase:firebase-bom:32.7.0"))
    implementation("com.google.firebase:firebase-messaging-ktx")
}

app/build.gradle (Groovy DSL)

dependencies {
    implementation platform('com.google.firebase:firebase-bom:32.7.0')
    implementation 'com.google.firebase:firebase-messaging-ktx'
}

The BOM pins all Firebase library versions together — you don't need to specify individual version numbers for other Firebase deps you may already use.

Step 3 — Apply the Google Services Gradle plugin

The plugin parses google-services.json and injects Firebase configuration at build time.

Root build.gradle.kts:

build.gradle.kts (root)

plugins {
    id("com.google.gms.google-services") version "4.4.1" apply false
}

Root build.gradle (Groovy):

build.gradle (root)

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.1'
    }
}

App-level build.gradle.kts:

app/build.gradle.kts

plugins {
    id("com.android.application")
    id("com.google.gms.google-services")   // ← add this
}

App-level build.gradle (Groovy):

app/build.gradle

apply plugin: 'com.google.gms.google-services'

Step 4 — Declare OEGNotificationService in your manifest

The SDK ships OEGNotificationService (a FirebaseMessagingService) but does not auto-merge it into your app's manifest. You must declare it explicitly:

app/src/main/AndroidManifest.xml

<application>

    <service
        android:name="vn.oeg.sdk.v2.core.push.OEGNotificationService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>

</application>

This service handles two things automatically:

• Token rotation — when FCM refreshes the device token mid-session, the service forwards it to the SDK, which re-registers it with the backend.
• Message dispatch — incoming FCM data messages are forwarded to your OEGPush.PushListener.

Step 5 — Request notification permission (Android 13+)

On API 33 (Android 13) and above, the POST_NOTIFICATIONS permission must be requested at runtime before any notification can be shown:

Kotlin

import android.Manifest
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts

// Register before your Activity/Fragment is resumed
val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    if (isGranted) {
        // Notifications will be shown
    }
}

// Call at an appropriate point (e.g. after tutorial)
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
}

Java

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    ActivityResultLauncher<String> launcher = registerForActivityResult(
        new ActivityResultContracts.RequestPermission(),
        isGranted -> { /* handle result */ }
    );
    launcher.launch(Manifest.permission.POST_NOTIFICATIONS);
}

On Android 12 and below, no runtime permission is required — notifications are enabled by default.

Step 6 — Receive push messages in game code

Set a listener before or immediately after OEGAuth.Builder.build() to avoid missing messages that arrive during SDK initialization:

Kotlin

import vn.oeg.sdk.v2.core.push.OEGPush

OEGPush.setPushListener(object : OEGPush.PushListener {
    override fun onMessageReceived(data: Map<String, String>) {
        val title = data["title"]
        val body  = data["body"]
        // Show custom in-game UI, or a system notification
    }

    override fun onTokenRefreshed(token: String) {
        // Optional — SDK handles re-registration automatically.
        // Log or forward to your own analytics if needed.
    }
})

Java

import vn.oeg.sdk.v2.core.push.OEGPush;
import java.util.Map;

OEGPush.INSTANCE.setPushListener(new OEGPush.PushListener() {
    @Override
    public void onMessageReceived(Map<String, String> data) {
        String title = data.get("title");
        String body  = data.get("body");
    }

    @Override
    public void onTokenRefreshed(String token) {}
});

FCM data-only messages (no notification block in the payload) are always delivered to onMessageReceived regardless of whether the app is in foreground or background.

FCM notification messages (with a notification block) are displayed automatically by the system when the app is in background, and delivered to onMessageReceived when the app is in foreground.

Optional — Topic subscriptions

Kotlin

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

CoroutineScope(Dispatchers.IO).launch {
    OEGPush.subscribeToTopic("events")
    OEGPush.unsubscribeFromTopic("events")
}

Java

// Topics require a coroutine scope — use from Kotlin or wrap in an async task.

Optional — Read the FCM token directly

Kotlin

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

// Cached (instant, may be null before first token fetch)
val cached = OEGPush.getCachedToken()

// Fresh fetch (suspending)
CoroutineScope(Dispatchers.IO).launch {
    val token = OEGPush.getDeviceToken()
}

How the SDK manages push tokens

Event	What the SDK does
User logs in	FCM token synced to Alogame backend (POST v2/push/token)
FCM token obtained or rotated	Token forwarded to Adjust for uninstall tracking (automatic)
FCM token rotates mid-session	Re-synced automatically via OEGNotificationService.onNewToken()
User logs out	Token deactivated on backend (DELETE v2/push/token)
Push not configured (no google-services.json)	All sync operations silently skip — auth flows are never blocked

Checklist

• google-services.json placed in app/ folder
• firebase-bom + firebase-messaging-ktx added to app-level dependencies {}
• com.google.gms.google-services plugin applied in root and app build files
• OEGNotificationService declared in AndroidManifest.xml
• Runtime POST_NOTIFICATIONS permission requested on Android 13+ devices
• OEGPush.setPushListener() called before OEGAuth.Builder.build()