Implementation Guide

// 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)) // verify(authId) call defined in #Validate the Mobile Phone section
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .build();

ProveAuth proveAuth = ProveAuth.builder()
    .withAuthFinishStep(authId -> verify(authId))
    .withOtpFallback(otpStartStep, otpFinishStep)
    .withContext(this)
    .withTestMode(true) // Test mode flag
    .build();

public class MyAuthenticator {
    private final MyBackendClient backend = new MyBackendClient(); // Backend API client

    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());
    }
}

package com.prove.android_sample_app;

import android.app.Activity;
import android.content.Context;
import android.content.Intent;

import androidx.activity.result.ActivityResultLauncher;
import androidx.activity.result.ActivityResultRegistry;
import androidx.activity.result.contract.ActivityResultContracts;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.lifecycle.DefaultLifecycleObserver;
import androidx.lifecycle.LifecycleOwner;

import com.prove.sdk.proveauth.OtpStartInput;
import com.prove.sdk.proveauth.OtpStartStepCallback;
import com.prove.sdk.proveauth.PhoneNumberValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

import java.util.concurrent.atomic.AtomicReference;

public class OtpStartStep implements
        com.prove.sdk.proveauth.OtpStartStep,
        DefaultLifecycleObserver {
    public static final String OTP_START_STEP_KEY = "OtpStartStep";
    private final ActivityResultRegistry registry;
    private ActivityResultLauncher<Intent> launcher;
    private final Context context;
    private final AtomicReference<OtpStartStepCallback> otpStartStepCallbackRef =
            new AtomicReference<>();

    public OtpStartStep(Context context, @NonNull ActivityResultRegistry registry) {
        this.context = context;
        this.registry = registry;
    }

    @Override
    public void execute(boolean phoneNumberNeeded, @Nullable ProveAuthException exception,
            OtpStartStepCallback otpStartStepCallback) {
        if (exception instanceof PhoneNumberValidationException) {
            otpStartStepCallbackRef.set(otpStartStepCallback);
            Intent intent = new Intent(context, OtpPhoneNumberInputActivity.class);
            intent.putExtra(IntentExtraFields.OTP_ERROR,
                    "Phone number is invalid, please try again.");
            launcher.launch(intent);
            return;
        }

        if (phoneNumberNeeded) {
            // We need to store callback object, it will be needed to complete this activity
            // by calling it with the results.
            otpStartStepCallbackRef.set(otpStartStepCallback);
            Intent intent = new Intent(context, OtpPhoneNumberInputActivity.class);
            launcher.launch(intent);
        } else {
            otpStartStepCallback.onSuccess(new OtpStartInput(""));
        }
    }

    public void onCreate(@NonNull LifecycleOwner owner) {
        launcher = registry.register(OTP_START_STEP_KEY, owner,
                new ActivityResultContracts.StartActivityForResult(),
                result -> {
                    OtpStartStepCallback callback = otpStartStepCallbackRef.get();
                    if (callback == null) {
                        return;
                    }

                    if (result.getResultCode() == Activity.RESULT_OK) {
                        Intent intent = result.getData();
                        if (intent != null) {
                            String phoneNumber = intent.getStringExtra(
                                    IntentExtraFields.OTP_PHONE_NUMBER_FIELD);
                            callback.onSuccess(new OtpStartInput(phoneNumber));
                        } else {
                            callback.onError();
                        }
                    } else {
                        callback.onError();
                    }
                });
    }
}

import android.app.Activity;
import android.content.Context;
import android.content.Intent;
import android.util.Log;

import androidx.activity.result.ActivityResultLauncher;
import androidx.activity.result.ActivityResultRegistry;
import androidx.activity.result.contract.ActivityResultContracts;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.lifecycle.DefaultLifecycleObserver;
import androidx.lifecycle.LifecycleOwner;

import com.prove.sdk.proveauth.OtpFinishInput;
import com.prove.sdk.proveauth.OtpFinishStepCallback;
import com.prove.sdk.proveauth.OtpValidationException;
import com.prove.sdk.proveauth.ProveAuthException;

import java.util.concurrent.atomic.AtomicReference;

public class OtpFinishStep implements
        com.prove.sdk.proveauth.OtpFinishStep,
        DefaultLifecycleObserver {
    public static final String OTP_FINISH_STEP_KEY = "OtpFinishStep";
    private final ActivityResultRegistry registry;
    private ActivityResultLauncher<Intent> launcher;
    private final Context context;
    private final AtomicReference<OtpFinishStepCallback> otpFinishStepCallbackRef =
            new AtomicReference<>();

    public OtpFinishStep(Context context, @NonNull ActivityResultRegistry registry) {
        this.context = context;
        this.registry = registry;
    }

    @Override
    public void execute(@Nullable ProveAuthException otpException,
            OtpFinishStepCallback otpFinishStepCallback) {
        // We need to store callback object, it will be needed to complete this activity
        // by calling it with the results.
        otpFinishStepCallbackRef.set(otpFinishStepCallback);
        if (otpException instanceof OtpValidationException) {
            Log.e("OtpFinishStep", "found otp errors", e);
            return;
        }
        Intent intent = new Intent(context, OtpCodeInputActivity.class);
        launcher.launch(intent);
    }

    public void onCreate(@NonNull LifecycleOwner owner) {
        launcher = registry.register(OTP_FINISH_STEP_KEY, owner,
                new ActivityResultContracts.StartActivityForResult(),
                result -> {
                    OtpFinishStepCallback callback = otpFinishStepCallbackRef.get();
                    if (callback == null) {
                        return;
                    }

                    if (result.getResultCode() == Activity.RESULT_OK) {
                        Intent intent = result.getData();
                        if (intent != null) {
                            String code = intent.getStringExtra(
                                        IntentExtraFields.OTP_CODE_FIELD);
                            callback.onSuccess(new OtpFinishInput(code));
                            return;
                        }
                    }
                    callback.onError();
                });
    }
}

// Object implementing ProveAuthFinishStep protocols
let finishStep = FinishAuthStep()

// Objects implementing OtpStartStep/OtpFinishStep protocols
let otpStartStep = MobileOtpStartStep()
let otpFinishStep = MobileOtpFinishStep()

let proveAuthSdk: ProveAuth
proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep)
  .build()

proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withMobileAuthTestMode() // Test mode flag
  .build()

// authToken retrieved from your server via StartAuthRequest
proveAuthSdk.authenticate(authToken) { error in
  DispatchQueue.main.async {
    self.messages.finalResultMessage = "ProveAuth.authenticate returned error: \(error.localizedDescription)"
    print(self.messages.finalResultMessage)
  }
}

import Foundation
import ProveAuth
import SwiftUI

// Implementation of OtpStartStep protocol
class MobileOtpStartStep: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

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

    // ProveAuth SDK calls this method when it is time to collect a customer's phone number for SMS OTP and/or obtain
    // the customer's confirmation to initiate the SMS message to the phone number provided
    // 'phoneNumberNeeded' argument indicates whether mobile app needs to collect the phone number
    func execute(phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback) {
        // here - signal to ContentView to display OtpStartView
        DispatchQueue.main.async {
            // SDK returns phoneValidationError if the phone number provided is invalid or blocked
            if case .phoneNumberValidationError = phoneValidationError {
                self.sheetObservable.isPhoneValidationError = true
            } else {
                self.sheetObservable.isPhoneValidationError = false
            }
            self.sheetObservable.isOtpStartActive = true
            self.sheetObservable.isPhoneNumberNeeded = phoneNumberNeeded
            self.callback = callback
        }
    }

    // Here - return collected phone number string to SDK
    func handlePhoneNumber(phoneNumber: String? = nil) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        if let phoneNumber = phoneNumber {
            let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
            // This is how you pass collected phone number to SDK
            callback.onSuccess(input: otpStartInput)
            return
        }
        // If phoneNumberNeeded = false (in the OtpStartStep.execute) and phone number was already provided in the initial server-to-server call to /start endpoint
        // Then return nil back to SDK, Prove Auth server already got the phone number
        // calling onSuccess here indicates that the customer's confirmation to send SMS was obtained
        callback.onSuccess(input: nil)
    }

    // Here - communicate to the SDK any issues while trying to obtain the phone number.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

import Foundation
import SwiftUI
import ProveAuth

// Implementation of OtpFinishStep protocol
class MobileOtpFinishStep: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable){
        self.sheetObservable = sheetObservable
    }
    // SDK calls this method when it is time to collect OTP value delivered in the SMS message
    // otpError will be returned if OTP value was incorrect
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // here - signal to ContentView to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Here - return the OTP value to the SDK
    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)
    }

    // Here - communicate to the SDK any issues while trying to obtain the OTP value.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction or presses the back button to exit out the SMS OTP finish step screen.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

// 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);

  // TODO: define your VerifyResponse object to parse customer information from the response
  String firstName = response.getFirstName();
  String lastName = response.getLastName();

  // Pre-fill customer information to your Android App UI, for example:
  firstNameEditText.setText(firstName);
  lastNameEditText.setText(lastName);
}

  // Send a verify request to get return customer information.
  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func verify(String: authId, completion: @escaping (Error?) -> Void) {
      guard let url = URL(string: "\(backendUrl)/verify") else {
          completion(URLError(.badURL))
          return
      }
      // Create the request
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body (empty JSON object) - authId is not needed so you can ignore.
      let body: [String: Any] = ["authId": authId]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(error)
          return
      }
      // Perform the request
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          if let error = error {
              completion(error)
              return
          }
          // Parse the response
          do {
              if let json = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any],
                 let firstName = json["firstName"] as? String,
                 let lastName = json["lastName"] as? String {
                  // Update the UI on the main thread
                  DispatchQueue.main.async {
                      // Update your UI with the pre-fill customer information
                      // For example, assuming you have IBOutlet references for your text fields
                      self.firstNameInput.text = firstName
                      self.lastNameInput.text = lastName
                  }
                  completion(nil)
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON"])
                  completion(parsingError)
              }
          } catch {
              completion(error)
          }
      }
      // Start the network call
      task.resume()
  }

  // Send request to the backend to verify customer information.
  SendInfoResponse sendInfo(String firstName, String lastName) {
    YourBackendClient backend = new YourBackendClient(); // Backend API client

    // TODO: Build your SendInfoRequest object
    SendInfoRequest sendInfoRequest = new SendInfoRequest(firstName, lastName, ...);

    // Send a sendInfoRequest to your backend server to get return customer information.
    SendInfoResponse response = backend.verify(sendInfoRequest);

    // TODO: define your own SendInfoResponse object to parse the response
    return response;
  }

  // Send request to the backend to verify customer information.
  // The below example uses native iOS URLSession, but any other
  // alternative networking approaches should also work
  func sendInfo(firstName: String, lastName: String, completion: @escaping (Result\<[String:Any], Error>) -> Void) {
      guard let url = URL(string: "\(backendUrl)/finish") else {
          completion(.failure(URLError(.badURL)))
          return
      }
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.addValue("application/json", forHTTPHeaderField: "Accept")
      request.addValue("application/json", forHTTPHeaderField: "Content-Type")
      // Set up the request body
      let body: [String: Any] = [
          "firstName": firstName,
          "lastName": lastName
      ]
      do {
          request.httpBody = try JSONSerialization.data(withJSONObject: body, options: \[])
      } catch {
          completion(.failure(error))
          return
      }
      let task = URLSession.shared.dataTask(with: request) { \_, response, error in
          // Handle network or connection errors
          if let error = error {
              completion(.failure(error))
              return
          }
          do {
              if let results = try JSONSerialization.jsonObject(with: data, options: \[]) as? [String: Any] {
                  completion(.success(results))
              } else {
                  let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey : "Failed to parse JSON or authToken is missing"])
                  completion(.failure(parsingError))
              }
          } catch {
              completion(.failure(error))
          }
      }
      // Start the network call
      task.resume()
  }