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.

build.gradle
    ...
    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.

MyApplicationClass.kt
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

CastledConfigs.kt
    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"/>
SDK OverviewPush Notification