Skip to main content

​
Installation

The Android SDK is a set of lightweight libraries delivered as Android Archive Repository files, .aar. The minimum supported version of Android is v7, level 24.Prove manages a maven repository with Android binaries to enable integration with Gradle.Update the dependencies object in the build.gradle file:
dependencies {
    // Existing dependencies are here.

    // Add the Prove Link dependencies:
    implementation 'com.prove.sdk:proveauth:6.10.7'
}
Point to the repository by updating your settings.gradle file with the Maven repository:
dependencyResolutionManagement {
    // Existing repository settings are here.

    repositories {
        // Existing repositories are here.

        // Add the Prove Link Maven repository:
        maven {
            url = "https://prove.jfrog.io/artifactory/libs-public-maven/"
        }
    }
}
Add the following to the build.gradle file to also download dependency libraries:
dependencies {
    implementation fileTree('libs')
}
If you receive an error message on the application@fullBackupContent value, you can resolve it by adding this line of code to your application AndroidManifest.xml file inside the <application>...</application> node. Add it as an attribute to the opening application tag:
<application
...
tools:replace="android:fullBackupContent"
...>
</application>

​
Permissions

The Prove Auth SDK and its children SDKs merge the following permissions into the main app:
<!-- Required to perform authentication -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required to access information about networks -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Required for ConnectivityManager.requestNetwork -->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />

​
Send the type of flow: mobile

Unlike the Web SDK, when using the Android SDK, use the mobile flow. Pass mobile to the Unify() function on the server. In a mobile flow, the mobile phone performs OTP validation.In the mobile flow, once OTP validation is complete, the AuthFinishStep function executes.

​
Authenticate()

The SDK requires an authToken as a parameter for the Authenticate() function. This token returns from the Unify() call of the server SDK. The token is session specific, limiting it to a single flow. It also expires after 15 minutes.

​
Retrieve authToken

Send a request to your backend server with possession type, and an optional phone number if using the Prove possession check.
String initialize(String phoneNumber, String possessionType) {
    YourBackendClient backend = new YourBackendClient(); // Backend API client

    // TODO: Build your InitializeRequest object
    InitializeRequest initializeRequest = new InitializeRequest(phoneNumber, possessionType);

    // Send an initialize request to your backend server to get authToken
    InitializeResponse response = backend.initialize(initializeRequest);

    // TODO: define your own InitializeResponse object to parse authToken string
    return response.getAuthToken();
}

​
Setup authenticator

Once you have the authToken, build the authenticator for the mobile flow.
Java
// Object implementing AuthFinishStep interface
AuthFinishStep authFinishStep = new AuthFinishStep() {
...
};

// Objects implementing OtpStartStep/OtpFinishStep interfaces
OtpStartStep otpStartStep = new OtpStartStep() {
...
};

OtpFinishStep otpFinishStep = new OtpFinishStep() {
...
};

ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId)) 
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .build();
The mobile data connection can sometimes be unavailable during testing. The Builder class offers a withTestMode(boolean testMode) method. This method permits simulated successful session results while connected to a Wi-Fi network only. Testing using a Wi-Fi connection is useful in the Sandbox environment.
Java
ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId))
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .withTestMode(true) // Test mode flag
    .build();

​
Performing the authentication

The ProveAuth object is thread safe. You can use it as a singleton. Most Prove Auth methods are blocking and therefore can’t execute in the main app thread. The app employs an executor service with a minimum of two threads to manage threads due to the ability to process concurrent blocking requests.
public class MyAuthenticator {
    private final MyBackendClient backend = new MyBackendClient(); // Backend API client
    private ExecutorService executor = Executors.newCachedThreadPool();
    private final AuthFinishStep authFinishStep = new AuthFinishStep() {
        @Override
        void execute(String authId) {
            try {
                AuthFinishResponse response = backend.authFinish("My App", authId);
                ... // Check the authentication status returned in the response
            } catch (IOException e) {
                String failureCause = e.getCause() != null ? e.getCause().getMessage() : "Failed to request authentication results";
                // Authentication failed due to request failure
            }
        }
    };

    private ProveAuth proveAuth;

    public MyAuthenticator(Context context) {
        proveAuth = ProveAuth.builder()
            .withAuthFinishStep(authFinishStep)
                .withOtpFallback(otpStartStep, otpFinishStep)
            .withContext(context)
            .build();
    }

    public void authenticate() throws IOException, ProveAuthException {
        AuthStartResponse response = backend.authStart("My Prove Auth App");

        proveAuth.authenticate(response.getAuthToken());
    }
}

public void authenticate() throws IOException, ProveAuthException {
        // NOTE: blocking method proveAuth.authenticate() should be run in background thread
        executor.submit(() -> {
            AuthStartResponse response = backend.authStart("My Prove Auth App");
            proveAuth.authenticate(response.getAuthToken());
        }
}

​
Validate the mobile phone

In the AuthFinishStep, specify a function to call once the possession checks complete on the mobile phone. In the sample, notice an endpoint called /verify. This endpoint on your back end server calls the UnifyStatus() function to validate the phone number.
// Send a verify request to get return customer information.
void verify(String: authId) {
    YourBackendClient backend = new YourBackendClient(); // Backend API client

    // Build your VerifyRequest object
    VerifyRequest verifyRequest = new VerifyRequest(authId, ...);

    // Send a verify request to your backend server to get return customer information.
    VerifyResponse response = backend.verify(verifyRequest);
}

​
Configure OTP

To use the Resend/Retry/Phone Change features, install the Android SDK version 6.5.0 or later.
To set the One-Time Password (OTP) handler, withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep), requires implementing the OtpStartStep and OtpFinishStep.The OTP session has a two minute timeout from when it’s sent through SMS to when the customer can enter in the OTP.
Follow these instructions if you are implementing OTP and you are passing in the phone number on the /unify endpoint.Since you passed the phone number in the Unify() function, call OtpStartStepCallback.onSuccess(OtpStartInput); to communicate to the SDK you have the customer’s agreement to deliver the SMS message. Ensure you return an instance of OtpStartInput with empty string or null to OtpStartStepCallback.onSuccess() function.Call the OtpStartStepCallback.onError(); method to communicate to the SDK any issues while trying to obtain the phone number or the OTP. Report an error if the customer cancels the SMS transaction or presses the back button to leave the screen.In the finish step, call the OtpFinishStepCallback.onSuccess(OtpFinishInput); method to return the collected OTP value wrapped in OtpFinishInput.
Swift
class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}
Instant Link for Android is an add-on feature. To enable, contact your Prove representative.
To integrate Instant Link, review the technical prerequisites, followed by the required function calls, and finally the detailed configuration steps for different use cases.For the Instant Link flow to work in Android, the customer host app must receive a deep link. It must then redirect back to the original host app after the user taps the Instant Link in the SMS. It’s highly recommended to use App Links for Android apps. Full instructions: Supporting App Link in your app | Android developer documentation

​
Required functions

To set the Instant Link handler, withInstantLinkFallback(InstantLinkStartStep startStep, @Nullable InstantLinkRetryStep retryStep), requires implementing the InstantLinkStartStep protocol and optionally the InstantLinkRetryStep protocol if you wish for advanced capabilities. When returning the phone number, ensure you pass an InstantLinkStartInput with the mobileNumber field to the callback.The Instant Link session has a five minute timeout from when it’s sent through SMS to when the customer can click the received link.
Follow these instructions if you are implementing Instant Link and you are passing in the phone number in the initial server-side call. In this case, you’ve already prompted for a phone number so you don’t prompt for it in the client SDK.Since you passed the phone number, call callback.onSuccess(InstantLinkStartInput input) to communicate to the SDK you have the customer’s agreement to deliver the SMS message.
Java
InstantLinkStartStep noPromptStartStep = (phoneNumberNeeded, instantLinkError, callback) -> {
    // No phone number needed, no need to ask end user for input.
    if (!phoneNumberNeeded) {
        callback.onSuccess(new InstantLinkStartInput(""));
    }
};
The app must also call finishInstantLink(String redirectUrl) after the session redirects back to the app when the Instant Link click is complete.This redirect occurs after the following steps, which take place outside the customer host app:
  1. The end-user taps the Instant Link delivered via SMS.
  2. The end-user goes to a stand-alone website to complete Instant Link authentication.
  3. That page then redirects the user back to the original customer host app via the same deep link provided as the finalTargetUrl field in the earlier Start() server-to-server call. See: Server Integration Guide — Device Auth with Mobile Auth and Instant Link Fallback. Upon successful redirect back to the customer host app, the app must call finishInstantLink(String redirectUrl) to continue the session.
When and where to invoke finishInstantLink(String redirectUrl): From your app’s entry point that handles the deep link redirect (for example, onCreate() method in the app link receiving activity). Pass the full redirect URL string returned by the Prove server (delivered to the app after the user opens the Instant Link in SMS).Make sure to register your app link handling activity similar to this:
<activity android:name=".MyAppLinkHanlderActivity"
    android:exported="true"
    android:launchMode="singleTask"
    android:excludeFromRecents="true"
    android:taskAffinity="">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="my.applink.com" />
    </intent-filter>
</activity>
The redirect URL returned by the Prove server has your original finalTargetUrl, plus extra parameters needed to resume the session in the customer host app. For example, if the original finalTargetUrl provided via the Start() call is https://yourDeepLinkUrl.com, the redirect URL that opens your app is https://yourDeepLinkUrl.com?asc=true&authId=some-uuid-string. Those parameters are:
  • asc — Must be the string "true" or "false". Indicates whether the auth session was completed successfully on the server side (true) or not yet (false).
  • authId — Must be a valid UUID string. Identifies the authentication session; the SDK uses it to match the redirect to the correct in-progress session.
If the URL is missing these parameters or they are invalid, the SDK throws an instance of ProveAuthException and does not continue the flow.