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.
- 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.
- 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.
- 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.
- 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
}
}