Quick Start

This guide demonstrates how to quickly integrate Altcraft mSDK with Firebase Cloud Messaging (FCM). After completing the steps below, your app will be able to receive Altcraft push notifications.

To use Huawei Mobile Services (HMS) or RuStore, add their corresponding SDKs to your project and implement their interfaces using the same approach as for Firebase.

Step 0. Prerequisites

• Push provider SDKs are integrated into your app project (see the corresponding integration guides);
• The app includes a class extending Application();
• All required entities (resource, mailing, template, profile database) are pre-created in the Altcraft platform;
• On Android 13 (Tiramisu) and later, explicit user permission is required to send push notifications.

Step 1. Connect Altcraft mSDK to the app

Add the library dependency to your app-level build.gradle.kts file:

dependencies {
        implementation("com.altcraft:android-sdk:1.0.3")
}

Then sync your Gradle project.

Step 2. Implementing JWTInterface

Implement the SDK interface that provides the JWT token. Create a class in your app module that implements JWTInterface and override the getJWT() function:

import com.altcraft.sdk.interfaces.JWTInterface

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

Note

• getJWT() is a synchronous function. The SDK execution thread will be blocked until the JWT is obtained.
• It’s recommended that getJWT() return the token immediately from cache (in-memory, SharedPreferences, or EncryptedSharedPreferences) to speed up requests.
• Ideally, prepare and cache the JWT as early as possible (e.g., during app startup) so that the SDK can access it instantly. Returning null is acceptable if no token is available.

Example implementation using a suspend function

import android.content.Context
import com.altcraft.sdk.interfaces.JWTInterface
import kotlinx.coroutines.runBlocking

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

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

Step 3. Registering the JWT provider

Register the JWT provider in Application.onCreate():

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

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

Step 4. Implementing the FCM interface

Create a class in your app module that implements FCMInterface:

Example implementation

import com.altcraft.sdk.interfaces.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 retrieval fails. */
    override suspend fun getToken(): String? {
        return try {
            Firebase.messaging.token.await()
        } catch (e: Exception) {
            null
        }
    }

    /** Deletes the current FCM token. */
    override suspend fun deleteToken(completion: (Boolean) -> Unit) {
        try {
            FirebaseMessaging.getInstance().deleteToken().addOnCompleteListener {
                completion(it.isSuccessful)
            }
        } catch (e: Exception) {
            completion(false)
        }
    }
}

Step 5. Creating a service extending FirebaseMessagingService()

In your app module, create a class that extends FirebaseMessagingService and override onMessageReceived() to pass push data to the SDK via AltcraftSDK.PushReceiver.takePush():

Example service implementation

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

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

    override fun onNewToken(token: String) {
        super.onNewToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)
        AltcraftSDK.PushReceiver.takePush(this@FCMService, message.data)
    }
}

Step 6. Registering the FCM service in AndroidManifest

Register your FirebaseMessagingService in the app’s AndroidManifest.xml:

<!-- 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()

Register the Firebase Cloud Messaging provider in Application.onCreate():

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

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

Step 8. Initializing the SDK

In Application.onCreate(), create a configuration object and initialize the SDK using initialization(). Make sure to call initialization() after all providers (JWT and push token providers) are registered.

Initialization details

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

Example initialization:

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

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

        val config = AltcraftConfiguration.Builder(
            apiUrl = "https://pxl-your-instance.altcraft.com",
            icon = R.drawable.your_icon
        ).build()
        
        // set additional configuration parameters (see Android mSDK README)

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

Step 9. Subscribing to push notifications

Use the pushSubscribe() function to subscribe to push notifications at any point in your code — for example, after obtaining user permission for notifications:

AltcraftSDK
└──  val pushSubscriptionFunctions: PublicPushSubscriptionFunctions
    // Push notifications subscription (status = SUBSCRIBED)
    ├─ fun pushSubscribe(
         context: Context,
         sync: Boolean = true,
         profileFields: Map<String, Any?>? = null,
         customFields: Map<String, Any?>? = null,
         cats: List<DataClasses.CategoryData>? = null,
         replace: Boolean? = null,
         skipTriggers: Boolean? = null
       ): Unit

Example subscription call:

class MainActivity : ComponentActivity() {

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

        NotificationPermissionHandler.isGranted(
            activity = this,
            onGranted = {
                if (isUnsubscribed()) {
                   AltcraftSDK.pushSubscriptionFunctions.pushSubscribe(context = this)
                }
            }
        )
    }
}