Package com.unblu.sdk.module.integrity

Class AppIntegrityModuleApi

java.lang.Object
com.unblu.sdk.module.integrity.AppIntegrityModuleApi
public class AppIntegrityModuleApi extends Object
Provides methods to ensure the integrity, security, and authenticity of the application and device. This class includes functionality for key management, app update enforcement, security checks, and integrity validation.

  • Constructor Details

    • AppIntegrityModuleApi

      public AppIntegrityModuleApi(android.content.Context context)

  • Method Details

    • generateKeyPair

      public String generateKeyPair()
      Generates (or reuses) the device RSA key pair in the Android Keystore.
      Returns:
      the Base64-encoded X.509 public key, or null if key generation fails.

    • signBindingChallenge

      public String signBindingChallenge(String challenge)
      Signs the given challenge with the device private key stored in the Android Keystore.
      Parameters:
      challenge - the challenge string to sign.
      Returns:
      the Base64-encoded signature, or null if no key is available or signing fails.

    • resetKeyPair

      public void resetKeyPair()
      Deletes the RSA key pair stored in the Android Keystore.

    • requestIntegrityToken

      public void requestIntegrityToken(@NonNull String nonce, @NonNull AppIntegrityModuleApi.SuccessCallback successCallback, @NonNull AppIntegrityModuleApi.ErrorCallback errorCallback)
      Requests an integrity token from the Play Integrity API using the default cloud project number. This overload uses DEFAULT_CLOUD_PROJECT_NUMBER (163924594738L).
      Parameters:
      nonce - A unique, client-generated string used to ensure freshness and prevent replay attacks. Use getChallenge(com.unblu.sdk.core.agent.UnbluAgentClient, com.unblu.sdk.core.callback.SuccessCallback<java.lang.String>) to retrieve one.
      successCallback - Callback invoked when the integrity token request is successful. The retrieved integrity token is passed to this callback.
      errorCallback - Callback invoked when an error occurs during the request. The error message describing the failure is passed to this callback.

    • requestIntegrityToken

      public void requestIntegrityToken(@NonNull String nonce, long cloudProjectNumber, @NonNull AppIntegrityModuleApi.SuccessCallback successCallback, @NonNull AppIntegrityModuleApi.ErrorCallback errorCallback)
      Requests an integrity token from the Play Integrity API with a specific cloud project number.
      Parameters:
      nonce - A unique, client-generated string used to ensure freshness and prevent replay attacks. Use getChallenge(com.unblu.sdk.core.agent.UnbluAgentClient, com.unblu.sdk.core.callback.SuccessCallback<java.lang.String>) to retrieve one.
      cloudProjectNumber - The Google Cloud project number used for the Play Integrity API request.
      successCallback - Callback invoked when the integrity token request is successful. The retrieved integrity token is passed to this callback.
      errorCallback - Callback invoked when an error occurs during the request. The error message describing the failure is passed to this callback.

    • scanQRCode

      public void scanQRCode(@NonNull AppIntegrityModuleApi.SuccessCallback successCallback, @NonNull AppIntegrityModuleApi.ErrorCallback errorCallback)
      Presents a full-screen QR code scanner activity with a camera preview and an "aim" frame. On the first decoded QR, invokes successCallback with the raw payload string. On user cancel, permission denial, or camera failure, invokes errorCallback with a reason.

      The host app's AndroidManifest must declare android.permission.CAMERA. The library's manifest declares the activity itself and a suitable full-screen theme.

      Parameters:
      successCallback - Callback invoked with the decoded QR payload (called once, on the main thread).
      errorCallback - Callback invoked with a failure reason (called once, on the main thread).

    • scanQRCode

      public void scanQRCode(@NonNull String hintText, @NonNull String cancelText, @NonNull AppIntegrityModuleApi.SuccessCallback successCallback, @NonNull AppIntegrityModuleApi.ErrorCallback errorCallback)
      Same as scanQRCode(SuccessCallback, ErrorCallback) but with caller-supplied copy for the on-screen hint and the cancel button, so the host app can localize or customize the scanner UI.
      Parameters:
      hintText - Text shown above the aim frame (e.g. "Align the QR code within the frame").
      cancelText - Label of the cancel button (e.g. "Cancel").
      successCallback - Callback invoked with the decoded QR payload (called once, on the main thread).
      errorCallback - Callback invoked with a failure reason (called once, on the main thread).

    • getChallenge

      public void getChallenge(@NonNull UnbluAgentClient unbluClient, SuccessCallback<String> result)
      Initiates a device integrity challenge using the given UnbluAgentClient.
      Parameters:
      unbluClient - The UnbluAgentClient used to obtain the challenge.
      result - A SuccessCallback called with the challenge string.

    • verifyAttestation

      public void verifyAttestation(@NonNull UnbluAgentClient unbluClient, String token, SuccessCallback<Boolean> result)
      Verifies the attestation token generated by the device during the integrity challenge.
      Parameters:
      unbluClient - The UnbluAgentClient used to verify the attestation.
      token - The attestation token to verify.
      result - A SuccessCallback called with the verification result.

    • createDeviceIntegrityVerifier

      public AppIntegrityModuleApi.DeviceIntegrityVerifier createDeviceIntegrityVerifier(@NonNull UnbluAgentClient unbluClient)
      Creates a AppIntegrityModuleApi.DeviceIntegrityVerifier using the given UnbluAgentClient.
      Parameters:
      unbluClient - The UnbluAgentClient used to obtain challenges and verify attestations.
      Returns:
      A AppIntegrityModuleApi.DeviceIntegrityVerifier using the default integrity token requester.

    • createDeviceIntegrityVerifier

      public AppIntegrityModuleApi.DeviceIntegrityVerifier createDeviceIntegrityVerifier(@NonNull UnbluAgentClient unbluClient, @NonNull AppIntegrityModuleApi.DeviceIntegrityVerifier.IntegrityTokenRequester integrityTokenRequester)
      Creates a AppIntegrityModuleApi.DeviceIntegrityVerifier using the given UnbluAgentClient.
      Parameters:
      unbluClient - The UnbluAgentClient used to obtain challenges and verify attestations.
      integrityTokenRequester - The requester used to obtain the integrity token.
      Returns:
      A AppIntegrityModuleApi.DeviceIntegrityVerifier using the provided requester.

    • handleDeviceIntegrityChecks

      public void handleDeviceIntegrityChecks(@NonNull UnbluAgentClient unbluClient, @NonNull AppIntegrityModuleApi.DeviceIntegrityResultCallback completion)
      Runs the device integrity flow using the given UnbluAgentClient.
      Parameters:
      unbluClient - The UnbluAgentClient used to obtain challenges and verify attestations.
      completion - Callback invoked with true when the device integrity flow succeeds, or false when it fails.

    • handleDeviceIntegrityChecks

      public static void handleDeviceIntegrityChecks(@NonNull AppIntegrityModuleApi.DeviceIntegrityVerifier verifier, @NonNull AppIntegrityModuleApi.DeviceIntegrityResultCallback completion)
      Runs the device integrity flow asynchronously and calls completion with the result. Example: 
      
 UnbluAgentClient unbluClient = ...;
 AppIntegrityModuleApi integrity = new AppIntegrityModuleApi(context);

 AppIntegrityModuleApi.DeviceIntegrityVerifier verifier =
         integrity.createDeviceIntegrityVerifier(
                 unbluClient,
                 (challenge, success, error) -> integrity.requestIntegrityToken(challenge, success, error)
         );

 AppIntegrityModuleApi.handleDeviceIntegrityChecks(verifier, isOk -> {
 });
      Parameters:
      verifier - Provides the operations required for the integrity flow.
      completion - Callback invoked with true when the device integrity flow succeeds, or false when it fails.

    • getDeviceBindingApi

      public DeviceBindingApi getDeviceBindingApi(@NonNull UnbluClientConfiguration clientConfiguration, @NonNull String username, @NonNull String password, String restPath)
      Creates a DeviceBindingApi that talks to the unblu server over REST.

      Pass the SAME UnbluClientConfiguration you use for UnbluClient. Building the configuration does not initialize the SDK, so this can run first. Device binding reads everything it needs from it — server URL, entry path, preferencesStorage (so it reuses / persists the shared device ID), customCookies (always sent), and the client certificate (mTLS) — which keeps it consistent with the initialized SDK.

      Obtain one instance and reuse it for the whole binding lifecycle (register → verify → revoke). The returned facade owns its own REST session: it logs in lazily on first use and caches the session, so calling getDeviceBinding again performs a fresh login (wasteful, not wrong; the device ID is shared via the configuration's preferencesStorage).

      Parameters:
      clientConfiguration - the configuration you reuse for UnbluClient; single source of truth for server URL, entry path, storage, custom cookies and client certificate.
      username - username for the dedicated device-binding REST login.
      password - password for username.
      restPath - REST API prefix; defaults to /rest/v4 when null.
      Returns:
      a DeviceBindingApi facade.

    • isUpdateAvailable

      public void isUpdateAvailable(android.content.Context context, AppIntegrityModuleApi.UpdateAvailabilityCallback callback)
      Checks if an update is available for the app.
      Parameters:
      context - The application context used to create the AppUpdateManager.
      callback - Callback invoked with true if an update is available, or false if no update is available or if the check fails.

    • forceUpdate

      public void forceUpdate()
      Forces an immediate app update if one is available. This method checks for an available update and, if an immediate update is allowed, redirects the user to the app's Play Store page to initiate the update process.

    • isDeviceScreenLockEnabled

      public boolean isDeviceScreenLockEnabled()
      Checks if the device has a secure screen lock enabled. This method verifies whether the device has a secure lock screen mechanism, such as a PIN, pattern, or password.
      Returns:
      true if a secure screen lock is enabled, false otherwise.

    • addBackgroundOverlay

      public void addBackgroundOverlay(boolean enableOverlay)
      Enables or disables a background overlay to prevent screen content from being captured. When enabled, this method applies the WindowManager.LayoutParams.FLAG_SECURE flag to the current activity, preventing screenshots and screen recording. When disabled, the flag is removed, allowing screen captures.
      Parameters:
      enableOverlay - true to enable the overlay and prevent screen capture, false to allow screen capture.
      Throws:
      ClassCastException - if the provided context is not an instance of Activity.

    • isScreenOverlayActive

      public boolean isScreenOverlayActive()
      Checks if a screen overlay is active on the device. This method attempts to detect whether an overlay is present by setting the WindowManager.LayoutParams.FLAG_SECURE flag and checking specific window attributes. It also verifies if the app has permission to draw overlays using Settings.canDrawOverlays(Context).
      Returns:
      true if a screen overlay is detected, false otherwise.
      Throws:
      ClassCastException - if the provided context is not an instance of Activity.

    • isUsingThirdPartyKeyboard

      public boolean isUsingThirdPartyKeyboard()
      Checks if the device is using a third-party keyboard. This method retrieves the default input method (keyboard) set on the device and checks whether it belongs to the current application package.
      Returns:
      true if a third-party keyboard is in use, false if the default keyboard is from the app itself.

    • isRunningOnEmulatorOrDebugger

      public boolean isRunningOnEmulatorOrDebugger()
      Detects if the application is running on an emulator or being debugged. This method checks common indicators of an emulator, such as a generic build fingerprint or a model name containing "google_sdk". It also verifies if a debugger is currently attached.
      Returns:
      true if the application is running on an emulator or a debugger is connected, false otherwise.

    • isDeviceRooted

      public boolean isDeviceRooted()
      Checks if the device is rooted. This method uses the RootBeer library to detect root access on the device.
      Returns:
      true if the device is rooted, false otherwise.

    • isFridaRunning

      public boolean isFridaRunning()
      Checks if Frida (a popular dynamic instrumentation tool) is running on the device. This method scans the list of running processes for known Frida-related process names, such as "frida" and "gum-js-loop". If any of these processes are found, it indicates that Frida may be running.
      Returns:
      true if a Frida-related process is detected, false otherwise.