Migrate to 3.0.0

In version 3.0.0 we modernized our UI and added support for light and dark modes. Additionally, we unified the public API of the SDK and introduced an easier way to customize certain parts of the UI.

Migrate from Component API

The Component API provided more UI customization options at the cost of a more difficult integration and maintenance. It was based on fragments, and you managed navigation between them and also update the navigation whenever we introduced breaking changes.

Maintaining the Component API along with the Screen API required an increasing amount of effort as we added new features. We decided therefore to unify both APIs and introduce the ability to inject fully custom UI elements.

The major benefit of the Component API was the ability to use a custom navigation bar (toolbar or action bar). Via UI injection that is still possible with the new public API.

Follow these steps to make the migration to the new public API easier:

• Configure the SDK the same way as before by using GiniCapture.

• If you used a custom navigation bar, you can use the new ability to inject fully custom UI elements. To do this, implement the NavigationBarTopAdapter interface and pass it to GiniCapture.newInstance(context).setNavigationBarTopAdapter(). The NavigationBarTopAdapter interface declares the contract your view has to fulfill and lets the SDK ask for your view instance when needed.

• Use the CameraActivity to launch the SDK instead of the CameraFragmentCompat.

• Handle the result of the CameraActivity to receive the extracted information (error or cancellation).

• Remove all code related to interacting with the SDK’s fragments. From now on the entry point is the CameraActivity and customization happens through GiniCapture and via overriding of resources.

• Use the new UI customization options and follow the screen-by-screen UI customization section to adapt the look of the new UI.

Migrate from Screen API

The new public API is based on the Screen API, so you only use the new UI customization options and follow the screen-by-screen UI customization section to adapt the look of the new UI.

Migrate Open with

If you use the GiniCapture.createIntentForImportedFile(), replace it with GiniCapture.getInstance().createIntentForImportedFiles().

Migrate Cleanup and Feedback step

We simplified the feedback-sending logic. When you clean up the Gini Capture SDK, pass the values the user receives (and potentially corrects) to GiniCapture.cleanup(). All values except the one for the amount are passed in as strings. The amount needs to be passed in as BigDecimal and its currency as an Enum value.

You don’t have to call any additional methods to send the extraction feedback.

Default Networking implementation

You don’t need to interact with the GiniCaptureDefaultNetworkApi anymore. The GiniCapture.cleanup() method takes care of sending the feedback.

Custom Networking implementation

Only implement the GiniCaptureNetworkService from now on. We removed the GiniCaptureNetworkApi and moved the sendFeedback() method to the GiniCaptureNetworkService.

GiniCaptureNetworkService.sendFeedback() is called when you pass the values the user receives (and potentially corrects) to GiniCapture.cleanup().

Overview of new UI customization options

To simplify UI customization, we introduced global customization options. There is no need to customize each screen separately anymore.

Styles

We leverage the power of Material Design to configure a theme for the SDK with a global color palette and typography that is applied on all the screens.

Using global styles for the various widgets, we enable you to customize them in a single place. They are then consistently applied on all screens.

Theme

The theme style is based on Material Design v2 and is named GiniCaptureTheme. To override the theme in your application, use Root.GiniCaptureTheme as the parent:

Widgets

The style of buttons and other widgets is based on Material Design v3. To override them in your application, use the root style as the parent, for example:

Colors

We introduced a global color palette which you are free to override. Custom colors are applied to all screens.

For more information about the names of the color resources, see Overview of UI Customization Options.

If you override the GiniCaptureTheme, the theme colors you set there override the color palette customization.

Images

Customizing images is done the same way as before via overriding of drawable resources. Find the drawable resource names in the screen-by-screen UI customization section.

We replaced most drawables with vector drawables. Unfortunately due to the limitations of vector drawables some images had to be added as PNGs.

If you use vector drawables please add them to the drawable-anydpi folder so that they also override any density specific PNGs.

Typography

We introduced global typography based on text appearance styles from Material Design v3. To override them in your application, use the root style as the parent, for example:

If you override the GiniCaptureTheme, the text appearances you set there override the typography customization. The same applies to overridden widget styles where you set a custom text appearance.

For more information about the typography style names, see Overview of UI Customization Options.

Text

Text customization is done the same way as before via string resources.

UI elements

Certain elements of the UI can now be fully customized via UI injection. This helped us to drop the Component API while still letting in-depth customization for certain parts of the UI.

UI injection utilizes view adapter interfaces which you can implement and pass to GiniCapture when configuring the SDK. These interfaces declare the contract the injected view has to fulfill and let the SDK ask for your view instance when needed.

The most important injectable UI element is the top navigation bar. You can also show the navigation bar on the bottom using your own custom view. For more information, see Generic Components.

Dark mode

To customize resources for dark mode, add them to resource folders containing the -night resource qualifier.

Migrate to new UI

Back buttons

We removed setBackButtonsEnabled and don’t support this option anymore.

Onboarding screen

The new onboarding screen uses the global UI customization options. You can discard the earlier screen-specific customizations.

Images and text are onboarding page specific and need to be customized for each page.

For more information, see Onboarding Screen.

Breaking changes

Setting custom onboarding pages

The OnboardingPage class was changed to also enable setting a title for the page and injecting a view for the illustration.

To display drawable resources, use the ImageOnboardingIllustrationAdapter.

If you set custom onboarding pages, create the OnboardingPage as shown in the example:

New features

Custom illustration views

To inject any custom view for the illustration, implement the OnboardingIllustrationAdapter interface and pass it to either GiniCapture or the OnboardingPage constructor.

For example, if you want to show animated illustrations, use a Lottie view in your OnboardingIllustrationAdapter implementation.

For more information, see Onboarding Screen.

Bottom navigation bar

To show a bottom navigation bar, pass true to GiniCapture setBottomNavigationBarEnabled. There is a default implementation, but you can also use your own by implementing the OnboardingNavigationBarBottomAdapter interface and passing it to GiniCapture.

Find more details Onboarding Screen.

Camera screen

The new camera screen uses the global UI customization options. You can discard the earlier screen-specific customizations.

For more information, see Camera Screen.

New features

We implemented image cropping. Parts of the image that appears outside the white camera frame are cut out from the final image.

Bottom navigation bar

To show a bottom navigation bar, pass true to GiniCapture setBottomNavigationBarEnabled. There is a default implementation, but you can also use your own by implementing the CameraNavigationBarBottomAdapter interface and passing it to GiniCapture.

For more information, see Camera Screen.

Custom loading indicator view

There is a default implementation of indicator which indicates that the image is in the cropping process, but you can show your own activity indicator by implementing the CustomLoadingIndicatorAdapter interface and passing it to GiniCapture.

For more information, see Camera Screen.

Breaking changes

We removed the tooltip dialogs that were shown on the first launch.

Review screen

The new review screen uses the global UI customization options. You can discard the earlier screen-specific customizations.

For more information, see Review Screen.

New features

Custom Process button loading indicator

There is a default implementation of a loading indicator on the Process button that indicates document upload is in progress, but you can show your own indicator by implementing the CustomLoadingIndicatorAdapter interface and passing it to GiniCapture.

For more information, see Review Screen.

Bottom navigation bar

To show a bottom navigation bar, pass true to GiniCapture setBottomNavigationBarEnabled. There is a default implementation, but you can also use your own by implementing the ReviewNavigationBarBottomAdapter interface and passing it to GiniCapture.

For more information, see Review Screen.

Breaking changes

Re-ordering and rotation of the images are not supported anymore. The Gini API automatically corrects rotation during processing. If the processing of images fails, then the user is redirected to the error screen.

Analysis screen

The new analysis screen uses the global UI customization options. You can discard the earlier screen-specific customizations.

For more information, see Analysis Screen.

Breaking changes

The new analysis screen does not show the page count of PDF files and preview images for photo documents.

New features

Custom loading indicator view

There is a default implementation for indicating that document analysis is in progress, but you can show your own activity indicator by implementing the CustomLoadingIndicatorAdapter interface and passing it to GiniCapture.

For more information, see Analysis Screen.

Help Screen

The new help screen uses the global UI customization options. You can discard the earlier screen-specific customizations.

For more information, see Help Screen.

New features

Bottom navigation bar

To show a bottom navigation bar, pass true to GiniCapture setBottomNavigationBarEnabled. There is a default implementation, but you can also use your own by implementing the HelpNavigationBarBottomAdapter interface and passing it to GiniCapture.

For more information, see Help Screen.

No results screen

The new no-results screen uses the global UI customization options. You can discard the earlier screen-specific customizations.

For more information, see No Results Screen.

New features

New UI

The new no results screen gives options to enter document details manually.

Enter manually button

Users can now click the Enter manually button on the no results screen and exit the SDK with CameraActivity.RESULT_ENTER_MANUALLY as the result code.

For more information, see No Results Feature.

Error screen

The new analysis screen uses the global UI customization options.

For more information, see Error Screen.

Breaking changes

Showing errors during usage of the SDK was changed from snackbar to a whole new screen.

New features

New UI

The new error screen gives options to retake photos or enter details manually and displays errors with more detailed description.

Enter manually button

Users can now click the Enter manually button on the error screen and exit the SDK with CameraActivity.RESULT_ENTER_MANUALLY as the result code.

For more information, see Error Feature.

QR code scanner

The new UI for the QR code scanner uses the global UI customization options. You can discard the earlier screen-specific customizations.

For more information, see Camera Screen

Breaking changes

QR code scanning UI and functionality changed. Scanning and processing happen automatically now.

New features

The SDK can be launched to only scan QR codes. To enable this feature, pass true to GiniCapture.Builder.setOnlyQRCodeScanning().