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.

Basics

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.

Init

MS8b

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

MasterController

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.

Activation

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.

Quickview

MS8b	MasterController	Description
onActivationBegin	KSMStartActivationUserIdAndCodeOnlyEvent	Start of activation flow
	KSMProvideActivationCodeAndUserIdEvent
	KSMStartActivationSetPINEvent
	KSMProvideSetPinEvent
onActivationEnd	KSMActivationResultEvent	End of activation flow

MS8b

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.

MasterController

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

Login

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.

Important KSMStartLoginEvent Behavior:

• KSMStartLoginEvent will NOT be triggered on the first app start when no user is activated yet
• It will only be triggered after a start/restart if a user is already activated
• Using KOBIL Shift Lite It will NOT be triggered right after activation, because activation is already a login process - there is no point in a KSMStartLoginEvent after a completed login

Quickview

MS8b	MasterController	Description
onLoginBegin	KSMStartLoginEvent	Start of login flow
doLogin	KSMLoginEvent	Trigger the login process
onLoginEnd	KSMLoginResultEvent	Get the result of the login process

MS8b

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)

MasterController

The new events are similar to MS8b

@interface KSMStartLoginEvent : KsMacroEvent

@interface KSMLoginEvent : KsMacroEvent

@interface KSMLoginResultEvent : KsMacroEvent

Transaction

Quickview

MS8b	MasterController	Description
	KSMTriggerBannerEvent	Information about an available transaction
onTransactionBlockBegin	KSMStartTransactionEvent	Start closure for transactionflow
onPinRequiredBegin	KSMTransactionPinRequiredRequestEvent	Start to verify the PIN
doPinRequired	KSMProvidePinEvent	Trigger verification of the PIN
onPinRequiredEnd	KSMProvidePinResultEvent	Result of PIN verification
onTransactionBegin	KSMDisplayConfirmationRequestEvent	Reception of the transaction information
doTransaction	KSMDisplayConfirmationEvent	Confirm or decline of the transaction
onTransactionEnd	KSMDisplayConfirmationResultEvent	Result of the confirmation or the decline
onTransactionBlockEnd	KSMTransactionFinishedEvent	Indication that the transactionflow is finished

MS8b

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)

MasterController

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

Quickview

MS8b	MasterController	Description
doPinChangeRequest	KSMStartChangePinEvent	Ask for possibility of changing the pin
onPinChangeBegin	KSMStartSetNewPinEvent	Start of PIN change flow
doPinChange	KSMProvideSetNewPinEvent	Provide old and new PIN
onPinChangeEnd	KSMChangePinResultEvent	Result of PIN change

MS8b

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)

MasterController

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

Errors

MS8b

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

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

MasterController

@interface KSMWarningEvent : KsMacroEvent

@interface KSMErrorRuntimeEvent : KsMacroEvent

@interface KSMErrorFatalEvent : KsMacroEvent