Skip to main content

Android Quickstart

This guide walks you through integrating PushEngage push notifications into a native Android application (Java or Kotlin). Estimated time: 15 minutes.

After completing this guide, your app will receive push notifications. See the Android SDK Reference for the full API.

Prerequisites​

  • Android Studio installed
  • Android project with minSdkVersion 16 (Android 4.1) or higher; API 21+ recommended
  • Firebase account (create one free)
  • PushEngage account and App ID (see Get Your App ID)

Step 1 — Installation​

Configure the Repository​

If your project uses a settings.gradle file (centralized dependency resolution):

settings.gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

If your project uses a project-level build.gradle:

build.gradle (project level)
buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath "com.google.gms:google-services:4.4.2"
    }
}

allprojects {
    repositories {
        google()
        maven { url 'https://jitpack.io' }
    }
}

Add the SDK Dependency​

build.gradle (app level)
plugins {
    id 'com.android.application'
    id 'com.google.gms.google-services'
}

dependencies {
    implementation 'com.github.awesomemotive:pushengage-android-sdk:0.0.6'
    implementation platform('com.google.firebase:firebase-bom:33.5.1')
}

Step 2 — Firebase Setup​

PushEngage uses Firebase Cloud Messaging (FCM) to deliver push notifications to Android devices.

Create a Firebase Project​

  1. Open the Firebase console and sign in.
  2. Click Add Project (or select an existing one) and complete the setup wizard.

Add Your Android App​

  1. In the Firebase project dashboard, click the Android icon.
  2. Enter your app's package name (found in android/app/build.gradle under applicationId).
  3. Click Register app.
  4. Download google-services.json and place it at android/app/google-services.json.

Generate Service Account JSON​

  1. Firebase console → Settings icon → Project settings → Service accounts tab.
  2. Click Generate new private key and save the downloaded JSON file securely.

Retrieve Your Sender ID​

  1. Firebase console → Settings icon → Project settings → Cloud Messaging tab.
  2. Copy the Sender ID.

Step 3 — Connect to PushEngage Dashboard​

  1. Log in to your PushEngage Dashboard.
  2. Navigate to Site Settings → Installation → Android SDK tab.
  3. Enter your Firebase Sender ID.
  4. Upload your Service Account JSON file.
  5. Click Update and copy the App ID shown on the page.

Step 4 — Initialize the SDK​

If your application does not have a custom Application class, create one:

PEApplication.kt
import android.app.Application
import com.pushengage.pushengage.PushEngage

class PEApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val pushEngage = PushEngage.Builder()
            .addContext(applicationContext)
            .setAppId("YOUR_APP_ID")
            .build()
        // Recommended: set a branded small icon instead of the default bell
        PushEngage.setSmallIconResource("your_icon_name")
    }
}

Register the custom Application class in AndroidManifest.xml:

AndroidManifest.xml
<application
    android:name=".PEApplication"
    ...>
note

Replace YOUR_APP_ID with the App ID from Step 3. The setSmallIconResource name must match a drawable resource in your res/drawable/ directory. If omitted or invalid, a default bell icon is used.

Step 5 — Request Notification Permission​

On Android 13 (API 33) and above, you must request notification permission explicitly. Call this from your main Activity — which must extend ComponentActivity (e.g., AppCompatActivity, FragmentActivity, or androidx.activity.ComponentActivity directly). If your Activity extends plain android.app.Activity, switch its base class first.

MainActivity.kt
PushEngage.requestNotificationPermission(this, object : PushEngagePermissionCallback {
    override fun onPermissionResult(granted: Boolean, error: Error?) {
        if (granted) {
            // The SDK automatically subscribes the user when permission is granted
            Log.d("PushEngage", "Permission granted and user subscribed")
        } else {
            Log.d("PushEngage", "Permission denied: ${error?.message}")
        }
    }
})
note

On Android 12 (API 32) and below, notification permission is automatically granted. The callback fires immediately with granted = true.

Step 6 — Send a Test Notification​

  1. Build and run your app on a physical Android device — push notifications do not work in the emulator.
  2. Grant notification permission when prompted.
  3. In the PushEngage Dashboard, go to Campaign → Push Broadcasts → Create New Push Broadcast and send a test.

You should receive the notification within a few seconds. Your integration is complete.

Troubleshooting​

Build error: "google-services plugin not applied" Ensure id 'com.google.gms.google-services' is in the plugins block of your app-level build.gradle, applied after com.android.application.

Notification permission denied — no second prompt On Android 13+, after denial the system blocks subsequent requestNotificationPermission calls. The only path back is Settings → Apps → <App> → Notifications. Surface a one-tap deep link to Settings.ACTION_APP_NOTIFICATION_SETTINGS in your UI.

Notifications not received on device

  • Confirm google-services.json is at android/app/google-services.json (not the project root).
  • Confirm the Sender ID and Service Account JSON in the PushEngage Dashboard match your Firebase project.
  • Test on a physical device, not an emulator (FCM requires Google Play Services).
  • Enable verbose logging: PushEngage.enableLogging(true) — watch for the FCM token registration log line.

Notifications work for a while, then stop Some Android device manufacturers aggressively restrict background services for apps the user has force-stopped. Ask affected users to disable battery optimization for your app: Settings → Battery → Battery Optimization → Don't optimize.

Custom small icon not appearing If setSmallIconResource("name") references a drawable that doesn't resolve, the SDK silently uses a default bell icon. Verify the drawable exists at res/drawable/name.xml (or .png).

Next Steps​

Last updated on