Best Practices for SDK Implementation
In this section, you will find a list of best practices for implementing the Unico IDCloud platform SDK
Use a PoC to Facilitate Your Implementation
Unico provides a set of POCs (Proof of Concept) that are implementations in the various languages supported by the SDK. These POCs present functional code examples with flows and methods in the context of the SDK, for educational purposes, making it easier to understand the expected sequence and how to adapt it to the code to be implemented by our clients. You can consult the available POCs through this link and request them by opening a ticket with our support team via the client portal.
Always Keep Your SDKs Updated
The SDKs are constantly evolving to ensure greater security and new features and functionalities. It is essential for clients to maintain a routine of updates, as well as to be agile in applying critical updates.
For more details, please refer to the SDK update policy.
Identify the Latest Version Available for the SDK
It is important to ensure that you update to the most recent version available:
Android: [list of versions];
iOS: [list of versions];
Flutter: [list of versions];
Web: [list of versions].
Avoid Updating the SDK and Other Components/Functionalities Simultaneously
We understand that your application makes use of various other libraries and functionalities, often being loaded simultaneously with the Unico SDK. As a best practice for updates, avoid upgrading our SDK at the same time you update any other functionality or library. This is because, if you encounter a failure or a change in behavior, it may be challenging to identify the root cause. We recommend performing updates separately to ensure better control over validations, as well as using our staging environment.
Are You Having Difficulty Updating the SDK? We Can Help
If you are having difficulties, open a ticket in our client portal with the following information (to expedite the process):
What is the language of the SDK you are trying to update?
If it’s mobile (Android or iOS), is it a native or hybrid implementation (please provide details)?
In the case of JavaScript implementation, which framework is being used?
What is the current version of the SDK you are trying to update? (not necessary if it's a new installation);
What is the new version you are attempting to install/update?
Please provide the API Key you are using;
Does the update consist solely of upgrading the SDK, or are other components/functionalities also being changed/updated/modified? If so, please describe which additional items are being modified;
Provide a description of the steps executed and what the results/errors were;
Please attach evidence and inputs related to the failure/problem (log files containing error/failure excerpts, screenshots, and/or videos reproducing the problem).
Do not Manipulate the JWT Object (Encrypted)
When successfully capturing an image, the onSuccessSelfie method returns an object of type ResultCamera which has two attributes:
Base64 of the obtained image, which can be used if you want to display a preview of the image in your app;
Encrypted, which is a JWT object that must be sent in the REST API calls. The JWT (Encrypted) should be used strictly during image submission through Unico's APIs. You should not open or serialize this attribute, as its characteristics may change without prior notice. Its use should be exclusive for interactions with the APIs to ensure data integrity and security. Unico is not responsible for any damages arising from this practice, as modifications can occur unpredictably. As mentioned, the SDK already provides the Base64 attribute to obtain the image in question.
Um caso de exemplo em Swift: Método: onSuccessSelfie print("(result.encrypted)") para Encrypted print("(result.base64)") para para Base64 print("(result)") para Encrypted e Base64
In summary: never attempt to read or manipulate the Encrypted (JWT) attribute.
Send the JWT Within 10 Minutes
For security reasons, the JWT must be sent within a period of 10 minutes. If the sending exceeds this window, the package will be considered invalid. Consider this time during the user's journey in your application and avoid subsequent changes.
Send the JWT Only Once
For security reasons, the JWT must be sent only once to Unico's backend. If there is a problem processing the image and/or an error in the response, a new biometric capture must be performed to generate a new encrypted object and then send this new file to Unico's backend.
Do Not Use Virtualization
Virtualizing devices in your application's testing dynamics can be interpreted as an attempt to bypass the security layers incorporated into the biometrics provider, potentially returning the errors:
Mobile:
73006 - Unable to open camera on emulators.
Web:
73600 - Could not find camera resource.
73400 - Could not initialize camera.
To avoid rework and incorrect error identification, tests should be conducted on physical devices.
Use the Same API Key for Capturing and Sending the Photo to the Backend
All communication and requests are based on API Keys previously defined in the client's instance. It is very important that your implementation uses the same API Key in both the capture and submission flows, as this helps avoid integration errors, facilitates validation, and ensures traceability of processes and flows.
If you have any questions about your API Key, please contact technical support.
Do Not Keep DevTools Open When Performing Web Captures
During testing and validation processes, it is normal to keep DevTools open to check flows and requests. However, the capture validation method should not be considered during these tests, as the SDK identifies it as a possible fraud and invalidates the submission when sent to the backend. Therefore, when performing end-to-end flows, it is essential to keep DevTools disabled and proceed with normal capture.
Delete "Resources" Files When Updating to New Versions (Web)
When uploading versions for the WEB SDK, if there is also an update for resource files, always delete the old file and insert the new ones in the Public folder. This is because files may have the same name and not be replaced. Also, ensure that there is no internal cache of the old resource files after the update and new build.
Implementations in Flutter Applications Must Use Our Flutter Plugin
For implementation in Flutter applications, always use our specific Flutter plugin for this purpose. We reinforce that you should not try to implement the native versions of our SDK (Android, iOS) through bridges in Flutter applications, as this action often generates errors not mapped by Unico's engineering team.
Separate the Preparation and Camera Opening Flow into 2 Steps
The SDK implementation has 2 steps until the photo capture and generation of the encrypted:
Camera preparation;
Camera opening.
In the first step, you need to specify the type of camera to be used and the bundle with the API KEY information. If everything is correct, the authentication with the SDK backend is successfully carried out. In the second step, the camera is opened, usually triggered by a button click from the user. Authentication with the SDK backend may take a few seconds, so placing this step along with the camera opening in the user's button click can create frustration and a sense of slowness. Therefore, the ideal approach is to prepare the camera during the loading of the capture orientation page, so when the user decides to open the camera, the loading will be faster, enhancing the final experience.
This way, you will optimize your implementation and improve the speed of your application, reducing the perception of slowness in processing for your end user.
Cache Cleaning When Updating the Mobile SDK
Always perform cache cleaning before building and uploading new versions. If this cleaning is not performed, you may encounter errors related to cached dependencies that may have been removed or updated in new versions. Below are some examples of how to do this:
For Flutter, use the command:
Remove the file:
pubspec.lockor;flutter pub get.
For iOS, use the command:
pod cache clean 'unicocheck-ios' –allor;pod cache clean –allor;Remove
podfile.lockand follow up withpod install.
For Android in build Gradle, use the command:
./gradlew clean.
Obfuscation Settings
Obfuscation is a process of transforming bytecode into a form that is less human-readable, thus making reverse engineering more difficult. The obfuscation tool used in your application can affect the functionality of the SDK, so it is important that the SDK code is not obfuscated. A good indicator of obfuscation issues is when your application works in debug mode but fails when building in release mode, since obfuscation does not modify files in debug mode.
Therefore, it is essential that during the SDK implementation, you add the necessary obfuscation rules for the Unico SDK. Otherwise, you may face issues when trying to build the project using the iOS, Android, or Flutter SDK.
Below are the links for the obfuscation configuration for each OS:
Perform Tests and Validations in Unico's Staging Environment
Unico provides a staging environment for clients to perform tests and validations of their implementations before making any changes and modifications to the production environment. We emphasize the importance of this step in order to ensure greater security when performing the change window in production. Ensure that your testing plan includes as many validations and scenarios as possible that you will encounter in the production environment (such as device variations, tests with limited connectivity, etc.).
Important: remember that the staging environment has its own set of configurations/parameters, such as service account and specific API Keys (different from the production environment).
Create a Safe Checklist for Production Rollout
Create a script / checklist considering your company's change management plan.
Make sure you are using the correct production settings (such as the correct API Key).
Ensure that you have a rollback (recovery) plan in case of failure when deploying the new version to production.
When encountering a failure, collect all logs and relevant inputs.
Reactivate the previous functional version to mitigate impact in production.
Open a ticket on our customer portal containing all the information and inputs regarding the failure so that we can assist you.
Still need help?
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
Atualizado
Isto foi útil?