How Do I Set Up Push Notifications in the Android SDK (v3)?

Gameball supports Firebase Cloud Messaging (FCM) and Huawei Push Kit, enabling you to deliver timely updates about rewards, achievements, and promotional messages to customers. Push notifications help drive engagement by notifying users when they earn points, complete challenges, or receive new rewards.

Firebase Cloud Messaging (FCM)

1. Setup

Follow these steps to enable FCM:

Add Firebase to your project following the official guide: https://firebase.google.com/docs/android/setup
Add FCM dependencies to your app:

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

Add your Firebase credentials in the Gameball Dashboard → Admin Settings → Push Notifications.

2. Retrieve Device Token

Use the Firebase Messaging API to obtain the device token and pass it to Gameball during customer initialization.

FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val token = task.result

        val customerRequest = InitializeCustomerRequest.builder()
            .customerId("customer-123")
            .deviceToken(token)
            .pushProvider(PushProvider.Firebase)
            .build()

        GameballApp.getInstance(context).initializeCustomer(
            customerRequest,
            callback
        )

        // With session token override
        GameballApp.getInstance(context).initializeCustomer(
            customerRequest,
            callback,
            sessionToken = "customer-token"
        )
    }
}

A push provider (Firebase) must always be set if you pass a deviceToken.

3. Handle Incoming Notifications

Implement a custom FirebaseMessagingService to handle notifications sent from Gameball.

class MyFirebaseMessagingService : FirebaseMessagingService() {

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)

        if (remoteMessage.data["source"] == "gameball") {
            val title = remoteMessage.notification?.title
            val body = remoteMessage.notification?.body

            showNotification(title, body)
        }
    }

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        // Re-register the token with Gameball
        val customerRequest = InitializeCustomerRequest.builder()
            .customerId("customer-123")
            .deviceToken(token)
            .pushProvider(PushProvider.Firebase)
            .build()

        GameballApp.getInstance(applicationContext).initializeCustomer(
            customerRequest,
            object : Callback<InitializeCustomerResponse> {
                override fun onSuccess(response: InitializeCustomerResponse) {}
                override fun onError(error: Throwable) {}
            }
        )
    }
}

Register the service

<service
    android:name=".MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Huawei Push Kit (HMS)

For Huawei devices without Google Play Services, use Huawei Push Kit.

1. Setup

Configure Huawei Push Kit in AppGallery Connect
Add Push Kit dependency:

dependencies {
    implementation 'com.huawei.hms:push:6.7.0.300'
}

Add Huawei repository:

repositories {
    maven { url 'https://developer.huawei.com/repo/' }
}

2. Retrieve Device Token

object : HmsMessageService() {
    override fun onNewToken(token: String) {
        val customerRequest = InitializeCustomerRequest.builder()
            .customerId("customer-123")
            .deviceToken(token)
            .pushProvider(PushProvider.Huawei)
            .build()

        GameballApp.getInstance(applicationContext).initializeCustomer(
            customerRequest,
            object : Callback<InitializeCustomerResponse> {
                override fun onSuccess(response: InitializeCustomerResponse) {}
                override fun onError(error: Throwable) {}
            }
        )
    }
}

For full Huawei setup instructions, refer to:• AppGallery Connect Configuration:
https://developer.huawei.com/consumer/en/doc/hmscore-guides/android-config-agc-0000001050170137• Push Kit Codelab: https://developer.huawei.com/consumer/en/codelab/HMSPushKit/index.html#0

In-App Messaging

Gameball supports several types of in-app engagement:

Profile widget pop-ups
Native in-app notifications
Custom in-app messaging templates

All configurations, message templates, rules, and segmentation are controlled directly from the Gameball Dashboard.

Best Practices

Request Permissions Thoughtfully

Request notification permission at a meaningful point in the user’s journey, rather than immediately upon app launch.

Handle Token Refresh

Always update the device token when it changes (onNewToken) by calling initializeCustomer with the new token and matching pushProvider.

Test on Real Devices

Verify push delivery on different Android versions and manufacturers.

Send Useful Notifications

Keep notifications relevant and valuable to avoid opt-outs.

Overview

Web & POS Integration

Mobile Integration

How Do I Set Up Push Notifications in the Android SDK (v3)?

Firebase Cloud Messaging (FCM)

1. Setup

2. Retrieve Device Token

3. Handle Incoming Notifications

Register the service

Huawei Push Kit (HMS)

1. Setup

2. Retrieve Device Token

In-App Messaging

Best Practices

​Firebase Cloud Messaging (FCM)

​1. Setup

​2. Retrieve Device Token

​3. Handle Incoming Notifications

​Register the service

​Huawei Push Kit (HMS)

​1. Setup

​2. Retrieve Device Token

​In-App Messaging

​Best Practices

Firebase Cloud Messaging (FCM)

1. Setup

2. Retrieve Device Token

3. Handle Incoming Notifications

Register the service

Huawei Push Kit (HMS)

1. Setup

2. Retrieve Device Token

In-App Messaging

Best Practices