Documentation

01 / Connect your app

Create an application

Sign in with Google or a verified email address and password. Open Applications, create an application and select Android. You can also save iOS and Web settings for later.

Copy the App ID from the application settings. It is a PushPort identifier, not a Firebase project ID or your Android package name.

Before you begin

• An Android application on API 23 or later.
• A test device with Google Play services and network access.
• Access to the Firebase project used by that application.

02 / Connect your app

Connect Firebase

Open the Firebase console for your application. Under Project settings → Service accounts, generate a private JSON key. Upload it to the Android settings of the corresponding PushPort application.

The private key belongs on the server. Do not add it to the Android project. With this PushPort integration, the host app does not need google-services.json or the Google Services Gradle plugin; its own independent Firebase integration can remain.

• Use credentials from the correct Firebase project.
• If you set a package restriction, it must match the Android applicationId.
• Firebase Analytics is not required for PushPort locale data.

03 / Connect your app

Install the Android SDK

SDK 0.3.0 is currently distributed as a Maven repository build, not through Maven Central. Ask support for the build and add its repository path to your Gradle settings. A raw AAR alone does not carry transitive dependencies.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("/path/to/pushport-maven-repository")
            content { includeGroup("dev.pushport") }
        }
    }
}

dependencies {
    implementation("dev.pushport:android-sdk:0.3.0")
}

Initialize the SDK in your Application class and register that class in AndroidManifest.xml. If your application already has an Application class, initialize it there. In apps with multiple processes, initialize only in the main process.

import android.app.Application
import dev.pushport.sdk.PushPort

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        PushPort.initWithContext(this, "PUSHPORT_APP_ID")
    }
}

<application android:name=".MyApplication" />

PushPort.requestNotificationPermission(this)

• Request notification permission from a visible Activity after explaining its purpose.
• Firebase Messaging, WorkManager and manifest components arrive through the dependency.
• Open the app, grant permission, then check its installation in Audience.

04 / Work with messages

Understand your audience

Audience lists installations. One person with two devices can appear twice. Filters use language, locale, approximate country and subscription state; save useful combinations as segments.

The SDK synchronizes the app locale and system locales, timezone, version and notification state. A locale such as de-DE is different from a language such as de. Country is estimated from the IP and may be unknown.

PushPort.setLocale(context, "de-DE")
PushPort.setLocale(context, null)
PushPort.setSubscribed(context, false)
PushPort.setSubscribed(context, true)
PushPort.sync(context)

• SUBSCRIBED — eligible when the token and permission are available.
• UNSUBSCRIBED / PERMISSION_DENIED — the app or system has disabled notifications.
• AWAITING_TOKEN / INVALID_TOKEN — a usable delivery token is missing.

05 / Work with messages

Send and schedule

Open Campaigns in your application. Save a draft with a title, message and audience. Check the eligible count and test on your own installation before sending to the full audience.

Choose immediate sending or a future date. The time shown uses your browser’s timezone and is stored as UTC. Schedules continue on the server after you close the page.

• Add translations: exact locale → language → default message.
• One-time schedules are available; recurring and recipient-local schedules are not implemented yet.
• Cancellation stops pending work. It cannot recall notifications already passed to FCM.

06 / Work with messages

Images and links

Use a publicly accessible HTTPS URL for an image and, optionally, an HTTPS click destination. With SDK 0.3.0, the text notification appears first; the image is added if downloading succeeds.

Images must be PNG, JPEG or WebP, at most 1 MiB, with each side at most 4096 pixels and at most 8 million pixels in total. URLs that need authentication or point to private networks are unsuitable.

• Keep image hosting available when the campaign is sent.
• Test both the picture and the click destination on a real device.
• If an image fails, the text notification can still be shown.

07 / Check and troubleshoot

Read the results

FCM acceptance means the push provider accepted the request. It does not prove the notification appeared on the device. Opens are counted separately when the SDK reports a tap.

Review the campaign result and installation state together. An invalid token differs from a temporary provider error. An uncertain sending result is not retried blindly because that could create a duplicate.

• Check subscription and system permission before retrying.
• A draft preview and the audience at sending time can differ.
• Compare the timestamp and installation ID when investigating a report.

08 / Check and troubleshoot

Troubleshooting

If an installation is missing, launch the app and check the App ID, backend connectivity and SDK initialization. If it appears but cannot receive notifications, check permission, subscription and token status.

If a message is accepted but not visible, check the device connection, notification settings and the exact target installation. For image-only issues, open the image URL without signing in and check the size and format.

• Missing code email: check spam, confirm the address and wait one minute before requesting another code.
• Firebase error: confirm that the sender credentials belong to the same application project.
• Still stuck? Send the App ID, approximate time and expected result through Contacts.