State Changes

This topic provides information on changes in the state.

Changes in state communicate the current user context from the SDK to the parent app. As a result, the Netspend API expects parent apps to rely on changes for the most business logic.

A client application can use many micro apps, but only one can be shown at a time, the rest must be hidden.
A parent app should subscribe to state changes, enabling the parent app to determine which micro apps to hide or show. Netspend provides a limited number of states so integrators can limit the scope of work to showing and hiding logic when utilizing micro apps.

Each micro app section in this document provides possible values for success and error data.

Note: Netspend also provides an Events API, but it provides highly granular details and is not suitable for most standard use cases.

Netspend SDK States

Netspend exposes the following SDK states.

startedMicro app has loaded and working properly for the account holder.
cancelledAccount holder has either:
- Explicitly clicked a button in the micro app communicating that they have abandoned an action, or
- Clicked the back button with no other states available in the micro app. The Parent app should close the micro app.
successAccount holder has completed the intended purpose inside the micro app. The parent app should close the micro app.
errorMicro app has encountered an error that the account holder cannot overcome. Netspend usually shows an error screen for this state, but the parent app can instruct the micro app to close itself and show a user interface (UI) instead.

Netspend SDK Micro App States

Netspend exposes the following Netspend SDK micro app states.

uninitializedMicro app has not yet been initialized.
initializingMicro app has been initialized but is not ready to use yet.
readyMicro app is ready to be launched.
busyMicro app is already launched and is blocking the launch of a different micro app. The existing micro app must be closed before launching another one.

Netspend SDK State Usages

The following sections illustrate how to subscribe to Netspend SDK state changes in each SDK.

Web SDK Usage

In the following sample, the micro app subscribes to state changes using the onStateChange property to register stateChangeHandler as the change handler. Subscription is done in the micro app’s open method.

const stateChangeHandler = (state,data) => {
	case 'started':
		console.log("[NetspendSDK] Purpose has been started!");
	case 'cancelled':
		console.log("[NetspendSDK] Purpose has been cancelled!");
	case 'error':
		console.log("[NetspendSDK] Purpose encountered an error!");
	case 'success':
		console.log("[NetspendSDK] Purpose was successful!");
  purpose: "linkBank", 
  passcode: "abcd1234", 
  params: {
	bankLinkId: "some_id" 
     // The Netspend provided Bank Link Identifier that the 
     // account holder uses to re-link the bank account.
  onStateChange: stateChangeHandler,
  onEvent(event, data) {
	// An event happened that you want to track. 

Android SDK Usage

The following sample uses the onNetspendSdkStateChange handler to subscribe to state changes.

class MyNetspendActivity : NetspendSdkActivity() {
  override fun onNetspendSdkStateChange(state: NetspendSdkPurposeState, data: Map<String, Any>){
      when(state) {
        NetspendSdkPurposeState.STARTED ->
          System.out.println("[NetspendSDK] Purpose $purposeName has been started!")

        NetspendSdkPurposeState.CANCELLED -> {
          System.out.println("[NetspendSDK] Purpose $purposeName was requested to be
          cancelled by the user!")

        NetspendSdkPurposeState.ERROR -> {
          System.out.println("[NetspendSDK] Purpose $purposeName encountered an

        NetspendSdkPurposeState.SUCCESS -> {
          System.out.println("[NetspendSDK] Purpose $purposeName was successful!")

iOS SDK Usage

The following sample subscribes to state changes from the ViewController. The sample also shows how animations can be used when closing and opening micro apps.

// The implementation `NetspendSdkViewDelegate` for your view controller
extension MyOwnViewController: NetspendSdkViewDelegate {
  func netspendSdkViewController(
    _ viewController: NetspendSdkViewController,
    didChange state: NetspendSdkPurposeState
  ) {
    switch state {
    case .started:
      print("[NetspendSDK] Purpose \(viewController.purpose) has been

    case .cancelled:
      print("[NetspendSDK] Purpose \(viewController.purpose) was
      requested to be cancelled by the user!")
      // Make sure to dismiss or otherwise hide the 
      //previously opened view controller.
      // This will not be done automatically
      dismiss(animated: true)

    case .error(let errorInfo):
      print("[NetspendSDK] Purpose \(viewController.purpose)
      encountered an error!", errorInfo)
      // Also should hide the view controller 
      // in case of irrecoverable error
      dismiss(animated: true)

    case .success(let successInfo):
      print("[NetspendSDK] Purpose \(viewController.purpose) 
      was successful!", successInfo)
      // Also should hide the view controller when successful
      dismiss(animated: true)
      // Refresh app data related to the purpose that completed