Getting Started with Android SDK
Prerequisites
The Castled Android SDK enables mobile applications running on Android devices to receive push and in-app notifications originating from the Castled Customer Engagement Platform. The steps outlined below will assist your Android app developers in integrating the SDK with your mobile application
SDK installation
Gradle
Maven
Applicable if your project uses Gradle for managing dependency. Add castled-notifications
as a dependency in the build.gradle
file of your Android application module.
...
dependencies {
...
implementation 'io.castled.android:castled-notifications:<sdk-latest-version>'
}
Replace latest-version
with the latest version number of the SDK found here. Sync the gradle file to pull the dependencies just added.
SDK initialization
The next step is to initialize the SDK. Initialization is typically done in the onCreate
method of your
Application
class as follows.
class MyApplicationClass : MultiDexApplication() {
override fun onCreate() {
super.onCreate()
// SDK initialization
CastledNotifications.initialize(
this, CastledConfigs.Builder()
.apiKey("<api-key>")
.location(<location>)
.build()
)
...
}
...
}
api-key
is a unique key associated with your Castled account. It can be found in the Castled dashboard at Settings > Api Keys. location
is the region where you have your Castled account.
Currently we offer services in 4 regions
enum class CastledLocation {
US, // United States
EU, // Europe
IN, // India
AP // Asia Pacific
}
User Identification
To identify the user associated with this app instance, use the following method. This is typically invoked immediately after user completes the
sign-in flow of your app. user-id
is the id that you use internally within your organisation to identify a user.
// User identification
CastledNotifications.setUserId(context, "<user-id>")
It is recommended to pass an optional user-token as the third parameter to
setUserId
to mitigate any risk of user impersonation. In the absence of a
user-token, no additional verifications will be done to enforce user
authenticity. If your user-id is random id such as a UUID, user-token
is probably not required. More info on user-token can be found in the next
section.
Secure User Identification
user-token
is a unique token for each user generated by your app server. This token is usually issued by the app server after the user
completes the login flow within your app.
// Secure user identification
CastledNotifications.setUserId(this, "<user-id>", "<user-token>")
user-token
is basically a Base64 encoded Hash-based Message Authentication Code (HMAC). Ensure the hash computation happens in your app server so that api-key
is not exposed. You can create an api-key
in the Setting > API Keys page within your Castled account. Contact Castled support for help with integration.
Find sample server code snippets to generate HMAC for the user-id
.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
public static String calculateHMAC(String userId, String apiKey) throws Exception {
// Get an instance of the HMAC using SHA-256 hashing algorithm
Mac sha256Hmac = Mac.getInstance("HmacSHA256");
// Create a SecretKeySpec using the provided key
SecretKeySpec secretKey = new SecretKeySpec(apiKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
// Initialize the Mac with the secret key
sha256Hmac.init(secretKey);
// Compute the HMAC of the given data
byte[] rawHmac = sha256Hmac.doFinal(userId.getBytes(StandardCharsets.UTF_8));
// Convert the HMAC bytes to a Base64 encoded string
return Base64.getEncoder().encodeToString(rawHmac);
}
SDK Permissions
By default AndroidManifest.xml
of the SDK includes the following permission requests. No developer action is required here.
<!-- Castled SDK needs this permission to sync user token and campaign events -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- Castled SDK will use this permission to decide when to make network calls -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>