Android SDK

The Accrue Savings Android SDK is available as a package for your company to integrate the Accrue Wallet.

It simplifies the integration by combining the Wallet lifecycle and deep linking into a single package.

Installation

Your package is available as a Package on Github package repository.

To install it you need to add the following to your build.gradle.kts file:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/accrue-savings/android-sdk")
            credentials {
                username = System.getenv("GITHUB_USERNAME")
                password = System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

You need to set the GITHUB_USERNAME and GITHUB_TOKEN environment variables. Any Github user can generate a token here. It only needs read:packages permission to read packages. But, you can also use the token provided by us:

export GITHUB_USERNAME="accruesavings"
export GITHUB_TOKEN="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"

And then add the dependency to your build.gradle.kts file:

dependencies {
    implementation("com.accruesavings:androidsdk:v1.0.0")
}

Usage

Here is an example of how to embed the widget in a Android application:

val userData = AccrueUserData(
    referenceId = "<your_unique_user_id>", // Deprecated — use stableReferenceId instead
    stableReferenceId = "<your_stable_user_id>", // Always set for new integrations (immutable once set). Legacy merchants may omit during transition.
    phoneNumber = "<users_phone_number>",
    email = "<users_email>",
    additionalData = mapOf(
        "key" to "value"
    )
)

val settingsData = AccrueSettingsData(
    shouldInheritAuthentication = true
)

val contextData = AccrueContextData(userData, settingsData)

val fragment = AccrueWallet.newInstance(
    contextData = contextData,
    redirectionToken = redirectionToken,
    isSandbox = true,
    merchantId = merchantId,
    onAction = mapOf(
        AccrueAction.SignInButtonClicked to {
            // Handle sign in button click
        },
        AccrueAction.RegisterButtonClicked to {
            // Handle register button click
        }
    )
)

supportFragmentManager.beginTransaction()
    .replace(R.id.fragment_container, fragment)
    .commit()

Props

The following props are available for the AccrueWallet component:

merchantId
Required	Yes
Type	String
Description	Merchant ID (received from Accrue)
Default	N/A
Example	724a57f2-1670-42de-b1f0-a94425fb60cf
redirectionToken
Required	No
Type	String
Description	Redirection token for the deep linking. This token will be used to redirect the user to a specific screen within the Accrue Savings Widget
Default	null
Example	61a77652-14ae-4ed4-9bb3-cdb31312869e
isSandbox
Required	No
Type	Boolean
Description	Flag to enable the sandbox mode. If set to true, the widget will use the sandbox environment
Default	true
Example	true
contextData
Required	yes
Type	ContextData(userData: AccrueUserData, settingsData: AccrueSettingsData)
Description	Your own user data to be attached to the user profile stored with Accrue. AccrueUserData supports stableReferenceId (required for new integrations; immutable once set), referenceId (deprecated), email, phoneNumber, and additionalData.
Default	null
Example	ContextData(AccrueUserData(referenceId = "legacy-id", stableReferenceId = "stable-abc-123", phoneNumber = "+1...", email = "a@b.com"), AccrueSettingsData())
onAction
Required	No
Type	Map<AccrueAction, () -> Unit>
Description	Callback with actions triggered by the user
Default	emptyMap()
Example	mapOf( AccrueAction.SignInButtonClicked to { // Handle sign in button click }, AccrueAction.RegisterButtonClicked to { // Handle register button click } )

ContextData

The ContextData struct is used to pass the user data and settings data to the widget.

AccrueUserData

The AccrueUserData struct is used to pass the user data to the widget. The following fields are available:

referenceId
Required	No
Type	String
Description	Deprecated. Use stableReferenceId instead. A unique reference id for the user. Immutable once set.
Default	N/A
Example	123e4567-e89b-12d3-a456-426614174000
stableReferenceId
Required	Yes
Type	String
Description	Stable merchant-scoped user ID. All new integrations must provide this (immutable once set). Omit only while completing migration from referenceId. When set, becomes the effectiveReferenceId.
Default	N/A
Example	stable-abc-123
email
Required	No
Type	String
Description	User email
Default	N/A
Example	email@example.com
phoneNumber
Required	Yes
Type	String
Description	User US phone number
Default	N/A
Example	+12125559999
additionalData
Required	No
Type	Map<String, String>
Description	Additional data to be attached to the user profile stored with Accrue. Currently we are listening to firstName and lastName keys but it will be expanded in the future.
Default	emptyMap()
Example	mapOf( "firstName" to "John", "lastName" to "Doe" )

AccrueSettingsData

The AccrueSettingsData struct is used to pass the settings data to the widget. The following fields are available:

shouldInheritAuthentication
Required	No
Type	Boolean
Description	Should the widget inherit the authentication from the parent app
Default	true
Example	true

⚠️ Important: Keep in mind that the shouldInheritAuthentication will change the behavior of the widget.

The following UX changes will occur:

• We will use the phoneNumber passed as props to auto-send the OTP to the user if not already authenticated on the widget.
• We will use the referenceId and/or stableReferenceId you pass as the merchant-side user identity. If either is present, we consider the user authenticated on your side; otherwise we consider them unauthenticated.
• Once user confirms the OTP, we will consider the user as authenticated on the widget.
• If referenceId or stableReferenceId changes, the user will be logged out from the widget.

Considerations:

• The user would not be able to change the phone number in the widget.
• The user would not be able to logout from the widget (unless the merchant identity you pass changes — referenceId or stableReferenceId).
• The user would not be able to change the email in the widget.
• All phoneNumber/email changes should be handled on the merchant side.

Actions

Actions are emitted from the webview in the form of a string. The onAction callback will be triggered with the action as a parameter.

The following actions are available:

• SignInButtonClicked: The user clicked the sign-in button
• RegisterButtonClicked: The user clicked the register button

Updating context data

If you need to update the context data at any time — for example, after the user has authenticated in your application — call updateContextData on the AccrueWallet instance. It sends a JavaScript event to the WebView that the embedded widget handles. Include stableReferenceId for new integrations (same rules as the initial AccrueUserData).

val updatedUserData = AccrueUserData(
    referenceId = "<your_unique_user_id>", // Deprecated — use stableReferenceId instead
    stableReferenceId = "<your_stable_user_id>", // Always set for new integrations (immutable once set)
    phoneNumber = "<users_phone_number>",
    email = "<users_email>",
    additionalData = mapOf("firstName" to "John", "lastName" to "Doe")
)
val updatedSettings = AccrueSettingsData(shouldInheritAuthentication = true)
val updatedContext = AccrueContextData(updatedUserData, updatedSettings)

fragment.updateContextData(updatedContext)

Use the same AccrueWallet fragment instance you created with AccrueWallet.newInstance.

Sending events to the widget

You can send events to the widget by calling the handleEvent method on the AccrueWallet instance. It will send a javascript event to the webview that will be handled by the embedded widget.

Currently, supported events are:

• AccrueTabPressed: The user pressed the tab button in the app where the widget is embedded.