Android Lifecyle

The Sensibill SDK lifecycle consists of 3 states: Uninitialized, Initialized, and Started. A method also exists for each state transition and takes the required information to move from one state to the next. A summary of the different states and what they represent can be found below: Full size

NOTE: When switching users, always remember to release the SDK and go through the full initialization & starting procedure again.

Initializing the SDK

Initialization can begin by using the InitializationBuilder to create an Initializer object which will be used to initialize the SDK.

The InitializationBuilder also has a number of optional configurations that can be applied. Subsections below will elaborate on each configuration.

In order to create the InitializationBuilder, two arguments are required:

See the InitializationBuilder Reference for full documentation.

val builder = InitializationBuilder(applicationContext, DefaultEnvironment.RECEIPTS_SANDBOX)

InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.RECEIPTS_SANDBOX);

Optional Initialization Configuration: SDK Lifecycle Listener

• Lifecycle events of activities in the SDK can be monitored by the host application by providing an AbstractActivityLifecycleListener during initialization.

builder.activityLifecycle(object : AbstractActivityLifecycleListener() {
        // implement methods here
    })

InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
        .activityLifecycle(new AbstractActivityLifecycleListener() {
            // implement methods here
        });

Optional Initialization Configuration: Token Provider

• A custom token provider can be used by the SDK by providing an Auth Token Provider. When the current session expires or if the curent token becomes invalid, the SDK will use this token provider to retrieve a new token.
• The strategy for providing tokens depends on the Authentication strategy (i.e., On-Device Authentication vs Integration Server Authentication). For more details see the Authentication Options page
• The token provider needs to provide a unique token for each user
  • The token provided is used for communication with the Sensibill API. Each token is tied to a particular user, therefore it is important to ensure the token provided is always for the intended user.

builder.authTokenProvider(object : TokenProvider {
        override fun provideTokenReplacement(
            oldAuthToken: String?,
            userIdentifier: String,
            listener: TokenProvider.OnTokenProviderListener
        ) {
            // Token replacement implementation
        }
    })

InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
        .authTokenProvider(new TokenProvider() {
            @Override
            public void provideTokenReplacement(@Nullable String oldAuthToken, @NonNull String userIdentifier, @NonNull TokenProvider.OnTokenProviderListener listener) {
                // Token replacement implementation
            }
        });

Optional Initialization Configuration: Event Listener

• SDK events can be monitored by providing an Event Listener during initialization. A class which implements OnTrackEventListener can be passed into the InitializationBuilder. SDK events will trigger the .trackEvent() method in said class.

builder.onTrackEventListener(object : OnTrackEventListener {
        override fun trackEvent(
            event: AnalyticsEvent?,
            attributes: MutableMap<String, Any>?,
            superAttributes: MutableMap<String, Any>?
        ) {
            // Track Event
        }
        override fun onDestroy() {
            // Handle Tracker Destruction
        }
    })

InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
        .onTrackEventListener(new OnTrackEventListener() {
            @Override
            public void trackEvent(AnalyticsEvent event, Map<String, Object> attributes, Map<String, Object> superAttributes) {
                // Track Event
            }
            @Override
            public void onDestroy() {
                // Handle Tracker Destruction
            }
        });

Optional Initialization Configuration: SDK Functional Customization

• Additional SDK functional customizations can be made via SBFunctionalConfiguration. Set the desired functionality flags, then pass the configuration object to the InitializationBuilder.

builder.configuration(
    FunctionalConfiguration().apply {
        functionalConfiguration.apply {
            enableSecureWindow = true
        }
    }
)

FunctionalConfiguration config = new FunctionalConfiguration();
// Example: Disable screen recording
config.getFunctionalConfiguration().setEnableSecureWindow(false);
InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
        .configuration(config);

Build and Initialize

Once the InitializationBuilder object is created and optional configurations are provided, it can be built by calling builder.build() and passed to the SensibillSDK.initialize() method along with an SDKInitializeListener. NOTE: By the Sensibill SDK lifecycle rules, if SensibillSDK.initialize() and / or SensibillSDK.start() have already been called in this instance of the app, SensibillSDK.release() should be called before re-initializing. See below for example:

SensibillSDK.initialize(builder.build(), object : SDKInitializeListener {
    override fun onInitialized() {
        // Handle initialization success
    }
    override fun onInitializationFailed() {
        // Handle initialization failure
    }
})

SensibillSDK.getInstance().initialize(builder.build(), new SDKInitializeListener() {
    @Override
    public void onInitialized() {
        // Handle initialization success
    }
    @Override
    public void onInitializationFailed() {
        // Handle initialization failure
    }
});

NOTE: Due to its asynchronous nature and potential time to complete, the initialize function has been changed to also require a listener. It is still possible to call SensibillSDK.initalize(Initializer), however this functionality is now deprecated and will soon be removed.

Starting the SDK

Once the SDK has been initialized, it can then be started with SensibillSDK.start().

Note: the userIdentifier you provide to .start() will be the one passed to your TokenProvider when the SDK requests new tokens.

val userIdentifier = "currentUser"
SensibillSDK.start(userIdentifier, object : SDKStartup {
    override fun onSDKStarted() {
        // The SDK has successfully started.  All functionality can now be safely used.
    }

    override fun onSDKFailed(loginError: LoginError?, errorMessage: String?) {
        // The SDK failed to start.  This may be because it has not been initialized yet, or the `TokenProvider`
        // was not able to provide a token.  See `loginError` for details
    }
})

final String userIdentifier = "currentUser";
SensibillSDK.getInstance().start(userIdentifier, new SDKStartup() {
    @Override
    public void onSDKStarted() {
        // The SDK has successfully started.  All functionality can now be safely used.
    }

    @Override
    public void onSDKFailed(LoginError loginError, String errorMessage) {
        // The SDK failed to start.  This may be because it has not been initialized yet, or the `TokenProvider`
        // was not able to provide a token.  See `loginError` for details
    }
});

Stopping the SDK

Once Sensibill SDK functionality is no longer being used, the SDK should be stopped in order to free up resources.

Also, if a change in users must occur, the SDK should also be stopped and fully reinitialized.

To stop the SDK call SensibillSDK.release().

SensibillSDK.release()

SensibillSDK.getInstance().release();