Ingo SDK version: 7.1.1
Release Date: 10.5.2023
Note: Documentation for prior versions may be found by using the search bar above.
minSdk level of 23 or greatertargetSdk level of 33 or greatercompileSdk level of 33 or greater7.5 or greater1.8.20
1.4.65.3.3IngoSdk.kt and IngoPlugins.kt with the new versions or other means to match the versions in distribution package.Ingo Money Mobile SDK version 7.1.1 has a new dependency structure and a new API compared to previous versions. It is recommended to completely remove all references to older Ingo Money Mobile SDK dependencies from both the build scripts and from source code before attempting to integrate Ingo Money SDK version 7.1.1.
The Ingo Money Mobile SDK relies on Google/Android, third party open source, and proprietary libraries to facilitate an end user's interaction with the Ingo Money service. Google/Android and third party dependency versions may vary based upon the implementing application's requirements. Please refer to the sample application for a working example with specific dependency versions.
If the implementing application is already utilizing a buildSrc directory to enable kotlin-dsl then add the IngoSdk.kt and IngoPlugins.kt files to your existing module.
If the implementing application is not already utilizing a buildSrc directory, then copy the buildSrc folder into your application's root directory. It will automatically be treated as an included build.
Alternatively, the content of IngoSdk.kt and IngoPlugins.kt can be copied directly into the application's build.gradle.kts or the dependency/version strings can be manually extracted.
Ingo Money does not support a Groovy based example at this time.
build.gradle.kts file //google/android project dependencies required for Ingo Money SDK
implementation(IngoSdk.Dependency.Android.composeUi)
implementation(IngoSdk.Dependency.Android.composeMaterial)
implementation(IngoSdk.Dependency.Android.lifecycleRuntimeKtx)
implementation(IngoSdk.Dependency.Android.accompanistDrawablePainter)
implementation(IngoSdk.Dependency.Android.activityCompose)
implementation(IngoSdk.Dependency.Android.appcompat)
implementation(IngoSdk.Dependency.Android.constraintLayout)
implementation(IngoSdk.Dependency.Android.navigationFragment)
implementation(IngoSdk.Dependency.Android.material)
implementation(IngoSdk.Dependency.Android.googlePlayServicesLocation)
implementation(IngoSdk.Dependency.Android.cameraCore)
implementation(IngoSdk.Dependency.Android.camera2)
implementation(IngoSdk.Dependency.Android.cameraLifecycle)
implementation(IngoSdk.Dependency.Android.cameraVideo)
implementation(IngoSdk.Dependency.Android.cameraView)
implementation(IngoSdk.Dependency.Android.cameraExtensions)
implementation(IngoSdk.Dependency.Android.exifInterface)
build.gradle.kts fileThere are two options to integrate the required binary dependencies.
ingo_libs under the application target and reference them with a wildcard import the in the application's build.gradle.kts file. implementation(fileTree(mapOf("dir" to "ingo_libs", "include" to listOf("*.jar", "*.aar"))))
build.gradle.kts file individually. For each binary in the Ingo Money Mobile SDK distribution package, add an implementation statement to the application's build file.implementation(files("/path/to/dependency.aar"))
The Ingo Money Mobile SDK utilizes the MiTek MiSnap SDK in order to capture images of checks and other documents. The MiTek MiSnap SDK is distributed via a GitHub hosted Maven repository, which requires a GitHub account and subsequent Personal Access Token for access. Please see this link for more details on creating a Personal Access Token and adding the repository to the application's Gradle configuration.
These credentials are necessary to also build and run the Ingo Money Mobile SDK sample application. Once credentials are created, they will need to be set in the sample application's settings.gradle.kts file.
// example repository declaration to integrate MiTek MiSnap GitHub Maven Repository into the application's Gradle configuration
allProjects {
repositories {
...
maven {
url = uri('https://maven.pkg.github.com/mitek-systems/misnap-android')
credentials {
username = 'your-github-username'
password = 'personal-access-token' // created in Step 1.
}
}
}
}
If your application does not have access to a remote Maven repository, please contact Ingo Money Client Services to request access to an offline MiSnap SDK that can be loaded into the local Maven repository of the machine that's building the application.
build.gradle.kts file implementation(IngoSdk.Dependency.Common.ktorClientCore)
implementation(IngoSdk.Dependency.Common.ktorContentNegotiation)
implementation(IngoSdk.Dependency.Common.ktorClientSerialization)
implementation(IngoSdk.Dependency.Common.ktorClientLogging)
implementation(IngoSdk.Dependency.Common.kotlinxSerialization)
implementation(IngoSdk.Dependency.Common.kotlinxSerializationJson)
implementation(IngoSdk.Dependency.Common.koinCore)
implementation(IngoSdk.Dependency.Android.ktor)
implementation(IngoSdk.Dependency.Android.koin)
implementation(IngoSdk.Dependency.Android.greenRobotEventBus)
implementation(IngoSdk.Dependency.Android.commonsImaging)
implementation(IngoSdk.Dependency.Android.slf4j)
implementation(IngoSdk.Dependency.Android.mitekDocument)
The Ingo Money Mobile SDK for Android utilizes the KotlinX serialization library and requires the addition of certain proguard rules in order to prevent required classes from being shrunk or removed. Please refer to the KotlinX serialization documentation for the required proguard rules.
Invocation of the Ingo Money SDK is comprised of 4 steps
The Ingo Money Mobile SDK requires an authorization token and customer identifier to interact with the Ingo Money service, both of which are securely retrieved via a server to server authentication mechanism. Please refer to the Ingo Money Mobile Check Cashing SDK Enrollment API documentation for details on enrolling and authenticating an end user in the Ingo Money Service. Once the implementing application retrieves these values from its own API, the Ingo Money Mobile SDK can be configured and launched. Please note that the authorization token returned by the API is single use, and can only be used for one invocation of the Ingo Money SDK.
The Ingo Money Mobile SDK requires a device specific identifier generated by the TransUnion Device Risk SDK in order to interact with Ingo Money Service. The Ingo Money Mobile SDK does not rely on a specific version of this library in order to prevent API conflicts, and it is the implementing application's responsibility to add and maintain this dependency.
//Generate TransUnion device blackbox for fraud prevention use from invoking Activity
val blackbox = FraudForceManager.getInstance().getBlackbox(this)
Launch the Ingo Money Mobile SDK Android Activity with the arguments generated in steps 1 and 2, the base URL for the Ingo Money API in the desired environment (UAT/Production), and provide additional UX customizations as desired.
NOTE: Do not launch the SDK multiple times with the same authorization token, as subseqent invocations it will result in a 403 Forbidden error. It is not recommended to launch the SDK from an Android lifecycle callback such as onResume because these callbacks can be executed multiple times, even if the invoking component is not visible at the top of the stack of the running Android task.
//Create an intent to launch IngoSdkActivity
val intent = Intent(this, IngoSdkActivity::class.java)
//Add the minimum required arguments. Make sure these string extras are not blank.
intent.putExtra(IngoSdkActivity.INGO_BASE_URL, getString(R.string.ingo_base_url))
intent.putExtra(IngoSdkActivity.SDK_AUTHORIZATION_TOKEN, sdkAuthorizationToken)
intent.putExtra(IngoSdkActivity.CUSTOMER_IDENTIFIER, customerId)
intent.putExtra(IngoSdkActivity.FRAUDFORCE_DEVICE_BLACKBOX, blackbox)
//Register a result contract and launch the Ingo Money Mobile SDK Activity (https://developer.android.com/training/basics/intents/result)
ingoActivityResultContract.launch(intent)
customerId value returned from the server to server register customer API call.sdkAuthorizationToken is the sessionID header value returned from the server to server AuthenticatePartner API call.getBlackbox() function.By default, logging is disabled in the Ingo Money Mobile SDK. To enable logging of all HTTP requests and responses as well as other debug and error information, add the IS_LOGGING_ENABLED key to the launch intent with a boolean value of true.
intent.putExtra(IngoSdkActivity.IS_LOGGING_ENABLED, true) //enables logging
The Ingo Money Mobile SDK uses a light/dark mode compatible theme object in order to style the user experience using Jetpack Compose Material Themes.
It is recommended to configure this theme at compile time using the colors.xml file. Both light and dark mode values need to be added to the main colors.xml file, not split across multiple resources directories with added qualifiers.
Example app/src/main/res/values/color.xml file
<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="ingo_sdk_theme_light_primary">#1C1C1E</color>
<color name="ingo_sdk_theme_light_secondary">#23AD4B</color>
<color name="ingo_sdk_theme_light_tertiary">#cccccc</color>
<color name="ingo_sdk_theme_light_background">#FFFFFF</color>
<color name="ingo_sdk_theme_light_secondary_background">#F6F7F8</color>
<color name="ingo_sdk_theme_light_primary_inverse_text">#FFFFFF</color>
<color name="ingo_sdk_theme_light_alert">#F3CA3E</color>
<color name="ingo_sdk_theme_light_error">#FF0000</color>
<color name="ingo_sdk_theme_dark_primary">#FFFFFF</color>
<color name="ingo_sdk_theme_dark_secondary">#23AD4B</color>
<color name="ingo_sdk_theme_dark_tertiary">#cccccc</color>
<color name="ingo_sdk_theme_dark_background">#1C1C1E</color>
<color name="ingo_sdk_theme_dark_secondary_background">#2C2C2E</color>
<color name="ingo_sdk_theme_dark_primary_inverse_text">#1C1C1E</color>
<color name="ingo_sdk_theme_dark_alert">#F3CA3E</color>
<color name="ingo_sdk_theme_dark_error">#FF0000</color>
</resources>
To configure the theme at run time, instantiate an IngoSdkTheme object with IngoSdkColorTheme parameters for light and dark modes. Serialize the object to a JSON string, and add it as an extra to the IngoSdkActivity intent using the THEME key. This object will takes precedence over any values configured in the colors.xml file.
It should be noted that this override only applies to UX outside of the camera experience used to capture images, which can only be customized via XML at compile time.
Example of overriding default theme values using a KotlinX JSON serializer
intent.putExtra(
IngoSdkActivity.THEME,
Json.encodeToString(
IngoSdkTheme(
light = IngoSdkColorTheme(primaryColor = "#000000))"),
dark = IngoSdkColorTheme(primaryColor = "#FFFFFFFF")
)
)
)
For detailed information on how these theming keys are applied to the Ingo Money Mobile SDK UX please reference the Figma file included in the distribution, but a brief overview is as follows (light mode):
ingo_sdk_theme_light_primary / ingo_sdk_theme_dark_primary
ingo_sdk_theme_light_secondary / ingo_sdk_theme_dark_secondary
ingo_sdk_theme_light_tertiary / ingo_sdk_theme_dark_tertiary
ingo_sdk_theme_light_background / ingo_sdk_theme_dark_background
ingo_sdk_theme_light_secondary_background / ingo_sdk_theme_dark_secondary_background
ingo_sdk_theme_light_primary_inverse_text / ingo_sdk_theme_dark_primary_inverse_text
ingo_sdk_theme_light_alert / ingo_sdk_theme_dark_alert
ingo_sdk_theme_light_error / ingo_sdk_theme_light_error
By default, the Ingo Money Mobile SDK supports a configurable dark mode theme. If the implementing application does not support dark mode or wishes to suppress it for the within the Ingo Money Mobile SDK, add the IS_DARK_MODE_ALLOWED key to the launch intent with a boolean value of false. Ensure to also override the Theme.IngoSdk value in the application level styles.xml to ensure the IngoSdkActivity inherits from an appropriate light mode only theme.
//Disable Dark Mode Support, use this in combination with overriding Theme.IngoSdk (see styles.xml)
// setting this extra to false will call AppCompatDelegate and set MODE_NIGHT_NO
intent.putExtra(IngoSdkActivity.IS_DARK_MODE_ALLOWED, false)
By default, the promotion code entry is enabled in the Ingo Money Mobile SDK. To disallow entering of promotion codes and hide the associated UI elements, add the PROMO_CODE_ENABLED key to the launch intent with a boolean value of false.
intent.putExtra(IngoSdkActivity.PROMO_CODE_ENTRY_ENABLED, false) //hide promo code button
The Ingo Money Mobile SDK utilizes the Jetpack Compose Typography API in order to easily customize fonts throughout the user experience with the exception of camera experience. Simply override the IngoTypography variable before launching the IngoSdkActivity intent.
/* override material typography styles */
IngoTypography = Typography(
body1 = TextStyle(
fontFamily = FontFamily.Default,
fontWeight = FontWeight.Normal,
fontSize = 12.sp
)
)
Fonts and other text attributes within the camera experience can be customized at compile time by overriding the following XML styles. Note that the application will have to override the styles in all applicable resource configurations (e.g. both the values folder and the values-night folder in order to properly display when dark mode is enabled).
<style name="MiSnapTheme.TextAppearance.Headline.Medium" parent="@style/TextAppearance.AppCompat.Medium">
<!-- Customization Attributes -->
</style>
<style name="MiSnapTheme.TextAppearance.HintView" parent="@style/TextAppearance.MaterialComponents.Headline4">
<!-- Customization Attributes -->
</style>
<style name="MiSnapTheme.TextAppearance.Medium" parent="@style/TextAppearance.AppCompat.Medium">
<!-- Customization Attributes -->
</style>
<style name="MiSnapTheme.TextAppearance.SuccessView" parent="@style/TextAppearance.MaterialComponents.Headline2">
<!-- Customization Attributes -->
</style>
The Ingo Money Mobile SDK utilizes vector graphics with a tint supplied by theIngoSdkTheme object. In order to override the default icons, replace drawables with resources of the same name in the implementing application module (e.g. to change the "success" icon, provide a drawable named ic_success_status_icon.xml in the application's resources).
In order to replace the default iconography with icons that utilize multiple colors, add the ICON_TINT_ENABLED key to the launch intent with a value of false which disables theme tinting for all icons throughout the Ingo Money Mobile SDK. If multi-color icons are required in your implementation, it is recommended to override all of the drawables packaged with the SDK that are prefaced with ic_.
The Ingo Money SDK API and Mobile SDK support associating multiple card and tokenized accounts to a single customer. By default, the customer first be presented a selection list if there are more than one destination account associated to their identifier. If it is known to your application where the customer wants to move their funds, this step may be skipped by inputting the desired account identifier when launching the Mobile SDK by using the ACCOUNT_TO_FUND Intent extra.
intent.putExtra(IngoSdkActivity.ACCOUNT_TO_FUND, "DESIRED-ACCOUNT-GUID-FROM-INGO-SDK-API") //skip account selection if more than one associated to a customer
The Ingo Money Mobile Android SDK uses the Android standard activity result API to deliver an object detailing result of the user experience.
If the resultCode returned is RESULT_OK, the Ingo Money Mobile SDK exited on a known condition. Otherwise, the Ingo Money Mobile SDK activity was finished for an unknown reason or due to an unexpected error.
private val ingoActivityResultContract =
registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { activityResult ->
if (activityResult.resultCode == Activity.RESULT_OK) {
Log.d("Ingo SDK Sample", "Ingo SDK Returned Result \"OK\"")
Log.d(
"Ingo SDK Sample",
"Ingo Result Was " + activityResult.data?.getStringExtra(KEY_INGO_RESULT)
)
val jsonString = activityResult.data?.getStringExtra(KEY_INGO_RESULT)
if (jsonString != null) {
val ingoSdkResultObject = IngoSdkResultDeserializer.deserialize(jsonString)
Log.d("Ingo SDK Sample App", "Deserialized Result: $ingoSdkResultObject")
}
} else {
Log.e("Ingo SDK Sample", "Ingo SDK DID NOT RETURN Result \"OK\"")
}
}
The implementing application can inspect and deserialize a result value in the case of the IngoSdkActivity returning RESULT_OK in order to determine the end user's experience in the Ingo Money Mobile SDK. The result is returned as a JSON formatted string, accessed with the key KEY_INGO_RESULT. The Ingo Money Mobile SDK provides a helper class (IngoSdkResultDeserializer) to decode this string into an object for inspection.
All SDK result objects have the following attributes:
| Field Name | Type | Validations | Description |
|---|---|---|---|
| exitCode | String | Not Null | The reason the SDK exited (e.g. CUSTOMER_EXIT_SDK, SESSION_TIMEOUT) |
| exitOnUTC | Long | Not Null | The UTC time at SDK Exit |
| customerIdentifier | String | Not Null | The Ingo customer identifier associated with the SDK session |
| transactionReferenceNumber | String | Nullable | The Ingo transaction reference number associated to the SDK session if available |
| title | String | Not Null | Human readable title of the result event |
| detail | String | Not Null | Human readable details of the result event |
| lastModule | String | Not Null | Last screen / module displayed to the user |
Some exit cases will have additional fields and details to further describe exit conditions.
Ingo Money provides a sample application in order to illustrate the integration, configuration, and launching of the Ingo Money SDK.
In order to run the sample application, a Github username and personal access token (refer to step 4 of the dependency setup section) must be entered into the sample application's settings.gradle.kts file. Additionally, in order to enable the MiTek camera experience the applicationId of the sample application must be updated in the /app/build.gradle.kts file to match the applicationId that will be used in production to pass MiTek license verification.