Public SDK API

object AltcraftSDK

AltcraftSDK
// SDK initialization and configuration setup
├─ fun initialization(context: Context, configuration: AltcraftConfiguration, complete: ((Result<Unit>) -> Unit)? = null): Unit
// Full cleanup of SDK data (DB, SP, background tasks)
├─ fun clear(context: Context, onComplete: (() -> Unit)? = null): Unit
// Register a JWT provider
├─ fun setJWTProvider(provider: JWTInterface?): Unit
// Allow push-module reinitialization in the current session
├─ fun unlockInitialOperationsInThisSession(): Unit
// Request notification permission (Android 13+)
├─ fun requestNotificationPermission(context: Context, activity: ComponentActivity): Unit
// Base Altcraft push receiver (can be overridden)
├─ open class PushReceiver
│  // Handle incoming push message
│  ├─ open suspend fun pushHandler(context: Context, message: Map<String, String>): Unit
│  // Entry point for delivering push messages to the SDK
│  └─ companion object
│     ├─ fun takePush(context: Context, message: Map<String, String>): Unit
│     └─ fun isAltcraftPush(message: Map<String, String>): Boolean
// Public subscription functions
├─ val pushSubscriptionFunctions: PublicPushSubscriptionFunctions
│  // Subscribe to push notifications (status = SUBSCRIBED)
│  ├─ fun pushSubscribe(
│  │     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
│  // Suspend push notifications (status = SUSPENDED)
│  ├─ fun pushSuspend(
│  │     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
│  // Unsubscribe from push notifications (status = UNSUBSCRIBED)
│  ├─ fun pushUnSubscribe(
│  │     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
│  // Change subscription status from suspended to subscribed for the one in JWT; others containing the specified push token switch from subscribed to suspended.
│  ├─ suspend fun unSuspendPushSubscription(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
│  // Status of the latest profile subscription
│  ├─ suspend fun getStatusOfLatestSubscription(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
│  // Status of latest subscription for a specific push provider
│  ├─ suspend fun getStatusOfLatestSubscriptionForProvider(context: Context, provider: String? = null): ResponseWithHttpCode<ResponseWithProfile>?
│  // Status of subscription with current device token.
│  ├─ suspend fun getStatusForCurrentSubscription(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
│  // Functional profile field (set/incr/…)
│  └─ fun actionField(key: String): ActionFieldBuilder
// Token management functions
├─ val pushTokenFunctions: PublicPushTokenFunctions
│  // Manually save provider token (onNewToken)
│  ├─ fun setPushToken(context: Context, provider: String?, token: String?): Unit
│  // Get current device push token
│  ├─ suspend fun getPushToken(context: Context): TokenData?
│  // Register FCM provider
│  ├─ fun setFCMTokenProvider(provider: FCMInterface?): Unit
│  // Register HMS provider
│  ├─ fun setHMSTokenProvider(provider: HMSInterface?): Unit
│  // Register RuStore provider
│  ├─ fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit
│  // Delete provider device token
│  ├─ fun deleteDeviceToken(context: Context, provider: String, complete: () -> Unit): Unit
│  // Forced token update (delete → refresh)
│  ├─ fun forcedTokenUpdate(context: Context, complete: () -> Unit): Unit
│  // Change provider priority list and update token
│  └─ suspend fun changePushProviderPriorityList(context: Context, priorityList: List<String>): Unit
// Push event tracking functions
├─ val pushEventFunctions: PublicPushEventFunctions
│  // Track delivery (delivery event)
│  ├─ fun deliveryEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit
│  // Track open (open event)
│  └─ fun openEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit
//
// Registering mobile events
├─ val mobileEventFunctions: PublicMobileEventFunctions
│  // Registers a mobile event for Altcraft
│  └─ fun mobileEvent(
│        context: Context,
│        sid: String,
│        eventName: String,
│        sendMessageId: String? = null,
│        payload: Map<String, Any?>? = null,
│        matching: Map<String, Any?>? = null,
│        matchingType: String? = null,
│        profileFields: Map<String, Any?>? = null,
│        subscription: Subscription? = null,
│        utm: UTM? = null
│     ): Unit
//
// Profile field update
├─ val profileFunctions: PublicProfileFunctions
│  // Updates profile fields for Altcraft
│  └─ fun updateProfileFields(
│        context: Context,
│        profileFields: Map<String, Any?>? = null,
│        skipTriggers: Boolean? = null
│     ): Unit
//
// Public In-App notification functions
├─ val inAppFunctions: PublicInAppFunctions
│  // Configure In-App notification animation
│  ├─ fun setAnimation(block: Animator.() -> Unit): Unit
│  // Set current screen marker (used for In-App notification filtering)
│  ├─ fun setScreen(screen: String): Unit
│  // Custom In-App notification trigger by name
│  ├─ fun inAppTrigger(context: Context, name: String): Unit
│  // Request available In-App placements
│  ├─ fun getInAppPlacements(context: Context): Unit
│  // Subscribe to Activity lifecycle for automatic In-App display
│  ├─ fun subscribeOnActivityLifecycle(context: Context): Unit
│  // Subscribe to In-App notifications (status = SUBSCRIBED)
│  ├─ fun inAppSubscribe(
│  │     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
│  // Unsubscribe from In-App notifications (status = UNSUBSCRIBED)
│  ├─ fun inAppUnSubscribe(
│  │     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
│  // In-App notification subscription status
│  └─ suspend fun getInAppSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
//
// Public authentication functions
├─ val authFunctions: PublicAuthFunctions
│  // Authenticate user
│  ├─ fun authenticate(context: Context): Unit
│  // Log out user
│  ├─ fun logOut(context: Context): Unit
│  // Check authentication status
│  └─ suspend fun isAuthenticated(context: Context): Boolean
//
// SDK events (single subscriber)
└─ val eventSDKFunctions: Events
   // Subscribe to SDK events
   ├─ fun subscribe(newSubscriber: (Event) -> Unit): Unit
   // Unsubscribe from SDK events
   └─ fun unsubscribe(): Unit

class AltcraftConfiguration

com.altcraft.sdk.config
└─ class AltcraftConfiguration private constructor(...)
   // Altcraft SDK configuration initialization class:
   // API URL, role token, app info, foreground service flag
   // and push notification settings (channel, receiver modules, provider priority).

   ├─ class Builder(
   │     apiUrl: String,                         // Base Altcraft API URL (required)
   │     icon: Int? = null,                      // Notification icon resource ID (optional)
   │     rToken: String? = null,                 // Role token
   │     appInfo: AppInfo? = null,               // Firebase Analytics metadata (optional)
   |     enableLogging: Boolean? = null,         // Enable/disable logging (optional)
   │     providerPriorityList: List<String>? = null, // Push provider priority (optional)
   │     pushReceiverModules: List<String>? = null,  // Package modules where PushReceiver may be overridden (optional)
   │     pushChannelName: String? = null,        // Push notification channel name (optional)
   │     pushChannelDescription: String? = null  // Push notification channel description (optional)
   │   )
   │   └─ fun build(): AltcraftConfiguration     // Build valid configuration
   │
   ├─ fun getApiUrl(): String                    // Returns base Altcraft API URL
   ├─ fun getIcon(): Int?                        // Returns notification icon ID (optional)
   ├─ fun getRToken(): String?                   // Returns role token (optional)
   ├─ fun getAppInfo(): AppInfo?                 // App info (ID/IID/version) (optional)
   ├─ fun getEnableLogging(): Boolean?           // Enable/disable logging (optional)
   ├─ fun getProviderPriorityList(): List<String>? // Push provider priority (optional)
   ├─ fun getPushReceiverModules(): List<String>? // Modules with PushReceiver overrides (optional)
   ├─ fun getPushChannelName(): String?          // Notification channel name (optional)
   └─ fun getPushChannelDescription(): String?   // Notification channel description (optional)

Event Classes

Event
// Base SDK event (universal telemetry).
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date
internal: Boolean


Error
// SDK error, inherits from Event.
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date


RetryError
// Request error with automatic retry and execution
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date

SDKEvent Enum

// Enum class containing all SDK event types.
// Each value contains a string message.

enum class SDKEvent(val message: String) {
    // General SDK events
    ConfigIsSet("SDK configuration is installed"),
    PushProviderSet("push provider set: "),
    NotAcPush("received a notification unrelated to the Altcraft Platform"),
    AcPush("received Altcraft push notification"),
    PushIsPosted("push is posted"),
    SdkCleared("SDK data has been cleared"),
    ReceiverRedefined("receiver is redefined"),
    NotAuthenticatedError("User is not authenticated"),
    UserLogOut("User logged out. Anonymous session started."),

    // Internal errors without retry
    ConfigIsNotSet("the configuration is not set"),
    ConfigNotValid("invalid configuration"),
    SdkInitWaitingExpired("SDK initialization timeout has expired"),
    MobileEventPartsIsNull("mobile event parts is null"),
    InvalidPushProvider("invalid provider. Available - android-firebase, android-huawei, android-rustore."),
    PushDataIsNull("push data is null"),
    PushUidIsNull("uid in the push data is null or empty, it is impossible to send a push event to the server."),
    ErrorImgLoad("error uploading the notification image"),
    NotificationErr("couldn't create notification"),
    ChannelNotCreated("the notification channel has not been created"),
    SmidIsNull("send message ID is null"),
    InvalidStaticField("invalid in-app static field"),
    RoomMigrationError("Room database migration failed. The local SDK database will be recreated."),

    // Missing request payload (without retry)
    UnSuspendRequestDataIsNull("unsuspend request data is null"),
    SubscriptionStatusRequestDataIsNull("status request data is null"),
    InAppSubscriptionStatusRequestDataIsNull("status request data is null"),
    AuthorizeRequestDataIsNull("authorize request data is null"),

    // Retry limit reached
    PushSubscribeRetryLimit("push subscribe retry limit"),
    PushEventRetryLimit("push event retry limit"),
    MobileEventRetryLimit("mobile event retry limit"),
    ProfileUpdateRetryLimit("profile update retry limit"),
    InAppSubscribeRetryLimit("in-app subscribe retry limit"),
    AuthRequestRetryLimit("auth request retry limit"),
    InAppEventRetryLimit("in-app event retry limit"),

    // SDK or environment state issues
    ConfigIsNull("config data is null"),
    PushTokenIsNull("current push token is null"),
    UserTagIsNull("userTag is null. It is impossible to identify the user"),
    PermissionDenied("no permission to send notifications"),
    NoInternetConnect("no internet connection, retry when connection is restored"),
    NotUpdated("failed to update the push token. The subscription request was rejected"),
    ResponseDataIsNull("response data is null"),
    JwtTokenIsNull("JWT token is null"),
    MatchingIsNull("matching mode is null"),
    JwtTooLarge("JWT payload exceeds allowed size (16 KB limit): input rejected to prevent DoS"),
    PayloadIsMissing("JWT does not contain a payload"),
    InternalAuthIsNull("internal auth data is null"),
    ExternalAuthIsNull("external auth data is null"),
    MatchingIdIsNull("matching claim does not contain a matching ID"),
    InvalidPayload("invalid mobile event payload: not all values are primitives"),
    InvalidCustomFields("invalid custom fields: not all values are primitives"),

    // Missing request payload (with retry)
    PushSubscribeRequestDataIsNull("push subscribe request data is null"),
    TokenUpdateRequestDataIsNull("token update request data is null"),
    PushEventRequestDataIsNull("push event request data is null"),
    InAppEventRequestDataIsNull("in-app event request data is null"),
    MobEventRequestDataIsNull("mobile event request data is null"),
    ProfileUpdateRequestDataIsNull("profile update request data is null"),
    InAppSubscribeRequestDataIsNull("profile update request data is null"),
    InAppPlacementsRequestDataIsNull("in-app placements request data is null"),

    // Successful API requests
    PushUnsubscribeRequestSuccessful("successful request: push/unsubscribe"),
    PushSubscribeRequestSuccessful("successful request: push/subscribe"),
    PushSuspendRequestSuccessful("successful request: push/suspend"),
    InAppUnsubscribeRequestSuccessful("successful request: inapp/unsubscribe"),
    InAppSubscribeRequestSuccessful("successful request: inapp/subscribe"),
    InAppStatusRequestSuccessful("successful request: inapp/status"),
    InAppEventRequestSuccessful("successful request: inapp/event"),
    InAppPlacementsRequestSuccessful("successful request: in_app/placements"),
    PushStatusRequestSuccessful("successful request: push/status"),
    TokenUpdateRequestSuccessful("successful request: push/update"),
    PushEventRequestSuccessful("successful request: event/push"),
    MobileEventRequestSuccessful("successful request: event/post"),
    UnsuspendRequestSuccessful("successful request: push/unsuspend"),
    ProfileUpdateRequestSuccessful("successful request: profile/update"),
    AuthenticateSuccessful("successful request: profile/authenticate"),

    // Failed API requests
    PushUnsubscribeRequestFailed("failed request: push/unsubscribe"),
    PushSubscribeRequestFailed("failed request: push/subscribe"),
    PushSuspendRequestFailed("failed request: push/suspend"),
    InAppUnsubscribeRequestFailed("failed request: inapp/unsubscribe"),
    InAppSubscribeRequestFailed("failed request: inapp/subscribe"),
    InAppStatusRequestFailed("failed request: inapp/status"),
    InAppEventRequestFailed("failed request: inapp/event"),
    InAppPlacementsRequestFailed("failed request: in_app/placements"),
    PushStatusRequestFailed("failed request: push/status"),
    TokenUpdateRequestFailed("failed request: push/update"),
    PushEventRequestFailed("failed request: event/push"),
    MobileEventRequestFailed("failed request: event/post"),
    ProfileUpdateRequestFailed("failed request: profile/update"),
    UnsuspendRequestFailed("failed request: push/unsuspend"),
    AuthenticateFailed("failed request: profile/authenticate"),
    InAppStaticErrorLoad("error loading in-app notification static resources"),
    InAppContentErrorLoad("error loading in-app notification content"),
}

Data Classes

// Device push provider token
data class TokenData(
    provider: String,
    token: String
)


// Optional data for Firebase Analytics (if used)
data class AppInfo(
    appID: String = "",
    appIID: String = "",
    appVer: String = ""
)


// API response wrapper with HTTP code
data class ResponseWithHttpCode<T : ResponseData>(
    httpCode: Int?,
    response: T?
)


// Request response (implementation of ResponseData)
data class ResponseWithProfile(
    error: Int? = null,
    @SerialName("error_text") errorText: String? = null,
    profile: ProfileData? = null
)


// User profile data
data class ProfileData(
    id: String? = null,
    status: String? = null,
    acid: String? = null,
    @SerialName("is_test") isTest: Boolean? = null,
    subscription: SubscriptionData? = null
)


// Current profile subscription
data class SubscriptionData(
    @SerialName("subscription_id") subscriptionId: String? = null,
    @SerialName("hash_id") hashId: String? = null,
    provider: String? = null,
    status: String? = null,
    fields: Map<String, JsonElement>? = null,
    cats: List<CategoryData>? = null
)


// Subscription category (name, title, flags)
data class CategoryData(
    name: String?,
    title: String? = null,
    steady: Boolean? = null,
    active: Boolean?
)


// Email channel subscription (added by mobile event)
data class EmailSubscription(
    @SerialName("resource_id") resourceId: Int,
    email: String,
    status: String? = null,
    priority: Int? = null,
    @SerialName("custom_fields") customFields: Map<String, @Contextual Any?>? = null,
    cats: List<String>? = null,
    @SerialName("channel") channel: String = "email"
)


// SMS channel subscription (added by mobile event)
data class SmsSubscription(
    @SerialName("resource_id") resourceId: Int,
    phone: String,
    status: String? = null,
    priority: Int? = null,
    @SerialName("custom_fields") customFields: Map<String, @Contextual Any?>? = null,
    cats: List<String>? = null,
    @SerialName("channel") channel: String = "sms"
)


// Push channel subscription (added by mobile event)
data class PushSubscription(
    @SerialName("resource_id") resourceId: Int,
    provider: String,
    @SerialName("subscription_id") subscriptionId: String,
    status: String? = null,
    priority: Int? = null,
    @SerialName("custom_fields") customFields: Map<String, @Contextual Any?>? = null,
    cats: List<String>? = null,
    @SerialName("channel") channel: String = "push"
)


// Subscription with cc_data (Telegram, WhatsApp, Viber, Notify)
data class CcDataSubscription(
    @SerialName("resource_id") resourceId: Int,
    @SerialName("channel") channel: String,
    @SerialName("cc_data") ccData: JsonObject,
    status: String? = null,
    priority: Int? = null,
    @SerialName("custom_fields") customFields: Map<String, @Contextual Any?>? = null,
    cats: List<String>? = null
)


// UTM parameters container for mobile event attribution (all fields optional)
data class UTM(
    campaign: String? = null,
    content: String? = null,
    keyword: String? = null,
    medium: String? = null,
    source: String? = null,
    temp: String? = null
)

Constants

com.altcraft.sdk.data
└─ object Constants
   // Push notification providers
   ├─ const val FCM_PROVIDER: String = "android-firebase"
   ├─ const val HMS_PROVIDER: String = "android-huawei"
   └─ const val RUS_PROVIDER: String = "android-rustore"
   // Subscription statuses
   ├─ const val SUBSCRIBED: String = "subscribed"
   ├─ const val UNSUBSCRIBED: String = "unsubscribed"
   └─ const val SUSPENDED: String = "suspended"

Interfaces

JWTInterface:

JWTInterface
// Access to current JWT
└─ fun getJWT(): String?
   // Returns JWT or null

FCMInterface:

FCMInterface
// FCM token operations contract
├─ suspend fun getToken(): String?
│  // Returns FCM token or null
└─ fun deleteToken(completion: (Boolean) -> Unit)
   // Deletes FCM token

HMSInterface:

HMSInterface
// HMS token operations contract
├─ suspend fun getToken(context: Context): String?
│  // Returns HMS token or null
└─ fun deleteToken(context: Context, complete: (Boolean) -> Unit)
   // Deletes HMS token

RuStoreInterface:

RustoreInterface
// RuStore token operations contract
├─ suspend fun getToken(): String?
│  // Returns RuStore token or null
└─ fun deleteToken(complete: (Boolean) -> Unit)
   // Deletes RuStore token

Subscription:

Subscription (sealed interface)
// Base subscription model contract for all channels
├─ val resourceId: Int
│  // Required Altcraft resource ID (JSON: "resource_id")
├─ val status: String?
│  // Optional subscription status
├─ val priority: Int?
│  // Optional priority
├─ val customFields: Map<String, @Contextual Any?>?
│  // Optional standard and custom fields (JSON: "custom_fields")
├─ val cats: List<String>?
│  // Optional subscription categories
└─ val channel: String
   // Required channel type (e.g., "email", "sms", "push", "telegram_bot", ...)