Skip to main content
Version: 14

Transition Guide (iOS/Swift)

This file helps of finding the corresponding calls of MS8b and events of the MasterController. For further information about the calls and events itself, please use the documentation of either MS8b or MasterController.


The MS8b was an interface based connection between the app and the SDK. This interface needed to be implemented and was the central interface. The MasterController is now an event based connection between the app and the SDK. You need to implement an event interface where you can send and receive events from or to the SDK.



You created a class where all the callbacks were received inside the app. This was handover AstSdkFactory.createAst(SdkListener())

Previously you used - (AstStatus)init:(NSString*)locale version:(NSString*)version appName:(NSString*)appName logLevel:(AstLogLevel)logLevel NS_REFINED_FOR_SWIFT; to start the SDK. This call was followed up by

func getAppConfigParameter(_ type: AstConfigParameter) -> [Any]?

Which takes the configuration of the SDK


You get an instance of the MasterController by calling

+ (id<KSAsyncEventReceiver, KSEcoModulInterface, KSEventSource> _Nullable) getMasterControllerWithParmeter: (NSString* _Nonnull) param andConsumer: (id<KSAsyncEventReceiver> _Nonnull) consumer;

The instance you receive is then used to send events to the MasterController.

For MasterController you provide a @interface KSMStartEvent : KsMacroEvent which takes all the necessary configurations - (instancetype _Nonnull) initWithSsmsAppConfiguration: (KSMSsmsAppConfiguration *_Nonnull) ssmsAppConfiguration scpConfig: (NSString*_Nonnull) scpConfig certificateChain: (NSData* _Nonnull) certificateChain configurationData: (KSMConfigurationData* _Nonnull) configurationData NS_DESIGNATED_INITIALIZER;

As a response you will receive @interface KSMStartResultEvent : KsMacroEvent

Depending on the status you need either to login or activate.


If you have no activated users/accounts on the device, you will get the activation callback/event after the successful init of the SDK or MasterController. The KSMStartActivationUserIdAndCodeOnlyEvent is just an information event.


onActivationBeginKSMStartActivationUserIdAndCodeOnlyEventStart of activation flow
onActivationEndKSMActivationResultEventEnd of activation flow


The activation process is the sequence of the three calls:

func onActivationBegin(_ deviceType: AstDeviceType)

- (void)doActivation:(AstDeviceType)deviceType pin:(NSString*)pin userId:(NSString*)userId activationCode:(NSString*)activationCode;

func onActivationEnd(_ deviceType: AstDeviceType, status: AstStatus)

After those calls you are either logged in or need to login.


The process is now split up into two steps.

First step is to send user ID and activation code to the MasterController.

@interface KSMStartActivationUserIdAndCodeOnlyEvent : KsMacroEvent

@interface KSMProvideActivationCodeAndUserIdEvent : KsMacroEvent

This is followed up by sending the PIN to the MasterController.

@interface KSMStartActivationSetPINEvent : KsMacroEvent

@interface KSMProvideSetPinEvent : KsMacroEvent

For the result you will also receive an event which gives you the status of the activation process. After That you are either logged in or need to login

@interface KSMActivationResultEvent : KsMacroEvent


If you have already activated users/accounts on the device, you will get the login callback/event after the successful init of the SDK or MasterController. The KSMStartLoginEvent is just an information event.


onLoginBeginKSMStartLoginEventStart of login flow
doLoginKSMLoginEventTrigger the login process
onLoginEnd KSMLoginResultEventGet the result of the login process


func onLoginBegin(_ deviceType: AstDeviceType, userIdList: [Any])

- (void)doLogin:(AstDeviceType)deviceType pin:(NSString*)pin userId:(NSString*)userId;

func onLoginEnd(_ deviceType: AstDeviceType, status: AstStatus, loginOtp: String?, userId: String?, retryCounter: Int32, retryDelay: Int32)


The new events are similar to MS8b

@interface KSMStartLoginEvent : KsMacroEvent

@interface KSMLoginEvent : KsMacroEvent

@interface KSMLoginResultEvent : KsMacroEvent



KSMTriggerBannerEvent Information about an available transaction
onTransactionBlockBeginKSMStartTransactionEventStart closure for transactionflow
onPinRequiredBeginKSMTransactionPinRequiredRequestEventStart to verify the PIN
doPinRequiredKSMProvidePinEventTrigger verification of the PIN
onPinRequiredEndKSMProvidePinResultEventResult of PIN verification
onTransactionBeginKSMDisplayConfirmationRequestEventReception of the transaction information
doTransactionKSMDisplayConfirmationEventConfirm or decline of the transaction
onTransactionEndKSMDisplayConfirmationResultEventResult of the confirmation or the decline
onTransactionBlockEndKSMTransactionFinishedEventIndication that the transactionflow is finished


For MS8b the SDK triggered the calls for the transaction itself and you had to react to it. All other SDK calls were then blocked by this process.

The calls that are wrapped around the transaction callbacks are

func onTransactionBlockBegin(_ deviceType: AstDeviceType, timeout: UInt32)

func onTransactionBlockEnd(_ deviceType: AstDeviceType)

If a PIN is needed for security reasons

func onPinRequiredBegin(_ deviceType: AstDeviceType, pinReason: AstPinReason)

- (void)doPinRequired:(AstDeviceType)deviceType confirm:(AstConfirmation)confirm pin:(NSString*)pin

func onPinRequiredEnd(_ deviceType: AstDeviceType, status: AstStatus, retryCounter: Int32)

The transaction calls which require the confirmation are

func onTransactionBegin(_ deviceType: AstDeviceType, displayData: String?, confirmationType: AstConfirmationType)

- (void)doTransaction:(AstDeviceType)deviceType confirm:(AstConfirmation)confirm displayData:(NSString*)displayData;

func onTransactionEnd(_ deviceType: AstDeviceType, status: AstStatus)


In the MasterController you will receive an event which tells you, that there is a transaction available, which you can then request when you are ready.

The event telling that a transaction is available is

@interface KSMTriggerBannerEvent : KsMacroEvent

The MasterController is not blocked by this event flow until you trigger it.

Now you can start the event flow for the Transaction by sending the event to the MasterController

@interface KSMStartTransactionEvent : KsMacroEvent

If you need extra security there is still the opportunity for using a PIN inside the transaction.

@interface KSMTransactionPinRequiredRequestEvent : KsMacroEvent

@interface KSMProvidePinEvent : KsMacroEvent

@interface KSMProvidePinResultEvent : KsMacroEvent

The transaction calls with the information and to be confirmed are

@interface KSMDisplayConfirmationRequestEvent : KsMacroEvent

@interface KSMDisplayConfirmationEvent : KsMacroEvent

@interface KSMDisplayConfirmationResultEvent : KsMacroEvent

The transaction process is wrapped up by the event

@interface KSMTransactionFinishedEvent : KsMacroEvent

Change PIN


doPinChangeRequestKSMStartChangePinEventAsk for possibility of changing the pin
onPinChangeBeginKSMStartSetNewPinEventStart of PIN change flow
doPinChangeKSMProvideSetNewPinEventProvide old and new PIN
onPinChangeEndKSMChangePinResultEventResult of PIN change


For changing the PIN it is necessary to request the SDK for permission that it can trigger some communication flags that are needed. - (void)doPinChangeRequest:(AstDeviceType)deviceType;

func onPinChangeBegin(_ deviceType: AstDeviceType, status: AstStatus)

- (void)doPinChange:(AstDeviceType)deviceType confirm:(AstConfirmation)confirm currentPin:(NSString*)currentPin newPin:(NSString*)newPin;

func onPinChangeEnd(_ deviceType: AstDeviceType, status: AstStatus, retryCounter: Int32)


Also for the change PIN in the MasterController it is needed to ask for permission because the MasterController also needs to set some communication flags.

Therefore the flow of calls is close to the same like in MS8b

@interface KSMStartChangePinEvent : KsMacroEvent

@interface KSMStartSetNewPinEvent : KsMacroEvent

@interface KSMProvideSetNewPinEvent : KsMacroEvent

@interface KSMChangePinResultEvent : KsMacroEvent



func onAlert(_ deviceType: AstDeviceType, subSystem: UInt32, errorCode: UInt32)

func onReport(_ deviceType: AstDeviceType, reportId: Int32)


@interface KSMWarningEvent : KsMacroEvent

@interface KSMErrorRuntimeEvent : KsMacroEvent

@interface KSMErrorFatalEvent : KsMacroEvent