Skip to main content

Initialization of the KSSIDP (Android/iOS/Flutter)

The KSSIDP SDK initialization process involves setting up the necessary configurations and creating an instance of the KssIdp. This documentation provides a step-by-step guide for initializing the SDK in your application.

iOS/Swift​

For Swift, the following steps can be done to initialize the KssIdpWrapper.

Prerequisites​

Ensure that you have the required information from your configuration files, including:

  • tenantId: The identifier for the tenant.
  • certName: The name of the trusted SSL server certificate.
  • baseUrl: The base URL for the IDP server.
  • masterController: An instance of the Master Controller.

Initialization Steps​

Singleton Instance​

static let sharedInstance: KssIdpModel = {
    var sharedInstance = KssIdpModel()
    return sharedInstance
}()

The sharedInstance is a singleton instance of the KssIdpModel. It ensures a single point of access to the KSSIDP SDK throughout the application.

Configuration Parameters Setup:​

guard let tenantId = GlobalConstats.appConfig?.tenantId,
      let certName = GlobalConstats.appConfig?.iam?.trustedSslServerCerts?.first,
      let baseUrl = GlobalConstats.mcConfig?.iam?.serverUrl,
      let masterController = MasterControllerAdapter.sharedInstance.masterController else {
    fatalError("unable to resolve required information from configuration files")
}
      let certificatePath = "\(Bundle.main.bundlePath)/assets/\(MultiAssets.current)/\(certName)"

Extract the necessary configuration information from your application's global constants or configuration files provided in the assets folder. Generate the path to the SSL server certificate by combining the bundle path, assets folder, and certificate name.

KssIdp Config Setup:​

let idpConfig = KssIdpConfig(certificatePath: certificatePath,
                             baseUrl: baseUrl,
                             tenantId: tenantId,
                             masterController: masterController,
                             shouldKssIdpHandleTms: false, // Deprecated and no longer supported
                             shouldHashPin: true)

Create an instance of KssIdpConfig using the extracted configuration information. This includes the certificate path, base URL, tenantID, masterController, and additional flags.

⚠️ Important: shouldKssIdpHandleTms is deprecated and no longer supported. You must handle transactions yourself. See Transaction Handling for details.

KSSIDP Wrapper Initialization:​

do {
    self.kssIdpWrapper = try KssIdpWrapper(config: idpConfig)
} catch {
    fatalError("unable to initialize KssIdpWrapper. \(error)")
}

Initialize the KssIdpWrapper with the created configuration. Handle any initialization errors, ensuring that the SDK is set up correctly.

NOTE: Now that the SDK is initialized, you can use the KssIdpWrapper instance throughout your application to perform various actions and interactions with the KSSIDP SDK.

Android/Kotlin​

The KSSIDP SDK initialization process on Android involves setting up the necessary configurations and initializing the SDK instance. This documentation provides a step-by-step guide for initializing the SDK in your Android application.

Prerequisites​

Ensure that you have the required information from your configuration files, including:

  • tenantId: The identifier for the tenant.
  • certName: The name of the trusted SSL server certificate.
  • baseUrl: The base URL for the IAM (Identity and Access Management) server.

Initialization Steps​

SDK Instance Retrieval​

fun getInstance(): SynchronousEventHandler? {
    return KssIdp.getSdkInstance()
}

Retrieve the KSSIDP SDK instance using the getSdkInstance method. This allows you to access the SDK functionalities throughout your Android application.

SDK Initialization​

fun init(application: Application) {
    // This ensures that your com.kobil.kssidp.wrapper.masterController.EventListener
    // implementation is notified when the SDK completes an operation.
    KssIdp.setOnResultReceivedListener(this)

    // Register your EventListener to receive events from the Master Controller.
    KssIdp.addEventListener(this)

    // for optional OTel tracing of KSSIDP flows
    var kssIdpTracingConfig: TracingConfig? = TracingConfig(
        tracingUrl = endPointUrl,
        tracingUserName = username,
        tracingPassword = password,
        tracingCerts = tracingCerts
    )

    // Initialize KssIdpConfig for SDK configuration.
    val kssIDPConfig = KssIdpConfig(
        certificatePath = trustedSslServerCerts,
        baseUrl = serverUrl,
        tenantId = tenantId,
        shouldHashPin = true,
        // Deprecated: shouldKssIdpHandleTms is no longer supported.
        // Users must handle transactions themselves.
        // See the transaction handling documentation for details.
        shouldKssIdpHandleTms = false,
        // (optional) pass a valid TracingConfig to make KSSIDP send traces to your endpoint
        tracingConfig = kssIdpTracingConfig
    )

    // Initialize the KSSIDP SDK.
    KssIdp.init(application, kssIDPConfig)
}

⚠️ Important: shouldKssIdpHandleTms is deprecated and no longer supported. You must handle transactions yourself. See Transaction Handling for details.

Flutter/Dart​

The KSSIDP SDK initialization process in Flutter involves setting up the necessary configurations and creating an instance of the KssIdpApi. This documentation provides a step-by-step guide for initializing the SDK in your Flutter application.

Prerequisites​

Ensure that you have the required information from your configuration files, including:

  • tenantId: The identifier for the tenant.
  • certificate: The trusted SSL server certificate data.
  • baseUrl: The base URL for the IDP server.
  • mcWrapperApi: An instance of the Master Controller Wrapper API.

Initialization Steps​

Configuration Setup​

KSSIDP Configuration (Flutter/Dart)
GetIt locator = GetIt.instance;

Future<void> setUpKssIdp() async {
  try {
    // Get configuration from environment or config manager
    final tenantId = Environment.current.appConfig.tenantId;
    final baseUrl = Environment.current.baseUrl;
    final certificate = await Environment.current.iamCertChain;
    final mcWrapperApi = locator<McWrapperHandler>().api;
    
    // Create TMS configuration
    final tmsConfig = KssIdpTmsConfig(
      shouldHandleTms: false, // Deprecated and no longer supported
      contextProvider: () => locator<AppRouter>().navigatorKey.currentContext,
      onTmsWindowShow: () => print("TMS window shown"),
      onTmsWindowDismiss: () => print("TMS window dismissed"),
      onUserConfirmation: (confirmed) => print("User confirmation: $confirmed"),
    );
    
    // Create KSSIDP configuration
    final kssIdpConfig = KssIdpConfig(
      tenantId: tenantId,
      baseUrl: baseUrl,
      certificate: certificate,
      mcWrapperApi: mcWrapperApi,
      tmsConfig: tmsConfig,
    );
    
    // Initialize and register KSSIDP API
    final kssIdpApi = KssIdpApi(kssIdpConfig);
    locator.registerSingleton<KssIdpApi>(kssIdpApi);
    
  } catch (e) {
    print("❌ Failed to initialize KSSIDP: $e");
    throw Exception("KSSIDP initialization failed: $e");
  }
}

⚠️ Important: shouldHandleTms is deprecated and no longer supported. You must handle transactions yourself. See Transaction Handling for details.

KssIdpApi Usage Example​

Using KSSIDP API (Flutter/Dart)
// Access your KssIdpApi instance from anywhere in your app
Future<void> performLogin(String username, String password) async {
  final kssIdpApi = locator<KssIdpApi>();
  
  final credentials = {
    'username': username,
    'password': password,
  };
  
  final loginResult = await kssIdpApi.login(
    'your-client-id',
    AuthenticationMode.no,
    credentials,
  );

  switch (loginResult.status.runtimeType) {
  // Handle result...
  }
}

NOTE: Now that the SDK is initialized, you can access the KssIdpApi instance from the service locator throughout your Flutter application to perform various actions such as login, activation, forgot password, and change password operations.

Receiving Events from the Master Controller (Android)​

After initialization, you need to handle events coming from the Master Controller. There are two approaches depending on how you integrate:

Using KSSIDP's EventListener​

If you are using KSSIDP via com.kobil.kssidp.wrapper.masterController.EventListener, make sure your onEventReceived implementation handles the relevant events. You must also register your listener:

KssIdp.addEventListener(yourEventListenerImpl)

⚠️ Recommendation: Call KssIdp.init and KssIdp.addEventListener as early as possible.

Using the MC Wrapper Directly​

If you are using the MC wrapper directly via com.kobil.wrapper.SynchronousEventHandler, make sure your executeEvent override handles the relevant events. See Communication with the MasterController for details.

⚠️ Recommendation: Instantiate your SynchronousEventHandler(Context) implementation as early as possible in the app lifecycle (e.g., in your Application.onCreate).