Android SDK

Beta · 0.1.0-beta.2 · Android API 23+

The Kotlin-first SDK owns installation bootstrap, FCM token refresh, encrypted credentials, bounded offline event/receipt retry, consent, identity, and signed notification receipts. Java callers can use its public static entry points.

Prerequisites

  1. Create an Android app in PushHub and configure its Firebase service-account credential.
  2. Add the Firebase google-services.json file to the Android application.
  3. In App → Integration → Client SDK access, create a publishable ph_pub_ key.
  4. Never place a server ph_live_ key in an APK or source repository.

Install

The current Beta direct artifact is pushhub-android-0.1.0-beta.2.aar. Beta 2 adds the shared Android bridge used by the Unity and Unreal previews; native Android applications use the same public Kotlin API. When consuming the AAR directly, also declare Firebase Messaging 24.1.0, AndroidX Core 1.15.0, Security Crypto 1.1.0-alpha06, WorkManager 2.10.0, and Kotlin Coroutines Android 1.9.0.

For source/Maven-local development:

git clone https://github.com/kemegames-studio/pushhub.git
cd pushhub/sdk/android
./gradlew :pushhub:publishToMavenLocal

implementation("com.kemegames.pushhub:pushhub-android:0.1.0-beta.2")

Configure and start

PushHub.configure(
    applicationContext,
    PushHubConfig(
        appId = UUID.fromString(BuildConfig.PUSHHUB_APP_ID),
        publishableKey = BuildConfig.PUSHHUB_PUBLISHABLE_KEY
    )
)

lifecycleScope.launch { PushHub.start() }

Configuration is idempotent and does not prompt for notification permission. start() gets the current FCM token, creates or recovers the installation, stores its credential with Android Keystore-backed encrypted preferences, and flushes eligible queued writes.

Permission and channels

Ask only from UI where the player understands the value:

PushHub.createNotificationChannel(this, id = "live_ops", name = "Live updates")
if (!PushHub.hasNotificationPermission(this)) PushHub.requestNotificationPermission(this)

Android 12 and earlier do not use the runtime POST_NOTIFICATIONS prompt. The SDK never displays it automatically.

Identity, consent, and events

lifecycleScope.launch {
    PushHub.identify("player-1842", mapOf("tier" to "gold", "region" to "mena"))
    PushHub.setConsent(PushHubConsent.GRANTED)
    PushHub.track("level_completed", mapOf("level" to "20"))
}

lifecycleScope.launch { PushHub.unlinkUser() } // on logout

Events and receipts retry only transport, timeout, rate-limit, and server failures. The encrypted queue retains at most 100 records for seven days and WorkManager waits for connectivity. Authentication and validation failures are removed instead of looping.

FCM lifecycle

The AAR manifest registers PushHubFirebaseMessagingService. If the host needs raw callbacks, subclass it:

class GameMessagingService : PushHubFirebaseMessagingService() {
    override fun onPushHubMessage(message: RemoteMessage) {
        // Render or route according to the host application's policy.
    }
}

The base service forwards refreshed FCM tokens and reports receipt when Android delivers a data message to the process. Call PushHub.reportOpened(payload) from the notification-open path. Receipt tokens—not notification UUIDs alone—authorize reports.

Reset and diagnostics

lifecycleScope.launch { PushHub.reset() }
val state = PushHub.diagnostics()

Reset attempts server deactivation, then always erases local credentials and queued operations. Diagnostics exposes only configured status, public installation ID, SDK version, queue count, and consent—not secrets, tokens, identity, content, or event properties.

See compatibility.json on GitHub and the sample.