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, three arguments are required:

See the InitializationBuilder Reference for full documentation.

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

val builder = InitializationBuilder(applicationContext, DefaultEnvironment.RECEIPTS_SANDBOX, tokenProvider)

final TokenProvider tokenProvider = new TokenProvider() {
    @Override
    public void provideTokenReplacement(@Nullable String oldAuthToken, @NonNull String userIdentifier, @NonNull TokenProvider.OnTokenProviderListener listener) {
        // Token replacement implementation
    }
}

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

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
            }
        });

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();