SDK Configuration

When you have successfully added the SDK screen into your app, you will need to configure the SDK. Configuration will ensure the proper URL and headers are in use.

First, you will need to set your Bank BE URL via Configuration.api.urlHost = "https://your_bank_BE". For security reasons make sure that the connection use HTTPS, otherwise an exception will be thrown.

Next, set your app identification like this:

Configuration.setDeviceInformation(
    deviceType = "mobile android",
    deviceUserAgent = "BANK_NAME_APP [version X.Y.Z]"
)

Make sure that you set these parameters correctly, as this will help us solve potential issues and identify requests by platform. mobile android is a static value and should not be changed. BANK_NAME_APP [version X.Y.Z] should contain your application or bank name and app version. The exact format is not required and depends on your preferences. Setting user device information is also helpful.

By Configuration.setIsLocationEnabled(bool) you will set up if to use user location or not. For this purpose, we use standard Google Play services. User need to grant permission to it, if it was not given before.

Working with user token

Authorization is done by setting user authentication in the headers. This header is configurable by name and value. Format of this header depends on the bank’s preferences and infrastructure (see Communication with bank backend and Dateio API). SDK offers two methods for user identification. One for long-lasting tokens and another for short-lived ones.

For long-lasting tokens headers can be set as follows:

Configuration.setCustomHttpRequestHeaders( 
    mapOf( 
        "Authorization" to "some token", 
    ) 
)

If your token needs to be refreshed (e.g. they are valid only a few minutes), you should use this method instead:

Configuration.setRefreshAuthHeadersCallback { onRefreshAuthHeadersCallback -> 
    onRefreshAuthHeadersCallback.invoke( 
        mapOf( 
            "Authorization" to "some short-lived token", 
        ) 
    ) 
}

Where you can pass callback function, that’s return a map of headers that you want to set.

You can also use Configuration.setRefreshAuthHeadersCallback(callback: suspend (requestInfo: Map<String, String?>, authHeaders: (Map<String, String>) -> Unit) -> Unit) when you need requests info that the SDK generate. E.g. for PowerAuth.

Please note that this function is called before all requests. So, in this callback you should call your API / do refresh only if it's really needed, otherwise use the present token.

When you are configuring user tokens, you might add the "Accept-Language" to Locale.getDefault().language to set user preferred language. When an offer is available in this language, the API will return it instead of the default one.

Other SDK methods

This section describes other SDK functions and settings.

Configuration.setOnApiErrorCallback(Configuration.OnApiErrorCallback)

You can set a callback in case an API error occurs. This callback has two methods, one specifically for 401 authentication error and the other one for all the other types of errors:

Configuration.setOnApiErrorCallback(object  : Configuration.OnApiErrorCallback {
    override fun onAuthErrorCallback() {
        // Do something here, when 401 error occurred during an API call
    }

    override fun onGeneralApiError(errorCode : Int) {
        // Do something here in case other generic error occurred
    }
})

async RegisterUserToApiUseCaseDefault().execute()

Will register user on Dateio BE. This call is intended to be used once the user gives all consents with program usage. Returns true / false based on result. For details see user consents section.

async DeleteUserUseCaseDefault().execute()

Will delete the user on Dateio BE. Returns true / false based on result. For details see user consents section.

async LogoutUserUseCaseDefault().execute()

Will logout user on Dateio BE. Returns true / false based on result.

async DateioSDKCore.loadCashbackHistoryTotals(...)

To load cashback history totals outside of SDK screens use this method. This method returns a CashbackHistoryTotals object with the following parameters:

toPayTotal: Double
toPayTotalCurrency: String
paidTotal: Double
paidTotalCurrency: String

When you use this function you must authenticate the user before navigating within the SDK. This function should only be used for registered users.

Example how to use this function:

viewLifecycleOwner.lifecycleScope.launch {
    val data = DateioSDKCore.loadCashbackHistoryTotals(Dispatchers.IO)
    if(data == null) {
        binding.savedThisMonth = "Error"
        binding.savedTotal = "Error"
    } else {
        binding.savedThisMonth = "${data.toPayTotal} ${data.toPayTotalCurrency}"
        binding.savedTotal = "${data.paidTotal} ${data.paidTotalCurrency}"
    }   
}

Configuration.destroy()

Will free up all resources in the configuration object. Call this function when user logs out from bank application. This will clear SDK configuration and all its information. When this function is called, you will have to configure the SDK again for further use.

async OfferRepositoryDefault.loadNewOffersCount()

Will return number of new offers for user. This is intended for “red dot” use case.

Configuration.sslPins = mapOf("domain" to listOf(...))

Will use SSL hashes for the given domains. SDK will not trust other certificates. Please note, that when you set this parameter, you won't be able to use Configuration.sslInterceptor and Configuration.sslNetworkInterceptor. Interceptors will be ignored in this case.

This parameter should be used when you are targeting Android version below 24 as it is not possible to use network-security-config.

Configuration.sslInterceptor = listOf(...), Configuration.sslNetworkInterceptor = listOf(...)

You can set Interceptors with this when you need to use Certificate Transparency. Internally we set all interceptors as addInterceptor(it) and addNetworkInterceptor(it) fromOKHttpClient. These parameters will be ignored when you use Configuration.sslPins.

Configuration.processNotification(type, handler)

You can pass data from push notifications via this method to SDK. SDK will perform the given action e.g. redirect to detail and delete passed data. type is eu.dateio.dateiosdkmutliplatform.modules.offer.data.models.Notification instance defined by enum from NotificationType e.g. Notification(NotificationType.OPEN_OFFER_DETAIL, objectId = 16698940774). In some cases you need to pass objectId so SDK knows which offer or category should be redirected.

Notifications can trigger the following types of actions:

1. OPEN_OFFERS_LIST - will open SDK on offer list. Same if you navigate to SDK without processNotification.
2. OPEN_OFFER_DETAIL - will open offer detail. Need pass objectId as offer id.
3. OPEN_OFFER_HISTORY - will open user history with transactions.
4. OPEN_OFFER_CATEGORY - will open offers list in given category. Need pass objectId as category id.
5. OPEN_OFFER_MAP - will open a map with offers on it.
6. ACTIVATE_OFFER - use this type when you want directly activate offer without navigating to SDK. Need pass objectId as offer id. Note that you will still need to authenticate the user as usual.

When you set notification type OPEN_X then you just need to navigate into to SDK via handler. No other actions are needed and handler can be something like switchToSDK(). If you use ACTIVATE_OFFER your handler should perform activation itself via activationUseCase.executeDispatched(offerId, ActivationOfferSource.NOTIFICATION, Dispatchers.IO). This async function returns activated offer or null if activation failed.

This method is intended mainly for push notifications but might be used as well for in-app banners and others.

Configuration.setBankLoggerCallback(Configuration.BankLoggerCallback ...)

Allows the use of custom bank analytics based on user actions as described in the overview section. You need to override logAction(action: AnalyticsAction, origin: AnalyticsOrigin?, id: String?, info: String?) with custom logging e.g. batch logging, one action / one request logging or third-party solution.

It is important that this override in bank application offloads time-consuming actions like HTTPS requests from the UI thread otherwise it will block the application. For example with CoroutineScope(Dispatchers.IO).launch. You also need to handle error states appropriately. As Dateio doesn’t know how bank will implement custom logging it is not possible to do this in the SDK. Basically logAction is called inside SDK like this Configuration.getBankLoggerCallback?.logAction(...) without try or CoroutineScope change.

AnalyticsAction.PAGE_ENTER and AnalyticsAction.PAGE_LEAVE actions are called inside ViewModels in onPause and onResume. These ViewModels are observed via DefaultLifecycleObserver in SDK screens.

Configuration.allowedOfferTypes(listOf(...))

Will enable only some offer types - you might use values defined in eu.dateio.dateiosdkmutliplatform.modules.offer.data.models.OfferType.

This method should be used only after consultation with Dateio as this will reduce number of available offers.

Configuration.api.version = numericVersion

You can change SDK API version via Configuration.api.version = numericVersion. In case you change the API version, a warning will be logged, since this should be used only in edge cases.

This parameter should be used only after consulting with Dateio in advance, since it might cause errors when set incorrectly.

Configuration.offerDetailMainParts(listOf(...)) and Configuration.offerDetailHeaderParts(listOf(...))

By that you might sort blocks in offer detail screen. Dateio will provide configuration based on the agreed UI. Detail will be sorted by the exact same order as set in these lists. Some parts might be disabled when they are not in list. Only OfferDetailMainParts and OfferDetailHeaderParts values can be used.

Configuration.tutorialsType

You can set tutorial type with this. SDK supports these values:

• FOUR_OVERLAY_PAGES - there will be four overlay tutorials on homepage when user starts app for the first time.
• HOW_IT_WORKS_WIDGET - there will be widget with info on how program work above offers list. It will be shown until the user have some cashback.
• NONE - there will be no tutorial. Default value.

Configuration.howItWorksType

You can set type for how it works bottom sheet with this. SDK supports these values:

• BIG_WITH_IMAGES - bottom sheet with big images.
• BIG_WITH_OVERLAPPING_IMAGES - bottom sheet that has images overlaying text. Useful when you want to show steps like 1, 2, 3.
• SIMPLE_TEXT - simple bottom sheet with text only. Default value.

Configuration.addOfferTags(listOf(...))

You can set list of tags for offers to match this to allowed offers to the client. This might be useful when you have e.g. retail and SME users.

This method should be used only after consultation with Dateio as this will reduce the number of available offers.

Configuration.setShowNavigationBar

Callback for showing / hiding the tab bar in your host app. Tabbar is shown only on offers list when bottom sheet is not open. Otherwise it is hidden. You might use it like this:

Configuration.setShowNavigationBar { show ->
    if (show) {
        bottomNavigationView.animate().translationY(0f).setDuration(150)
            .withStartAction { bottomNavigationView.isVisible = true }
            .start()
    } else {
        bottomNavigationView.animate().translationY(56.toFloat()).setDuration(150)
            .withEndAction { bottomNavigationView.isVisible = false }
            .start()
    }