Public SDK API

The SDK is assembled from modules: the mandatory Core and the optional Push, Target, Profile, In-App. Each module is connected with a separate dependency and is accessed through the corresponding property of the AltcraftSDK object:

AltcraftSDK          // Core: initialization, authentication, events, cleanup
AltcraftSDK.auth     // Core: user authentication
AltcraftSDK.push     // Push: subscriptions, tokens, notifications
AltcraftSDK.target   // Target: sending goals
AltcraftSDK.profile  // Profile: profile fields
AltcraftSDK.inApp    // In-App: campaigns and subscriptions

Core (mandatory module)

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
// Allow reinitialization of retry operations and token checks in the current session
├─ fun unlockInitialOperationsInThisSession(): Unit
// Access to user authentication
├─ val auth: AuthAPI
// Access to SDK events (single subscriber)
├─ val SDKEvents: Events
// Core module event types
└─ val moduleEvents: CoreEvents

object AuthAPI

AuthAPI
// Set the JWT token provider (null — unset)
├─ fun setJWTProvider(provider: JWTInterface?): Unit
// Authenticate the user
├─ fun authenticate(context: Context): Unit
// User log out (restores an anonymous session)
├─ fun logOut(context: Context): Unit
// Check the authentication status
└─ suspend fun isAuthenticated(context: Context): Boolean

object Events

Events
// Subscribe to SDK events (replaces the existing subscriber)
├─ fun subscribe(newSubscriber: (Event) -> Unit): Unit
// Unsubscribe from SDK events
└─ fun unsubscribe(): Unit

object CoreEvents — public events of the Core module

CoreEvents
// General SDK events
├─ val configIsSet: SDKEvent             // SDK configuration is installed
├─ val sdkCleared: SDKEvent              // SDK data has been cleared
├─ val notAuthenticatedError: SDKEvent   // User is not authenticated
├─ val userLogOut: SDKEvent              // User logged out. Anonymous session started.
├─ val roomMigrationError: SDKEvent      // Room database migration failed. The local SDK database will be recreated.
// Successful API requests
├─ val authenticateSuccessful: SDKEvent  // successful request: profile/authenticate
// Failed API requests
└─ val pushStatusRequestFailed: SDKEvent // failed request: push/status

class AltcraftConfiguration

com.altcraft.sdk.config
└─ class AltcraftConfiguration private constructor(...)
   // Altcraft SDK configuration class: API URL, resource token, app
   // details, logging flag, and configurations of optional modules.

   ├─ val apiUrl: String
   ├─ val rToken: String?
   ├─ val appInfo: AppInfo?
   └─ val enableLogging: Boolean?

   └─ class Builder(
        apiUrl: String,                    // Base URL of the Altcraft API (mandatory)
        rToken: String? = null,            // Role token (optional)
        appInfo: AppInfo? = null,          // App details (optional)
        enableLogging: Boolean? = null     // Enables/disables logging (optional)
      )
      // Add an optional module configuration (a repeated call for the
      // same module replaces the previous configuration)
      ├─ fun addModuleConfiguration(configuration: ModuleConfiguration): Builder
      // Build a valid configuration
      └─ fun build(): AltcraftConfiguration

Push (optional module)

object Push

Push
// Access to the push token API
├─ val token: TokenAPI
// Access to push events (delivery, open)
├─ val pushEvents: EventAPI
// Push module event types
├─ val moduleEvents: ModuleEvents
// Access to receiving incoming push notifications
├─ val receiver: PushReceiverApi
// Access to push notification subscriptions
├─ val subscription: SubscriptionAPI
// Request notification permission (Android 13+)
└─ fun requestNotificationPermission(context: Context, activity: ComponentActivity): Unit

object PushReceiverApi

PushReceiverApi
// Check whether a push notification belongs to Altcraft
├─ fun isAltcraftPush(message: Map<String, String>): Boolean
// Pass an incoming push notification to the SDK
└─ fun takePush(context: Context, message: Map<String, String>): Unit

open class PushReceiver

PushReceiver
// Handling of an incoming push notification.
// Override it for a custom notification display. The SDK looks for
// implementations via reflection in the packages specified in
// PushConfiguration.pushReceiverModules; if none is found, it uses the
// standard implementation and calls pushHandler.
└─ open suspend fun pushHandler(context: Context, message: Map<String, String>): Unit

object TokenAPI

TokenAPI
// Register the FCM provider (null — unset)
├─ fun setFCMTokenProvider(provider: FCMInterface?): Unit
// Register the HMS provider (null — unset)
├─ fun setHMSTokenProvider(provider: HMSInterface?): Unit
// Register the RuStore provider (null — unset)
├─ fun setRuStoreTokenProvider(provider: RustoreInterface?): Unit
// Get the current device token
├─ suspend fun getToken(context: Context): TokenData?
// Delete the token at the selected provider
├─ suspend fun deleteToken(context: Context, provider: String): Unit
// Forced token update (delete → update)
├─ suspend fun forcedTokenUpdate(context: Context): Unit
// Manually save a provider token
├─ suspend fun setToken(context: Context, provider: String?, token: String?): Unit
// Change the provider priority and update the token
└─ suspend fun changeProviderPriority(context: Context, priority: List<String>): Unit

object EventAPI

EventAPI
// Record the delivery of an Altcraft push (fires the delivery event)
├─ suspend fun deliveryEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit
// Record the opening of an Altcraft push (fires the open event)
└─ suspend fun openEvent(context: Context, message: Map<String, String>? = null, messageUID: String? = null): Unit

object SubscriptionAPI

SubscriptionAPI
// Push subscription statuses
├─ val status: StatusAPI
// 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
// Suspend the push notification subscription (status = SUSPENDED)
├─ fun suspend(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 unsubscribe(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 the subscription status specified in the JWT from suspended to
// subscribed; the remaining subscriptions containing the specified push
// token will change their status from subscribed to suspended
├─ suspend fun unSuspend(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
// Add a functional profile field (set/incr/...)
└─ fun actionField(key: String): ActionFieldBuilder

object StatusAPI

StatusAPI
// Status of the profile's latest subscription
├─ suspend fun latest(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
// Status of the subscription with the current device token
├─ suspend fun current(context: Context): ResponseWithHttpCode<ResponseWithProfile>?
// Status of the profile's latest subscription for the specified push notification provider
└─ suspend fun latestForProvider(context: Context, provider: String? = null): ResponseWithHttpCode<ResponseWithProfile>?

class PushConfiguration

com.altcraft.sdk.push.config
└─ class PushConfiguration(
     icon: Int? = null,                        // Notification icon resource ID (optional)
     providerPriority: List<String> = emptyList(), // Priority of push notification providers (optional)
     pushReceiverModules: List<String> = emptyList(), // Packages in which PushReceiver may be overridden (optional)
     pushChannelName: String? = null,          // Name of the push notification channel (optional)
     pushChannelDescription: String? = null    // Description of the push notification channel (optional)
   )
   // Extension for adding the Push configuration to the main builder
   └─ fun AltcraftConfiguration.Builder.pushConfig(configuration: PushConfiguration): AltcraftConfiguration.Builder

Target (optional module)

object Target

Target
// Target module event types
├─ val moduleEvents: ModuleEvents
// Send a goal (target event) to the server
└─ fun sendTarget(
       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 (optional module)

object Profile

Profile
// Profile module event types
├─ val moduleEvents: ModuleEvents
// Update profile fields
└─ fun updateProfileFields(context: Context, profileFields: Map<String, Any?>? = null, skipTriggers: Boolean? = null): Unit

In-App (optional module)

object InApp

InApp
// Managing In-App notification subscriptions
├─ val subscription: SubscriptionAPI
// JSON emitter of In-App campaigns for an external subscriber
├─ val emitter: EmitterAPI
// In-App module event types
├─ val moduleEvents: ModuleEvents
// Configure the animation of an In-App notification
├─ fun animation(block: Animator.() -> Unit): Unit
// Set the current screen marker (used when filtering In-App campaigns)
├─ fun setScreen(context: Context, screen: String): Unit
// Trigger a custom In-App campaign by name
├─ fun trigger(context: Context, name: String): Unit
// Request the available In-App placements
└─ fun getPlacements(context: Context): Unit

object SubscriptionAPI (In-App)

SubscriptionAPI
// Subscribe to In-App 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
// Unsubscribe from In-App notifications (status = UNSUBSCRIBED)
├─ fun unSubscribe(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
// Status of the In-App notification subscription
└─ suspend fun getSubscriptionStatus(context: Context): ResponseWithHttpCode<ResponseWithProfile>?

object EmitterAPI

EmitterAPI
// Subscribe to the JSON of In-App campaigns (replaces the existing subscriber)
├─ fun subscribe(newSubscriber: (String) -> Unit): Unit
// Unsubscribe from the JSON of In-App campaigns
└─ fun unsubscribe(): Unit

interface Animator

Animator
// Identifier of the placement the animator belongs to
├─ val companyId: Int
// Apply the block to the In-App view instantly, without starting an animation
├─ fun prepare(block: View.() -> Unit): Unit
// Configure and start a property animation for the In-App view
└─ fun animate(block: ViewPropertyAnimator.() -> Unit): Unit

class InAppConfiguration

com.altcraft.sdk.inapp.config
└─ class InAppConfiguration(
     inAppAutoRequest: Boolean = true         // Automatic request of In-App placements (optional)
   )
   // Extension for adding the In-App configuration to the main builder
   └─ fun AltcraftConfiguration.Builder.inAppConfig(configuration: InAppConfiguration): AltcraftConfiguration.Builder

Data models

Event Classes

Event
// Base SDK event (general-purpose 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 for which an automatic retry and execution are provided
function: String
event: SDKEvent?
eventMessage: String?
eventValue: Map<String, Any?>?
date: Date

Data Classes (Core)

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


// Wrapper of an API response together with the HTTP code
data class ResponseWithHttpCode<T : ResponseData>(
    httpCode: Int?,
    response: T?
)


// Request response (implementation of BaseResponseData)
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?
)

Data Classes (Push)

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

Data Classes (Target)

com.altcraft.sdk.target.data.models.TargetModels

// Container of UTM parameters for goal attribution (all fields are optional)
data class UTM(
    campaign: String? = null,
    content: String? = null,
    keyword: String? = null,
    medium: String? = null,
    source: String? = null,
    temp: String? = null
)


object SubscriptionModel {
    // Base interface of all subscription types added by a goal
    sealed interface Subscription {
        @SerialName("resource_id")
        val resourceId: Int
        val status: String?
        val priority: Int?
        @SerialName("custom_fields")
        val customFields: Map<String, @Contextual Any?>?
        val cats: List<String>?
        val channel: String
    }

    // Subscription to the Email channel
    data class EmailSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        val email: String,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription {
        @SerialName("channel")
        override val channel: String = "email"
    }

    // Subscription to the SMS channel
    data class SmsSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        val phone: String,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription {
        @SerialName("channel")
        override val channel: String = "sms"
    }

    // Subscription to the push channel
    data class PushSubscription(
        @SerialName("resource_id") override val resourceId: Int,
        val provider: String,
        @SerialName("subscription_id") val subscriptionId: String,
        override val status: String? = null,
        override val priority: Int? = null,
        @SerialName("custom_fields") override val customFields: Map<String, @Contextual Any?>? = null,
        override val cats: List<String>? = null,
    ) : Subscription {
        @SerialName("channel")
        override val channel: String = "push"
    }

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

Constants

com.altcraft.sdk.push.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"

Interfaces

JWTInterface (Core):

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

FCMInterface (Push):

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

HMSInterface (Push):

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

RuStoreInterface (Push):

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

Subscription (Target):

Subscription (sealed interface)
// Base contract of the subscription model for all channels
├─ val resourceId: Int
│  // Mandatory ID of the Altcraft resource (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
   // Mandatory channel type (for example, "email", "sms", "push", "telegram_bot", ...)