Ingo SDK version: 7.1.0
7.1.0 release21 or greater33 or greater33 or greater7.5 or greater1.8.20
1.4.6IngoSdk.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.0 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.0.0.
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.activityCompose)
implementation(IngoSdk.Dependency.Android.accompanistDrawablePainter)
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 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)
ingoSdkUx module as source codeCopy the ingoSdkUx module to the root directory of the application and reference it by adding the following declaration in settings.gradle.kts:
include(":ingoSdkUx")
Then add the ingoSdkUx module to the application's build.gradle.kts file:
implementation(project(":ingoSdkUx"))
ingoSharedSdk module as AAR fileCreate a directory named ingoSharedSdk in the root directory of the application and add to it the ingo-sharedSdk-release.aar file.
Then in the same ingoSharedSdk directory, create a file named build.gradle with the following declarations:
configurations.maybeCreate("default")
artifacts.add("default", file('ingo-sharedSdk-release.aar'))
Reference this as a module in settings.gradle.kts
include(":ingoSharedSdk")
Then add the ingoSharedSdk module to the application's build.gradle.kts file:
implementation(project(":ingoSharedSdk"))
build.gradle.kts fileThere are three options to integrate the remaining required binary dependencies.
ingo_libs under the application target and reference them with a wildcard directive 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"))
ingo-sharedSdk-release.aar file may be used for all AAR files comprising the Ingo Money Mobile SDK in order to avoid duplicating AARs across modules in the project if there are multiple application variants.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. The Ingo Money Mobile SDK Sample Application provides a working example of how the implementing application's servers should interact with the Ingo Money Mobile Check Cashing SDK Enrollment API. 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 an optional parameter to serialize and pass on the IngoSdkActivity intent. To modify the colors, create an IngoSdkTheme with IngoSdkColorTheme parameters for light and dark modes and encode it to JSON, and pass the encoded object on the launch intent using the THEME key.
//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")
)
)
)
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. 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
)
)
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 SDK utilizes a modular architecture. By including the ingoSdkUx module as source code, developers have access to a ViewProvider implementation and the Jetpack Composables used for each Fragment screen in the SDK, except for those contained in the MiTek MiSnap module. Developers can modify the source code of each Fragment's UX layer if the standard theming available does not satisfy the requirements for the implementing application. It should be noted that other aspects of the SDK (e.g. navigation actions, return results, etc.) cannot or should not be modified. Do not remove or hide Ingo Money legal disclaimers when modifying. Modifications are subject to Ingo Money review and approval.
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.