Push Messaging

🚧
Important
Please ensure that you have completed all the platform integration steps listed under Getting started before proceeding.

Push Notifications are messages that pop up on mobile devices. App publishers can send them at any time; even if the recipients aren’t currently engaging with the app or using their devices.
You can start sending Push Notifications to your Android users via WebEngage by configuring Firebase Cloud Messaging (FCM).

Here's how you can go about it:

1. Add Firebase to Your Project

Please follow these instructions for adding Firebase to Your Android Project.

2. Add Firebase Cloud Messaging Dependency

Add the dependency for Firebase Cloud Messaging in your module’s build.gradle.

dependencies {
  implementation 'com.google.firebase:firebase-messaging:22.0.0'
}

3. Pass Firebase Token to WebEngage

Firebase tokens can be passed to WebEngage using FirebaseMessagingService

import com.google.firebase.messaging.FirebaseMessagingService;
import com.webengage.sdk.android.WebEngage;

public class MyFirebaseMessagingService extends FirebaseMessagingService {
    @Override
    public void onNewToken(String s) {
        super.onNewToken(s);
        WebEngage.get().setRegistrationID(s);
    }
}

import com.google.firebase.messaging.FirebaseMessagingService;
import com.webengage.sdk.android.WebEngage;

class MyFirebaseMessagingService : FirebaseMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        val data = remoteMessage.data
        if (data != null) {
            if (data.containsKey("source") && "webengage" == data["source"]) {
                WebEngage.get().receive(data)
            }
        }
    }
}

🚧
Mandatory Step
It is also mandatory that you pass Firebase token to WebEngage from onCreate of your Application class as shown below. This will ensure that changes in user’s Firebase token are communicated to WebEngage.

import com.webengage.sdk.android.WebEngage;
import com.google.android.gms.tasks.OnCompleteListener;
import com.google.android.gms.tasks.Task;
import com.google.firebase.messaging.FirebaseMessaging;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
    
       FirebaseMessaging.getInstance().getToken().addOnCompleteListener(new OnCompleteListener<String>() {
                @Override
                public void onComplete(@NonNull Task<String> task) {
                    try {
                        String token = task.getResult();
                        WebEngage.get().setRegistrationID(token);
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
            });
    }
}

import com.webengage.sdk.android.WebEngage;
import com.google.android.gms.tasks.OnCompleteListener;
import com.google.android.gms.tasks.Task;
import com.google.firebase.messaging.FirebaseMessaging;

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
            try {
                val token: String? = task.result
                WebEngage.get().setRegistrationID(token)
            } catch (e: Exception) {
                e.printStackTrace()
            }
        }
    }
}

4. Pass Messages to WebEngage

Create a class that extends FirebaseMessagingService and pass messages to WebEngage.
All incoming messages from WebEngage will contain key source with the value as webengage.

package your.application.package;

import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import com.webengage.sdk.android.WebEngage;

public class MyFirebaseMessagingService extends FirebaseMessagingService {
  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
    Map<String, String> data = remoteMessage.getData();
    if(data != null) {
      if(data.containsKey("source") && "webengage".equals(data.get("source"))) {
        WebEngage.get().receive(data);
      }
    }
  }
}

package your.application.package;

import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import com.webengage.sdk.android.WebEngage;

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        Map<String, String> data = remoteMessage.getData();
        if (data != null) {
            if (data.containsKey("source") && "webengage".equals(data.get("source"))) {
               WebEngage.get().receive(data);
            }
        }
    }
}

🚧
Note
If you want to do customization on push, kindly follow the doc.

Next, register the service to the application element of your AndroidManifest.xml as follows.

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

5. Add Your Firebase Credentials to WebEngage

Step 1: Log in to the Firebase Developers Console.

Step 2: Select your Firebase project.

Step 3: Navigate to Project Settings > Cloud Messaging and copy your server key as shown in the image below.

For existing projects, cloud messaging API is enabled by default.

For newly created projects, cloud messaging API (Legacy) support is disabled by default

To enable the support follow the steps below:

Under "Cloud Messaging API (Legacy)" click on the options (three dots on the right) and click "Manage API in Google Cloud Console".

You will be redirected to Cloud Messaging API page, where you can enable the API support.

Post enabling, refresh your Firebase Console page, and now you can see that the Cloud Messaging API (Legacy) has been enabled and Server Key is visible.

Step 4: Log in to your WebEngage dashboard and navigate to Data Platform > Integrations > Push Setup (Configure).

Paste the copied server key under the field labeled GCM/FCM Server Key under the Android tab.
Enter your application package name under the field labeled Package Name and click Save.

Making your app compatible with Android 13 push changes

From Android 13 onwards, clients will have to explicitly ask permissions from end user to send push notifications. This means, client will NOT recieve push opted in as true once the app is installed by the end user, unless the user explicitly subscribes for same.

To make sure your app is compatible with Android 13 changes, kindly follow these steps:

Step 1. Kindly refer to official Google documentation to make your application compatible with the same.

Step 2. On the basis of the permission provided by the user, pass the status to WebEngage by following the code snippet below:

WebEngage.get().user().setDevicePushOptIn(true);

WebEngage.get().user().setDevicePushOptIn(true)

🚧
Please Note

Pass the boolean value "true" or "false" depending on the permission the user has specified. If users refuse the permission, they will not receive push alerts.

Push permission Prompt trigger to be managed by the App.

Hybrid SDKs (React, Cordova, Flutter, etc.)

Refer these React, Cordova and Flutter documents to make your app compatible with Android 13 push notification related changes.

Additional Step: Customizing Icon & Accent Colors

(Applicable only to Android SDK v1.14.0 & above)

By default, the WebEngage Android SDK uses your application's icon to set the small and large icons of your push messages. You can provide custom icons during SDK initialization, as shown below.

import com.webengage.sdk.android.WebEngageConfig;
import com.webengage.sdk.android.WebEngageActivityLifeCycleCallbacks;

...
...

WebEngageConfig webEngageConfig = new WebEngageConfig.Builder()
	.setPushSmallIcon(R.drawable.YOUR_SMALL_ICON)
	.setPushLargeIcon(R.drawable.YOUR_LARGE_ICON)
	.setPushAccentColor(Color.parseColor("#ff0000"))
	.build();
registerActivityLifecycleCallbacks(new WebEngageActivityLifeCycleCallbacks(this, webEngageConfig));

import com.webengage.sdk.android.WebEngageConfig;
import com.webengage.sdk.android.WebEngageActivityLifeCycleCallbacks;

...
...

val webEngageConfig = WebEngageConfig.Builder()
            .setPushSmallIcon(R.drawable.YOUR_SMALL_ICON)
            .setPushLargeIcon(R.drawable.YOUR_LARGE_ICON)
            .setPushAccentColor(Color.parseColor("#ff0000"))
            .build()
        registerActivityLifecycleCallbacks(
            WebEngageActivityLifeCycleCallbacks(
                this,
                webEngageConfig
            )
        )

Notification Icon Fix for Android Lollipop & Above

Since the release of Lollipop (API 21), the material design style dictates that all non-alpha channels in notification icons be ignored. Therefore, the small icon will be rendered as solid white if it's not transparent. Hence, if you have provided a custom icon during SDK initialization, then you need to make sure that it is transparent.

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!