Android Quick Start Guide

Castled uses Google Firebase Cloud Messaging(FCM) to send push and in-app messages to your Android mobile application. The following steps will walk you through the process of setting up your application to receive push or in-app notification from Castled. They are mainly intended for your android app developers.

​

Setting up FCM configs

• Make sure you have added Firebase to your Android project. Follow Firebase doc for more details. Within the doc the recommended approach is to follow the steps in option 1
• We need to get the FCM Sender ID and FCM Server Key from Firebase console which will be required for configuring the Android app in Castled.

1. After logging into Firebase console, navigate to project settings page for your project and select cloud messaging tab. Add a new server key if not already done.

2. Also make sure that the Cloud messaging API is enabled. If not click on the Manage API in Google Cloud Console button to enable it.

3. Once the above step is complete navigate to settings > channels > mobile push in Castled webapp. Select Android tab. Specify an App Name to identify your app configuration and enter the FCM Sender ID and FCM Server Key you got from Firebase console in the previous step.

4. When you save your config, you will get an instance-id which will be used in the library initialization step.

​

Library installation

​

Gradle

Add Castled module as a dependency in the build.gradle file for your Android application module

...
dependencies {
    ...
    implementation 'io.castled:notifications:x.y.z'
}

where x.y.z is the latest version of the library published in MavenCentral

​

Maven

Add the following snippet in your pom.xml file as a child of dependencies

<dependency>
  <groupId>io.castled</groupId>
  <artifactId>notifications</artifactId>
  <version>x.y.x</version>
</dependency>

Replace x.y.z with the latest version of the library.

​

Registering for notifications

The next step is to initialize the Castled sdk. Add the following code to your Application class. instance-id is the one obtained when Android FCM configs were saved in Castled webapp.

public class MyTestApplication extends Application {

  @Override
  public void onCreate() {
      super.onCreate();

      ...
      CastledNotifications.initialize(this, "instance-id");
      ...
  }
}

To let Castled know the user associated with this app instance, use the following method. This is typically invoked immediately after user completes the sign-in flow in your app. The user-id passed to Castled is the one that you use internally within your organisation to identify a user.

CastledNotifications.setUserId("user-zdc1234");

setUserId can optionally take in a security token which is fetched from your app server. This is the recommended approach to avoid any risks of user impersonation.

​

Notification default configs

SDK provides option to specify default values for some of the push notification payload fields. You need to create a castled.xml file in the res/values folder of your app project.

​

Notification channels

Add the following values to castled.xml if you want to specify a default channel for notifications from Castled. More details on android notifications channels can be found here.

<string name="io_castled_push_default_channel_id">YOUR_NOTIFICATION_CHANNEL_ID</string>
<string name="io_castled_push_default_channel_name">YOUR_NOTIFICATION_CHANNEL_NAME</string>
<string name="io_castled_push_default_channel_desc">YOUR_NOTIFICATION_CHANNEL_DESC</string>

​

Firebase push messaging handling service

By default push token registration and notification receiving are handled by SDK. In case if you are handling com.google.firebase.MESSAGING_EVENT using your own service add the following code snippets to your service class (derived from FirebaseMessagingService)

​

Register for push tokens

public void onNewToken(@NonNull String token) {
    super.onNewToken(token);
    ...
    ...
    CastledNotifications.setToken(token);
}

​

Handling notifictions

public void onMessageReceived(RemoteMessage remoteMessage) {

    // This check will ensure any notification from castled is handled by SDK
    if (!CastledNotificationManager.handleNotification(this, remoteMessage)) {

        // Notification not from castled. Handle the notification here

    }
}