Skip to main content

Start/Restart Event

Start Event is the initial event we need to trigger when our app starts communicating with the Master Controller. This event informs us whether the user needs to activate or log in. Additionally, it handles some configuration tasks in the background. When triggering this event, we must provide certain configuration-related information. You can find relevant details about this event here.

In the start event, you must provide values for APP_NAME and the app version. While you do not necessarily have to use the values provided in the samples, it is essential to configure these values in the security server. Refer to Add App in Security Server for instructions on adding a new app in your Security Server. Similarly, refer to Register App Version for registering a new app version.

Also, you must provide the language you expect to be used in transactions sent to this instance of your app. This must be a language tag as described in RFC 3066 with additional requirement:

  • In KOBIL Digitanium and KOBIL Digitanium+, only two-letter primary subtags are allowed, e.g. "de" or "en" As for configuring the translation templates on the server side, see the full documentation of the ASM module available via https://developer.kobil.com/docs/ssms-docs/ssmsgui/modules/asm-module/overview.
  • In KOBIL Shift Lite a region subtag is allowed in addition to the primary subtag (e.g. "de-DE", "de-CH", "en-GB", or "en-US"), localization templates are maintained as described in https://developer.kobil.com/api/ast#tag/Localization. Note that more specialized tags match more general language specifications, i.e. if the app asks for "de-DE" and the server has only "de" available, then that translation is used. However, in the opposite direction this does not work, i.e. if the app asks for "de" and the server has "de-CH" and "de-DE", then neither does match and you fall back to the default translation which might be e.g. "en".

Which language tags actually work depends on localization templates on the server side. If a suitable language is not found, transactions automatically fall back to using the translations that have been marked as the default language on the server side. In general, it is a good idea to keep the translations on the server side general, i.e. make sure to have a translation for the base language (e.g. "de"). However, we expect that most of the time there is some coordination between people developing the app and people maintaining the translation on the server side, so you should know, which languages are available and which tags to use to choose them.

Start event flow-diagram​

The following diagram illustrates the Start Event and its reply:

iOS/Swift​

For Swift, you can use the following snippet to trigger the Start Event.

Note: The Swift code utilizes helper classes available in the sample app's code to read the configuration files and directly pass their content to the MasterController. This method is not the currently recommended approach! One of the key helper functions is getSMSConfiguration, as shown below:

Triggering Start Event (Swift)
func triggerStartEvent(){

        // This is the mc_config json file model
         let scpConfiguration = globalConst.scpConfiguration
        // This is the scp certificate file content
        guard let certChain = Utilities.getSSLCertificate(fileName: scpConfiguration?.scp?.trustedSslServerCerts?.first ?? "") else {
            return
        }
        // SSMS Configuration
        guard let smsConfiguration = Utilities.getSSMSConfiguration() else {
            return
        }
        // mc_config file path
        guard let scpFilePath = AssetsHelper.getScpConfigFilepath() else {
            return
        }
        // mc_config JSON string
        guard let scpConfigJsonString = JsonHelper.getDictionaryFrom(filePath: scpFilePath)?.toJSONString() else {return}
        // Create start event
        let startEvent = KSMStartEventEx(ssmsAppConfiguration: smsConfiguration, mcConfig: scpConfigJsonString, certificateChain: certChain, configurationData: KSMConfigurationData(category: "payment", tagName: "paymentContent.cardTokenID"))
        masterControllerAdapter.sendEvent2MasterController(startEvent){ event in
            // Handle post event accordingly.
        }
    }
Getting SSMS configuration (Swift)
class func getSMSConfiguration() -> KSMSsmsAppConfiguration? {
    let sdkFilePath = "\(GlobalConstant.const.assetFolder)/sdk_config"
    guard let path =  Bundle.main.path(forResource: sdkFilePath, ofType: "xml")
    else {
        return nil
    }
    let data = NSData(contentsOfFile: path ) as Data?
    let version = KSMVersion(majorVersion: 1, minorVersion: 0, build: 5)
    let smsConfig = KSMSsmsAppConfiguration(
    locale: "de",
    version: version,
    name: "MCWMPGettingStartedSwift",
    sdkconfig: data!)
    return smsConfig
}

Android/Kotlin​

For Kotlin, we have created a specific method in the MCHandler class of our sample app to trigger this event. Below is the code snippet.

Note: Kotlin's KsMcConfigManager is a helper class that converts the mc_config.json file (located in the assets folder) into a model class.

Triggering Start Event (Kotlin)
fun triggerStartEvent() {
    val sdkConfig = getSDKConfig()
    sdkConfig?.let {
        val mcConfig = KsMcConfigManager.getEntityInstance()
        val startEvent = StartEvent(
            AppConstants.LOCALE,
            AppVersion(
                BuildConfig.VERSION_MAJOR,
                BuildConfig.VERSION_MINOR,
                BuildConfig.VERSION_BUILD
            ),
            AppConstants.APP_NAME,
            KsMcConfigManager.getInstance().getMcConfigContent(),
            "",
            it,
            getIamCerts()
        )
        logDebug("triggering StartEvent", "triggerStartEvent with data => $startEvent", TAG)
        launchIO {
            SessionManager.getInstance(context).setStartTime(System.currentTimeMillis())
            mcEventHandler?.postEvent(startEvent)?.then {
                // handle result
            }
        }
    }.orElse {
        logDebug("sdk config is null", "triggerStartEvent", TAG)
    }
}
Getting SDK Config (Kotlin)
private fun getSDKConfig(): ByteArray? {
    var sdkConfig: ByteArray? = null
    try {
        logDebug("configuring sdk", "getSDKConfig", TAG)
        val configName = SessionManager.getInstance(context).getConfigName()
        var inputStream : InputStream? = null
        if (KsMcConfigManager.getEntityInstance().astServerBackend == "maverick") {
            inputStream = context.assets.open("$configName${File.separator}${AppConstants.SDK_CONFIG_FILE_MAVERICK}")
        } else if (KsMcConfigManager.getEntityInstance().astServerBackend == "ssms") {
            inputStream = context.assets.open("$configName${File.separator}${AppConstants.SDK_CONFIG_FILE_SSMS}")
        }
        val size = inputStream?.available()
        logDebug("sdkConfig file size: $size")
        val buffer = size?.let { ByteArray(it) }
        inputStream?.read(buffer)
        inputStream?.close()
        sdkConfig = buffer
    } catch (e: IOException) {
        logDebug("failed to load the sdkConfig: ==> ${e.message}", "getSDKConfig", TAG)
    }
    return sdkConfig
}
Constants value used in Start Event (Kotlin)
const val LOCALE = "en"
const val APP_NAME = "MCWMPGettingStarted"

NOTE: You must have an assets folder with correct config files in your project folder, in order to send the correct configuration to SSMS. Configuration related files would be provided by Kobil with project files.

RestartEvent​

In certain situations, you may need to restart the SDK, such as when logging out in KOBIL Digitanium or KOBIL Digitanium+ / KOBIL Shift Lite. Additionally, the SDK itself might initiate a restart, for instance, if it encounters a RuntimeErrorEvent. Because most of the configuration can be retained from the previous startup of the Master Controller, we require fewer parameters compared to the Start Event. However, you still need to provide values for APP_NAME and the app version.

IMPORTANT: When calling RestartEvent, developers must wait for RestartResultEvent before proceeding to use any MC features. Attempting to use the SDK before initialization (StartEvent) has completed will result in errors, and the same applies for re-initialization (RestartEvent). ⚠️ In certain cases, such as a RuntimeError, the SDK may trigger a RestartEvent. Ensure that your app can respond to a RestartResultEvent at any time!

Restart event flow-diagram​

The following diagram illustrates the Restart Event and its reply:

iOS/Swift​

For Swift, you can use the following snippet to trigger the Restart Event.

Triggering Restart Event (Swift)
func triggerRestartEvent() {
    guard let smsConfig = Utilities.getSMSConfiguration() else {return }
	let restartEvent = KSMRestartEvent(locale: smsConfig.locale, version: smsConfig.version, appName: smsConfig.name)
	masterControllerAdapter.sendEvent2MasterController(restartEvent){ event in
		// Handle post event accordingly.
	}
}

Android/Kotlin​

In Kotlin you can trigger RestartEvent like that:

Triggering Restart Event (Kotlin)
fun triggerRestartEvent() {
    val restartEvent = RestartEvent(
        AppConstants.LOCALE,
        AppVersion(
            BuildConfig.VERSION_MAJOR,
            BuildConfig.VERSION_MINOR,
            BuildConfig.VERSION_BUILD
        ),
        AppConstants.APP_NAME
    )
    mcEventHandler?.postEvent(restartEvent)?.then {
        // handle result
    }
}
Constants value used in Start Event (Kotlin)
const val LOCALE = "en"
const val APP_NAME = "MCWMPGettingStarted"