Open with (Share, Send to) Guide

1 Register image and PDF file types
2 Handle imported files
3 Detect when your app is the default app for opening images or PDF files

We use the term file import to refer to the Share feature within Gini Capture 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 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"

Please note that the “Open with (Share, Send to)” feature is disabled by default.

To enable this feature, pass true to GiniCapture.Builder.setFileImportEnabled(). 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 Capture SDK.

Register image and PDF file types

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.

Handle imported files

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 create an Intent for launching Gini Capture SDK with GiniCapture.getInstance().createIntentForImportedFiles():

void configureGiniCapture() {
  GiniCapture.newInstance(this).
    .setFileImportEnabled(true)
    ... // other configuration options
    .build()
}

void startGiniCaptureSDKForImportedFile(final Intent importedFileIntent) {
    // Configure the Gini Capture SDK first
    configureGiniCapture();
    if (GiniCapture.hasInstance()) {
        mFileImportCancellationToken = GiniCapture.getInstance().createIntentForImportedFiles(
                importedFileIntent, (Context) this,
                new AsyncCallback<Intent, ImportedFileValidationException>() {
                    @Override
                    public void onSuccess(final Intent result) {
                        mFileImportCancellationToken = null;
                        startActivityForResult(result, REQUEST_SCAN);
                    }

                    @Override
                    public void onError(final ImportedFileValidationException exception) {
                        mFileImportCancellationToken = null;
                        handleFileImportError(exception);
                    }

                    @Override
                    public void onCancelled() {
                        mFileImportCancellationToken = null;
                    }
                });
    }
}

void handleFileImportError(final ImportedFileValidationException exception) {
    String message = ...
    if (exception.getValidationError() != null) {
        // Get the default message
        message = getString(exception.getValidationError().getTextResource());
        // Or use custom messages
        switch (exception.getValidationError()) {
            case TYPE_NOT_SUPPORTED:
                message = ...
                break;
            case SIZE_TOO_LARGE:
                message = ...
                break;
            case TOO_MANY_PDF_PAGES:
                message = ...
                break;
            case PASSWORD_PROTECTED_PDF:
                message = ...
                break;
            case TOO_MANY_DOCUMENT_PAGES:
                message = ...
                break;
        }
    }
    new AlertDialog.Builder((Context) this)
            .setMessage(message)
            .setPositiveButton("OK", (dialogInterface, i) -> finish())
            .show();
}

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

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.