`HeadlessActivity`

Overview

The HeadlessActivity class extends ComponentActivity and provides essential methods for handling the lifecycle and interactions of a SoftPOS transaction activity. This includes managing the UI state, handling NFC operations, and providing themes and UI components.

Methods

`provideTheme`

Override to provide the theme color for the activity.

Returns

Return Type	Description
`ThemeProvider`	The custom theme provider.

Usage

import android.graphics.Color
import com.theminesec.sdk.headless.HeadlessActivity
import com.theminesec.sdk.headless.ui.ThemeProvider
 
class ClientHeadlessImpl : HeadlessActivity() {
    override fun provideTheme(): ThemeProvider = CustomThemeProvider
}
 
object CustomThemeProvider : ThemeProvider() {
    override fun provideColors(darkTheme: Boolean): HeadlessColors = if (darkTheme) {
        HeadlessColorsDark().copy(
            primary = Color.CYAN,
            primaryForeground = Color.BLACK,
            secondary = Color.BLUE,
            secondaryForeground = Color.BLACK,
            approval = Color.GREEN,
            approvalForeground = Color.WHITE,
            error = Color.RED,
            errorForeground = Color.WHITE
        )
    } else {
        HeadlessColorsLight().copy(
            primary = Color.CYAN,
        )
    }
}

`provideUi`

Provides the UI components for the activity.

Returns

Return Type	Description
`UiProvider`	The custom UI provider.

Usage

override fun provideUi(): UiProvider = CustomUiProvider()

You can provide the UI with Compose or as an inflated traditional XML view, for more details, see:

Customize (Compose)→Customize (XML view)→

`interceptBeforeOnline`

This is a suspended method.

Called after the card is read and before the request goes online. Use it to inspect what was read and optionally replace the request, for example to pick a different acceptance tag or add extra fields based on the card BIN.

Parameters

Name	Type	Description
`originalRequest`	`PoiRequest.ActionNew`	The request that started this transaction.
`cardReadExtract`	`CardReadExtract`	A summary of the card read: `paymentMethod`, `cardBin`, `issuerCountryAlpha2` and `consumerPaymentDevice` (for example physical card, mobile phone, watch).

Returns

Return Type	Description
`PoiRequest.ActionNew?`	`null` to keep the original request, or a replacement request.

The replacement request must have the same amount value and currency as the original, otherwise the transaction is aborted with 42_002. Throwing from this method also aborts the transaction with 42_002 (AbortedManually).

Usage

override suspend fun interceptBeforeOnline(
    originalRequest: PoiRequest.ActionNew,
    cardReadExtract: CardReadExtract,
): PoiRequest.ActionNew? {
    return if (cardReadExtract.cardBin.startsWith("4")) {
        originalRequest.copy(preferredAcceptanceTag = "VISA_ROUTE")
    } else {
        null
    }
}

`pendingAppSelection`

Choose the application, debit or credit, for the next card read. This only applies to dual-interface cards (for example in Brazil) that carry both a debit and a credit AID, where the terminal must pick one before the card is processed. It has no effect on other cards or markets.

Value	Description
`AppSelection.NO_APP_SELECT`	Default, no preference.
`AppSelection.SELECT_DEBIT`	Prefer the debit application.
`AppSelection.SELECT_CREDIT`	Prefer the credit application.

The value is read at the start of each card read, and it is reset to no preference after every transaction attempt. It stays inside the SDK and is not part of the PoiRequest or sent to the backend. Override it as a computed property, or as a var you set before launching.

Usage

class ClientHeadlessImpl : HeadlessActivity() {
    // for example, driven by the choice the cashier made in your own screen
    override val pendingAppSelection: AppSelection
        get() = if (userChoseCredit) AppSelection.SELECT_CREDIT else AppSelection.SELECT_DEBIT
}

`readCardFeedback`

Called when a card read finishes, so the app can give the cardholder feedback. The default vibrates for a successful read, and for a failed read it plays an alert tone and vibrates briefly. Override it to change or disable the feedback.

Parameters

Name	Type	Description
`success`	`Boolean`	Whether the card read was successful.

Usage

override fun readCardFeedback(success: Boolean) {
    // silence: no tone or vibration
}

Companion Object

`contract`

Creates an activity result contract for starting the HeadlessActivity.

Parameters

Parameter	Type	Condition	Description
`cls`	`Class<out HeadlessActivity>`	Required	The class of your custom `HeadlessActivity`.

Returns

Return Type	Description
`ActivityResultContract<PoiRequest, WrappedResult<Transaction>>`	The activity result contract for the request `PoiRequest` and wrapped response `WrappedResult<Transaction>`.

Usage

val contract = HeadlessActivity.contract(MyHeadlessActivity::class.java)
val launcher = registerForActivityResult(contract) { result ->
    when (result) {
        is WrappedResult.Success -> {
            // Handle success
            val transaction = result.value
        }
        is WrappedResult.Failure -> {
            // Handle failure
            val errorCode = result.code
            val errorMessage = result.message
        }
    }
}
 
// Start the activity with a PoiRequest
val poiRequest = PoiRequest.ActionNew(/* initialize with appropriate parameters */)
launcher.launch(poiRequest)

HeadlessSetup HeadlessService