Open with (Share, Send to) Guide

We use the term file import to refer to the Open with feature within Gini Bank SDK. From the point of view of the SDK, files are imported into the SDK from an outside source. It is unaware and can't set configuration related to enabling the client app to receive files via Android’s Open-with/Share functionality.

The “Open with…” feature can be found under different names in the Android phones, e.g: "Send to", "Share", “Share with” and "Open with".

To enable this feature, pass true to GiniBank.setCaptureConfiguration(CaptureConfiguration(fileImportEnabled = )). Additionally, your app should declare intent filters for receiving images and/or PDF files from other apps and then forward the incoming intent to Gini Bank SDK.

Add the following intent filter to the activity in your AndroidManifest.xml to receive incoming images and PDF files:

<activity android:name=".ui.MyActivity">
    <!-- Receiving images: -->
    <intent-filter
        android:label="@string/label_for_image_open_with">
        <action android:name="android.intent.action.VIEW" />
        <action android:name="android.intent.action.SEND" />
        <!-- The below SEND_MULTIPLE action is only needed if you enabled scanning of multi-page documents: -->
        <action android:name="android.intent.action.SEND_MULTIPLE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="image/*" />
    </intent-filter>
    <!-- Receiving pdfs: -->
    <intent-filter
        android:label="@string/label_for_pdf_open_with">
        <action android:name="android.intent.action.VIEW" />
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="application/pdf" />
    </intent-filter>
</activity>

We recommend adding ACTION_VIEW to the intent filter to let users send images and PDF files to your app from apps that don’t implement sharing with ACTION_SEND but enable viewing images and PDF files with other apps.

When your app is requested to handle an image or a PDF file, your activity (declaring the intent filter shown above) is launched or resumed (onNewIntent()) with the Intent having ACTION_VIEW or ACTION_SEND.

We recommend checking whether the Intent has the required action before proceeding with it:

String action = intent.getAction();
if (Intent.ACTION_VIEW.equals(action) || Intent.ACTION_SEND.equals(action)) {
    ...
}

If the Intent passes the above check then register an activity result handler with the CaptureFlowImportContract() and pass the Intent to GiniBank.startCaptureFlowForIntent():

fun configureCapture() {
  GiniBank.setCaptureConfiguration(this,
    CaptureConfiguration(
      fileImportEnabled = true,
      ... // other configuration options
    )
  )
}

// Use the androidx's Activity Result API to register a handler for the capture result.
val captureImportLauncher = registerForActivityResult(CaptureFlowImportContract()) { result: CaptureResult ->
    when (result) {
        is CaptureResult.Success -> {
            handleExtractions(result.specificExtractions)
        }
        is CaptureResult.Error -> {
            when (result.value) {
                is ResultError.Capture -> {
                    val captureError: GiniCaptureError = (result.value as ResultError.Capture).giniCaptureError
                    handleCaptureError(captureError)
                }
                is ResultError.FileImport -> {
                    val fileImportError = result.value as ResultError.FileImport
                    handleFileImportError(fileImportError)
                }
            }
        }
        CaptureResult.Empty -> {
            handleNoExtractions()
        }
        CaptureResult.Cancel -> {
            handleCancellation()
        }
    }
}

fun handleFileImportError(exception: ImportedFileValidationException) {
    var message = ...
    exception.validationError?.let { validationError ->
        // Get the default message
        message = getString(validationError.textResource)
        // Or use custom messages
        message = when (validationError) {
            FileImportValidator.Error.TYPE_NOT_SUPPORTED -> ...
            FileImportValidator.Error.SIZE_TOO_LARGE -> ...
            FileImportValidator.Error.TOO_MANY_PDF_PAGES -> ...
            FileImportValidator.Error.PASSWORD_PROTECTED_PDF -> ...
            FileImportValidator.Error.TOO_MANY_DOCUMENT_PAGES -> ...
        }
    }
    AlertDialog.Builder(this)
        .setMessage(message)
        .setPositiveButton("OK") { _, _ -> finish() }
        .show()
}

fun startGiniBankSDKForImportedFile(importedFileIntent: Intent) {
    // Configure capture first
    configureCapture();

    fileImportCancellationToken =
        GiniBank.startCaptureFlowForIntent(captureImportLauncher, this, importedFileIntent)
}

When your activity (declaring the intent filter shown above) is not the same as the activity from which you launch the Gini Bank SDK you need to create a Document from the intent first and then pass it to your other activity as an extra. There you can then launch the SDK with the Document.

Passing the launch intent from the first activity to the other activity causes java.lang.SecurityException: Permission Denial exceptions when the first activity is finished before the SDK has been launched in the other activity.

Create a Document from the intent in your activity A:

fun createDocumentAndLaunchActivityB(importedFilesIntent: Intent) {
    // Configure capture first
    configureCapture();

    fileImportCancellationToken =
        GiniBank.createDocumentForImportedFiles(
            intent = intent,
            context = this,
            callback = { documentCreationResult ->
                when (documentCreationResult) {
                    GiniBank.CreateDocumentFromImportedFileResult.Cancelled -> showCancellationToast("'Open with' cancelled")
                    is GiniBank.CreateDocumentFromImportedFileResult.Error -> showErrorToast("'Open with' failed with error ${documentCreationResult.error}")
                    is GiniBank.CreateDocumentFromImportedFileResult.Success -> documentCreationResult.document?.let { document ->
                        launchActivityB(document)
                    } ?: run {
                        showErrorToast("'Open with' failed")
                    }
                }
            }
        )
}

Get the Document from the intent extras in your activity B and launch the Gini Bank SDK:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    if (savedInstanceState == null) {
        if (intent.hasExtra(EXTRA_IN_OPEN_WITH_DOCUMENT)) {
            IntentCompat.getParcelableExtra(intent, EXTRA_IN_OPEN_WITH_DOCUMENT, Document::class.java)?.let {
                GiniBank.startCaptureFlowForDocument(
                            resultLauncher = captureImportLauncher,
                            document = document
                        )
            }
        }
    }
}

If the Intent passes the check for ACTION_VIEW and ACTION_SEND, then pass the Intent to GiniBank.createCaptureFlowFragmentForIntent():

fun configureCapture() {
  GiniBank.setCaptureConfiguration(this,
    CaptureConfiguration(
      fileImportEnabled = true,
      ... // other configuration options
    )
  )
}

fun startGiniBankSDKForImportedFile(importedFileIntent: Intent) {
    // Configure capture first
    configureCapture();

    fileImportCancellationToken =
        GiniBank.createCaptureFlowFragmentForIntent(this /* activity context */, importedFileIntent) { result ->
            when (result) {
                GiniBank.CreateCaptureFlowFragmentForIntentResult.Cancelled -> {
                    handleCancellation()
                }
                is GiniBank.CreateCaptureFlowFragmentForIntentResult.Error -> {
                    handleFileImportError(result.exception)
                }

                is GiniBank.CreateCaptureFlowFragmentForIntentResult.Success -> {
                    // Opening the file(s) from the intent and creating the CaptureFlowFragment
                    
                    // Set the listener to receive the Gini Bank SDK's results
                    result.fragment.setListener(this)
                    
                    // Show the CaptureFlowFragment for example via the fragment manager:
                    requireActivity().supportFragmentManager.beginTransaction()
                        .replace(R.id.fragment_container, result.fragment, "CaptureFlowFragment")
                        .addToBackStack(null)
                        .commit()
                }
            }
        }
}

// Handle the results from Gini Bank SDK
override fun onFinishedWithResult(result: CaptureResult) {
    when (result) {
        is CaptureResult.Success -> {
            // Handle extraction results (to proceed with the transaction)
            handleExtractions(result.specificExtractions)
            // After the user has seen (and maybe edited) the extractions and has executed the transfer 
            // please send the transfer summary to Gini with the final data approved by the user.
        }
        is CaptureResult.Error -> {
            when (result.value) {
                is ResultError.Capture ->
                    // There was a capture error
                    val captureError = result.value as ResultError.Capture
                    handleCaptureError(captureError)
                is ResultError.FileImport ->
                    // There was a file import error
                    val fileImportError = result.value as ResultError.FileImport
                    handleFileImportError(fileImportError)
            }
        }
        CaptureResult.Empty -> {
            // Handle empty result
            handleNoExtractions()
        }
        CaptureResult.Cancel -> {
            // Process was cancelled by user
            handleCancellation()
        }
        CaptureResult.EnterManually -> {
            // User wants to enter the invoice data manually
            handleEnterManually()
        }
    }
}

fun handleFileImportError(exception: ImportedFileValidationException) {
    var message = ...
    exception.validationError?.let { validationError ->
        // Get the default message
        message = getString(validationError.textResource)
        // Or use custom messages
        message = when (validationError) {
            FileImportValidator.Error.TYPE_NOT_SUPPORTED -> ...
            FileImportValidator.Error.SIZE_TOO_LARGE -> ...
            FileImportValidator.Error.TOO_MANY_PDF_PAGES -> ...
            FileImportValidator.Error.PASSWORD_PROTECTED_PDF -> ...
            FileImportValidator.Error.TOO_MANY_DOCUMENT_PAGES -> ...
        }
    }
    AlertDialog.Builder(this)
        .setMessage(message)
        .setPositiveButton("OK") { _, _ -> finish() }
        .show()
}

Android users can unintentionally set your app as the default for opening images or PDF files. To inform users about it and let them undo it, the SDK detects if your app is selected as the default app and shows the Clear Defaults Dialog enabling them to clear the defaults for your app in the Android settings.

The UI customization options for the Clear Defaults Dialog can be viewed in the UI Customisation Guide Analysis Screen.

Open with (Share, Send to) Guide

Register image and PDF file types

Handle imported files

Launch the SDK as an activity

Launch the SDK from a different activity

Launch the SDK as a fragment

Detect when your app is the default app for opening images or PDF files