Skip to main content

Document capture

About this guide​

This guide is designed to help you implement the Android SDK quickly and easily. Basic concepts, SDK implementation examples and also how to interact with the engines REST APIs are available.

PLEASE NOTE

This guide focuses on the image capture process. If you are looking for information about unico | check, visit this page, the APIs guide or the overview page.

Through this guide, you can:

  • Implement the camera aperture and the image capture;
  • Manipulate the return data;
  • Use SDK feedback with engine APIs.

Before you begin​

Make sure you followed the step-by-step instructions for installing and importing the SDK through this guide. It is also important to consider the features available in this SDK, as explained on the overview page.

Available resources​

The Android SDK provides a document capture component containing a capture frame that helps the user to position the document correctly for the photo. After positioning correctly, the user must click a button to capture the photo of the document.

The SDK does not perform any kind of validation of what is being captured.

The document capture is done by the Document camera with manual capture mode, which makes it possible to capture documents:

  • CPF: Capture from Brazilian national ID Document (CPF);
  • CNH: Capture from Brazilian Driver's licence - Opened document, front and back;
  • CNH Front: Capture from Brazilian Driver's licence - Front;
  • CNH Back: Capture from Brazilian Driver's licence - Back;
  • RG Front: Capture from Brazilian regional ID Document (RG) - Front;
  • RG Back: Capture from Brazilian regional ID Document (RG) - Back;
  • Others: Capture from any other document.

image

Implementation​

By following this step-by-step guide, you will have the full potential of the SDK embedded in your Android application.

INITIALIZE THE SDK​

Create an instance of the builder (Generated through the IAcessoBioBuilder interface), providing as a parameter the context in question and the implementation of the AcessoBioListener class.

The implementation of this class is very simple and can be done with a few lines of code. All you need to do is instantiate the builder informing the context in question and override the callback methods with your application's business logic:

public class MainActivity extends AppCompatActivity {

    private AcessoBioListener callback = new AcessoBioListener() {
        @Override
        public void onErrorAcessoBio(ErrorBio errorBio) { }

        @Override
        public void onUserClosedCameraManually() { }

        @Override
        public void onSystemClosedCameraTimeoutSession() { }

        @Override
        public void onSystemChangedTypeCameraTimeoutFaceInference() { }
    };

    private IAcessoBioBuilder acessoBioBuilder = new AcessoBio(this, callback);
}

IMPLEMENT CALLBACK FUNCTIONS​

Note that the work of implementing the AccessBioListener class is, to a large extent, configuring the callback methods. Each method is called in a specific situation back from the SDK.

Just overwrite the methods exemplified in the previous step with the business logic of your application.

WARNING

All the above methods must be created in the way indicated in your project (Even without any logic). Otherwise, the project does not compile successfully.

PERSONALIZATION THE CAPTURE PROCESS​

This is an optional step, but highly recommended so that the capture process has your company's visual identity.

It is possible to customize some objects of the frame according to the camera mode used, through the setTheme() method.

WARNING

Supported types for color representation are Color Resource or String containing the hex code of the color. Ex: R.color.red ou #FF0000

All methods are available below:

IAcessoBioTheme unicoTheme = new IAcessoBioTheme() {
    @Override
    public Object getColorBackground() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBoxMessage() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextMessage() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundButtonPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextButtonPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundTakePictureButton() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorIconTakePictureButton() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundBottomDocument() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextBottomDocument() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorSilhouetteSuccess() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorSilhouetteError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorProgressBar() { 
        return R.color.your_color;
    }
};
    
acessoBioBuilder.setTheme(unicoTheme);

It is also possible to make customizations statically, in your colors.xml file add the following code:

<color name="unico_color_background"> #YourColor </color> 
<color name="unico_color_silhouette_success"> #YourColor </color> 
<color name="unico_color_silhouette_error"> #YourColor </color> 
<color name="unico_color_silhouette_neutral"> #YourColor </color> 
<color name="unico_color_box_message"> #YourColor </color> 
<color name="unico_color_text_message"> #YourColor </color> 
<color name="unico_color_background_popup_error"> #YourColor 
<color name="unico_color_text_popup_error"> #YourColor </color> 
<color name="unico_color_background_button_popup_error"> #YourColor 
<color name="unico_color_text_button_popup_error"> #YourColor </color> 
<color name="unico_color_background_take_picture_button"> #YourColor </color> 
<color name="unico_color_icon_take_picture_button"> #YourColor </color> 
<color name="unico_color_background_bottom_document"> #YourColor </color> 
<color name="unico_color_text_bottom_document"> #YourColor </color> 
<color name="unico_color_button_cancel"> #YourColor </color> 
<color name="unico_color_progress_bar_capture"> #YourColor </color>
WARNING

Please, refer to available customization methods by camera mode.

DOCUMENT CAMERA WITH MANUAL CAPTURE​

In this camera mode it is possible to personalize:

image

CONFIGURE CREDENTIALS​

It is necessary to inform the credentials generated in the API Key for the SDK to work, for this, use the AccessoBioConfigDataSource configuration class:

AcessoBioConfigDataSource unicoConfig = new AcessoBioConfigDataSource() {

    @Override
    public String getHostKey() {
        return HOST_KEY;
    }

    @Override
    public String getHostInfo() {
        return HOST_INFO;
    }

    @Override
    public String getBundleIdentifier() {
        return BUNDLE_IDENTIFIER;
    }

    @Override
    public String getMobileSdkAppId() {
        return MOBILE_SDK_APP_ID;
    }

    @Override
    public String getProjectId() {
        return PROJECT_ID;
    }

    @Override
    public String getProjectNumber() {
        return PROJECT_NUMBER;
    }
};

IMPLEMENT LISTENERS FOR CAMERA EVENTS​

The camera's aperture method, which is called in the next step, needs to know what to do if it manages to capture an image successfully or if it has an error in the process. It is necessary to inform "what to do" to the method of opening the camera through the implementation of listeners that is called in situations of success or error.

Through the configuration of the listeners, you can specify what happens in your App in situations of error (onErrorDocument method) or success (onSuccessDocument method) in capturing images.

The example below illustrates the configuration of listeners, build and camera opening:

iAcessoBioDocument cameraListener = new iAcessoBioDocument() {
    @Override
    public void onSuccessDocument(ResultCamera result) { }

    @Override
    public void onErrorDocument(ErrorBio errorBio) { }
};

unicoCheckCamera.prepareDocumentCamera(unicoConfig, new DocumentCameraListener() {
    @Override
    public void onCameraReady(UnicoCheckCameraOpener.Document cameraOpener) {
        cameraOpener.open(DocumentType.CNH, cameraListener);
    }

    @Override
    public void onCameraFailed(String message) {
        Log.e(TAG, message);
    }
});
IMPLEMENTATION OF LISTENERS

The implementation of these methods listeners must be done through an instance of the iAcessoBioDocument class.

PREPARE AND OPEN THE CAMERA​

It is necessary to create an instance of builder through the build() method. This method is available through the object generated with the IAcessoBioBuilder interface and AcessoBio class:

UnicoCheckCamera unicoCheckCamera = acessoBioBuilder.build();

The next step is to prepare the camera using the prepareDocumentCamera() method with the object returned by the builder (Named UnicoCheckCamera in the example above).

When everything goes well, the prepareDocumentCamera() method should generate an object of type UnicoCheckCameraOpener.Document, which is finally used to open the camera with its open() method, receiving the parameters type of document to be captured, which are:

  • DocumentCameraType.CPF: Capture from Brazilian national ID Document (CPF);
  • DocumentCameraType.CNH: Capture from Brazilian Driver's licence - Opened document, front and back;
  • DocumentCameraType.CNH_FRENTE: Capture from Brazilian Driver's licence - Front;
  • DocumentCameraType.CNH_VERSO: Capture from Brazilian Driver's licence - Back;
  • DocumentCameraType.RG_FRENTE: Capture from Brazilian regional ID Document (RG) - Front;
  • DocumentCameraType.RG_VERSO: Capture from Brazilian regional ID Document (RG) - Back;
  • DocumentCameraType.None: Capture from any other document.

ONSUCCESSDOCUMENT METHOD​

When performing an image capture with success, this method is invoked and returns an object of type ResultCamera that is used later in the call of the REST APIs:

public void onSuccessDocument(ResultCamera result) { }

The ResultCamera object returns 2 attributes: Base64 and Encrypted:

  • The Base64 attribute can be used if you want to display a preview of the image in your app;
  • The Encrypted attribute must be sent when calling the unico | check (Detailed in the next section).
Alert

The Encrypted attribute is strictly intended for sending the image through the Unico APIs. You should not open and serialize this attribute, as its characteristics may change without notice. Its use must be exclusive in interactions with the APIs to guarantee the data integrity and security. Unico is not responsible for any damages arising from this practice, since the changes may occur unpredictably.

ONERORDOCUMENT METHOD​

When an error occurs in the image capture, this method is invoked and returns an object of type ErrorBio:

public void onErrorDocument(ErrorBio errorBio) { }
LEARN MORE

About ErrorBio types in the References section of this SDK.

CONVERSION FROM BASE64 TO BITMAP

If you need to convert base64 to bitmap, the standard way does not work for Android. You need to perform the split from the comma(,) for it to work. If you want to know more, read the following article How to convert a Base64 string into a Bitmap image to show it in an ImageView?.

CALL THE APIS​

Capturing the images is just the first part of the journey. After capturing the image, it is necessary to send the generated Encrypted to the APIs, selecting one of the available flows detailed in Flows.

Attention

For security reasons, the interval between generating the Encrypted and sending it via one of the available flows must be a maximum of 10 minutes. Submissions made beyond this period will be automatically rejected by the API.

Any concerns?​

Didn't find something or still need help? If you are already a customer or partner, you can contact us through Help Center.

Next steps​

-References.