Quick start

This article provides an example of quickly integrating Altcraft mSDK with Firebase Cloud Messaging (FCM). After performing the steps described, your app will be able to receive Altcraft push notifications.

To use Huawei Mobile Services or RuStore, you need to add the corresponding SDKs to the project and implement their interfaces using the same approach shown for Firebase.

Step 0. Prerequisites

The push provider SDKs are integrated into the app project (see the push provider integration instructions);
A class extending Application() has been added to the app;
All required entities (resource, mailing, template, profile base) have been created in Altcraft Platform in advance;
Sending push notifications on devices with Android 13 (Tiramisu) requires explicit user permission.

Step 1. Connecting Altcraft mSDK to the app

mSDK is split into modules. A module is activated by adding its dependency — no separate registration is required: each module registers automatically at app startup.

The push scenario requires two modules:

android-sdk-core — the base module (initialization, authentication, retries);
android-sdk-push — push notifications.

Add the dependencies to the app-level build.gradle.kts file (app level):

    dependencies {
        implementation("com.altcraft:android-sdk-core:X.Y.Z")
        implementation("com.altcraft:android-sdk-push:X.Y.Z")
    }

Run a synchronization of the Gradle changes.

Step 2. Implementing JWTInterface

Implement the SDK interface designed to provide a JWT token.

In the app module, create a class that implements JWTInterface and override getJWT():

import com.altcraft.sdk.platform.authenticate.external.jwt.JWTInterface

class JWTProvider(private val context: Context /** add the context property if necessary */) : JWTInterface {
    override fun getJWT(): String?{
      // your code that returns the current JWT token
    }
}

Note

getJWT() is a synchronous function. The SDK execution flow will be suspended until the JWT is received;
It is recommended that getJWT() return a value immediately from a cache (in-memory, SharedPreferences, or EncryptedSharedPreferences). This will speed up request execution;
It is advisable to prepare the current JWT as early as possible, for example at app startup, and store it in a cache so that when the SDK accesses it, the token is available without delays. If no value is available, it is permissible to return null.

Implementation example using a suspend function to fetch the token

import android.content.Context
import com.altcraft.sdk.platform.authenticate.external.jwt.JWTInterface
import kotlinx.coroutines.runBlocking

class JWTProvider(private val context: Context /** add the context property if necessary */) : JWTInterface {
    private suspend fun fetchJwt(context: Context): String? {
        // your code that returns the current JWT token
        return jwt
    }

    override fun getJWT(): String? = runBlocking {
        fetchJwt(context)
    }
}

Step 3. Registering the JWT provider

import android.app.Application
import com.altcraft.sdk.AltcraftSDK

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.auth.setJWTProvider(JWTProvider(/** add the context property if necessary */))
    }
}

Step 4. Implementing the FCM interface

In the app module, create a class that implements FCMInterface:

Implementation example

import com.altcraft.sdk.push.platform.token.provider.FCMInterface
import com.google.firebase.Firebase
import com.google.firebase.messaging.FirebaseMessaging
import com.google.firebase.messaging.messaging
import kotlinx.coroutines.tasks.await

/**
 * FCM implementation for managing Firebase Cloud Messaging tokens.
 *
 * Provides methods to retrieve and delete FCM tokens via the Firebase SDK.
 */
class FCMProvider : FCMInterface {

    /**
     * Retrieves the current FCM token.
     *
     * Returns `null` if an error occurs during retrieval.
     *
     * @return The FCM token or `null` on failure.
     */
    override suspend fun getToken(): String? {
        return try {
            Firebase.messaging.token.await()
        } catch (e: Exception) {
            null
        }
    }

    /**
     * Deletes the current FCM token.
     *
     * Invokes [completion] with `true` if successful, `false` otherwise.
     *
     * @param completion Callback with the result of the deletion.
     */
    override fun deleteToken(completion: (Boolean) -> Unit) {
        try {
            FirebaseMessaging.getInstance().deleteToken().addOnCompleteListener {
                completion(it.isSuccessful)
            }
        } catch (e: Exception) {
            completion(false)
        }
    }
}

Step 5. Creating a service that extends `FirebaseMessagingService()`

In the app module, create a class that extends FirebaseMessagingService and implement its onMessageReceived() method with a call to AltcraftSDK.push.receiver.takePush() to pass the push notification data to the SDK:

Example of creating the service

import com.altcraft.sdk.AltcraftSDK
import com.altcraft.sdk.push.push
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

/**
 * FCM service for handling push tokens and messages.
 */
class FCMService : FirebaseMessagingService() {

    /**
     * Called when a new FCM token is generated.
     *
     * @param token The new FCM token.
     */
    override fun onNewToken(token: String) {
        super.onNewToken(token)
    }

    /**
     * Called when a push message is received.
     *
     * Forwards the message to all receivers with additional metadata.
     *
     * @param message The received [RemoteMessage].
     */
    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)

        if (AltcraftSDK.push.receiver.isAltcraftPush(message.data)) {
            AltcraftSDK.push.receiver.takePush(this@FCMService, message.data)
        }
    }
}

Step 6. Registering the FCM service in the app manifest

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

Step 7. Registering the FCM provider in `Application.onCreate()`

import android.app.Application
import <your_package_name>.FCMProvider
import com.altcraft.sdk.AltcraftSDK
import com.altcraft.sdk.push.push

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.push.token.setFCMTokenProvider(FCMProvider())
    }
}

Step 7.5. Requesting notification permission

On devices with Android 13+, you must request the user's permission to send notifications before subscribing. Use AltcraftSDK.push.requestNotificationPermission():

AltcraftSDK.push.requestNotificationPermission(context = this, activity = this)

Step 8. SDK initialization

In Application.onCreate(), create a configuration variable and perform initialization using the initialization() function.

Note that the initialization() function must be run after registering all the providers in use (both the JWT provider and the push token providers).

More about initialization

AltcraftSDK
 // SDK initialization and configuration setup
   └── fun initialization(context: Context, configuration: AltcraftConfiguration, complete: ((Result<Unit>) -> Unit)? = null): Unit

fun initialization(context: Context, configuration: AltcraftConfiguration, complete: ((Result<Unit>) -> Unit)? = null): Unit

AltcraftConfiguration.Builder configuration parameters:

Parameter	Type	Description
`apiUrl`	`String`	URL of your Altcraft instance
`rToken`	`String? = null`	Role token (rToken), if the SDK works via rToken
`appInfo`	`AppInfo? = null`	App data: `appID`, `appIID`, `appVer`
`enableLogging`	`Boolean? = null`	Enables the SDK's internal logging

The push module configuration is added by calling pushConfig():

`PushConfiguration` parameter	Type	Description
`icon`	`Int?`	Icon resource for push notifications
`providerPriority`	`List<String>`	Order of push providers by priority
`pushReceiverModules`	`List<String>`	Package prefixes containing the `PushReceiver` implementations
`pushChannelName`	`String?`	Name of the push notification channel
`pushChannelDescription`	`String?`	Description of the push notification channel

Initialization example:

import android.app.Application
import <your_package_name>.FCMProvider
import com.altcraft.sdk.AltcraftSDK
import com.altcraft.sdk.config.AltcraftConfiguration
import com.altcraft.sdk.push.config.PushConfiguration
import com.altcraft.sdk.push.config.pushConfig
import com.altcraft.sdk.push.push

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.auth.setJWTProvider(JWTProvider(applicationContext))
        AltcraftSDK.push.token.setFCMTokenProvider(FCMProvider())

        val config = AltcraftConfiguration.Builder(
            apiUrl = "https://pxl-your-instance.altcraft.com",
            enableLogging = true
        )
            .pushConfig(
                PushConfiguration(
                    icon = R.drawable.your_icon
                )
            )
            .build()

        AltcraftSDK.initialization(context = this, configuration = config)
    }
}

Step 9. Subscribing to push notifications

Use the subscribe() function to subscribe to push notifications anywhere convenient in your code, for example, after the permission to send notifications has been granted:

AltcraftSDK
└──  val push: Push
    └── val subscription: SubscriptionAPI
        // Subscribe to push notifications (status = SUBSCRIBED)
        ├─ fun subscribe(
              context: Context,
              sync: Boolean = true,
              profileFields: Map<String, Any?>? = null,
              customFields: Map<String, Any?>? = null,
              cats: List<CategoryData>? = null,
              replace: Boolean? = null,
              skipTriggers: Boolean? = null
            ): Unit

Subscription example:

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        AltcraftSDK.push.requestNotificationPermission(context = this, activity = this)

        NotificationPermissionHandler.isGranted(
            activity = this,
            onGranted = {
                if(isUnsubscribed()){
                    AltcraftSDK.push.subscription.subscribe(context = this)
                }
            }
        )
    }
}

Step 0. Prerequisites​

Step 1. Connecting Altcraft mSDK to the app​

Step 2. Implementing JWTInterface​

Step 3. Registering the JWT provider​

Step 4. Implementing the FCM interface​

Step 5. Creating a service that extends FirebaseMessagingService()​

Step 6. Registering the FCM service in the app manifest​

Step 7. Registering the FCM provider in Application.onCreate()​

Step 7.5. Requesting notification permission​

Step 8. SDK initialization​

Step 9. Subscribing to push notifications​