Skip to main content

Android - Q2Utils

Q2Utils provides a collection of utility functions to help you develop modules for the Q2 Mobile application. This document outlines the key functionalities available in Q2Utils.

Open UIModule​

This function is used to open a UIModule from anywhere in the application, without needing to rely on a new call from a Tecton extension. This can be a common use case where you are listening for an event to occur, a notification to be consumed, etc. and you want to open a UIModule in response to that event.

fun openUIModule(
    moduleId: String,
    moduleData: String = "{}",
    sdkUtils: SdkUtils,
    callback: ValueCallback<String>
) {
    sdkUtils.runJavascriptInUUX(
        "(function() { return __MOB.modules.open(\"$moduleId\", \"$moduleData\", console.log); })();",
        callback
    )
}

Essentially, this helper function illustrates the usage of the sdkUtils.runJavascriptInUUX function to activate existing UUX functions. Here, the function is __MOB.modules.open, which is the fundamental JavaScript function that launches a UIModule.

How to Use​

Q2Utils.openUIModule(myModuleId, myModuleData, sdkUtils) {
    // Handle the result of the UIModule
}

For more details on how to use the openModule call and the properties it requires, please refer to the openModule section of the Tecton SDK documentation.

Permission Requests​

Permission requesting is a very common requirement. Especially if you are working with high risk operations. For example, if you are working with a camera, you need to request permission to access the camera. If you are working with location, you need to request permission to access the location. If you are working with contacts, you need to request permission to access the contacts. And so on.

To assist with this, the library provides a permission request utility. This utility is a simple utility that allows you to request a permission. If the permission is already granted, the utility will return true. If the permission is not granted, the utility will request the permission and return true if the user grants the permission, and false if the user denies the permission.

suspend fun requestPermission(
    activity: Activity?,
    permission: String,
    rationale: Rationale? = null
): Boolean

The permission value is the Constant Value of each given permission. For example, if you want to request the camera permission, you need to pass the android.permission.CAMERA value, or if you want to request the location permission, you need to pass the android.permission.ACCESS_FINE_LOCATION value.

How to Use​

suspend fun requestCameraPermission(sdkUtils: SdkUtils) {
    Q2Utils.requestPermission(sdkUtils.getActivity(), "android.permission.CAMERA")
}

You can see an entire list of permissions and their Constant Value in the Android Developer Documentation.

Best Practices​

Opening UIModules​

  • Always handle the callback to ensure proper tracking of UIModule state
  • Use appropriate module data (in JSON format) to pass necessary information to the UIModule
  • Verify that the UIModule ID exists before attempting to open it
  • Consider checking if the user is logged in before opening certain UIModules

Permission Requests​

  • Always provide a clear rationale to the user about why the permission is needed
  • Handle denied permissions gracefully, providing alternative functionality when possible
  • Check permission status before requesting to avoid unnecessary permission prompts
  • Group related permissions together when possible to minimize user interruption

Troubleshooting​

Common Issues with UIModule Opening​

  • Module Not Found: Ensure the moduleId is correct and that the module is properly registered
  • JavaScript Execution Error: Check that the application is in the foreground and Core has control of the current view
  • Data Format Issues: Verify that the moduleData is valid JSON format

Permission Request Problems​

  • Permission Always Denied: The user might have selected "Don't ask again" - direct them to App Settings
  • Permission Dialog Not Showing: Ensure the Activity context is valid and not null
  • Unexpected Behavior After Permission Grant: Some features may require app restart after permission changes