SDK Initialization

SDK Lifecycle

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:

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 using the InitializationBuilder to create a builder object which will be used to initialize the SDK, by providing the application context and Sensibill DefaultEnvironment

  • InitializationBuilder builder = new InitializationBuilder(context, sensibill_env)

  • Parameters:

    Name	Description
    context	Application Context
    sensibill_env	An enum conforming to the DefaultEnvironment type. This specifies what external Sensibill environment you wish your application to access. Example DefaultEnvironment.BETA_SANDBOX

• InitializationBuilder can be extended to provide SDK customization and monitoring. Extensions are optional
  
  

Initialization Extension: SDK Lifecycle Listener

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

Java

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

Kotlin

val builder = InitializationBuilder(applicationContext, DefaultEnvironment.BETA_SANDBOX)
    .activityLifecycle(object : AbstractActivityLifecycleListener() {
        // implement methods here
    })

Initialization Extension: Token Provider

• Custom token provider can be applied to the SDK by providing an Auth Token Provider. When session time runs out or token is invalid, SDK will use this token provider to retrieve a new token.
• Strategy for providing tokens depends on the Authentication strategy (ie, On-Device Authentication vs Integration Server Authentication). For more detail on authentication: Authentication Strategy
• 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.

Java

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

Kotlin

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

Initialization Extension: Event Listener

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

Java

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

Kotlin

val builder = InitializationBuilder(applicationContext, DefaultEnvironment.BETA_SANDBOX)
    .onTrackEventListener(object : OnTrackEventListener {
        override fun trackEvent(
            event: AnalyticsEvent?,
            attributes: MutableMap<String, Any>?,
            superAttributes: MutableMap<String, Any>?
        ) {
            // Track Event
        }

        override fun onDestroy() {
            // Handle Tracker Destruction
        }
    })

Initialization Extension: SDK Functional Customization

• Additional SDK functional customizations can be made via FunctionalConfiguration. Set desired functionality, and pass to initialization builder.

Java

FunctionalConfiguration config = new FunctionalConfiguration();
// Example: Disable Exports
config.getFunctionalConfiguration().setEnableExports(false);

InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
        .configuration(config);

Kotlin

val builder = InitializationBuilder(applicationContext, DefaultEnvironment.BETA_SANDBOX)
    .configuration(FunctionalConfiguration().apply {
        functionalConfiguration.apply {
            // Example: Disable Exports 
            enableExports = false
        }
    })

Setting	SDK Effect	Type
setEnablePaymentFilter	show/hide Payment filter in search, default will show payment filter	Boolean
setEnableReceiptEmail	show/hide receipt email in receipt list, will show receipt email	Boolean
setEnableFolderSorting	show/hide sorting in folder receipt list, default will show	Boolean
setEnableNotes	show/hide notes, default will show	Boolean
setEnableTags	show/hide user tags in notes, default will show	Boolean
setEnableExports	show/hide exports, default will show	Boolean
setShowSearchInReceiptList	show/hide search in sort in the receipt list, default will show	Boolean
setEnableCurrencyFilter	show/hide currency filter in search, default will show currency filter	Boolean
setReceiptEmailDisplayDomain	set custom domain for receipt email registration	String
setEnableAchievementFeedback	Determines if user achievement feedback will be presented to users. Default value: True. Note: Achievement feedback dialogs will only display at maximum once. To reset this, clear the app’s defaultSharedPreferences	Boolean
setEnableSecureWindow	Determines if the SDK activities will be visible to screen recording. Defaults to false.	Boolean

Build and Initialize

Once the InitializationBuilder object is created and optional extensions are added, 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:

Java

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

    @Override
    public void onInitializationFailed() {
        // Handle initialization failure
    }
});

Kotlin

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

    override fun 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.