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)
Let an AI agent do the integration for you

Every step on this page can be handled by an AI coding agent. Install the official PushEngage Agent Skills in Claude Code, Cursor, or another compatible agent:

npx skills add awesomemotive/pushengage-skills

Then ask it to "integrate PushEngage into this app". The skills walk the agent through the full setup and can also diagnose a broken integration.

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.1.0'
    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