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 various languages supported by the SDK, presenting functional code examples with flows and methods in the context of the SDK. These examples are for educational purposes, making it easier to understand the expected sequence and adapt it to the code that our clients will implement. You can consult the available PoCs at this link and request them by opening a ticket with our support team through the client portal.
Always Keep Your SDKs Updated
SDKs are constantly evolving to ensure greater security and new features. It is essential for clients to maintain a routine of updates, as well as agility in 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 know that your application uses various other libraries and functionalities, often loaded simultaneously with Unico's SDK. As a good practice for updates, avoid upgrading our SDK at the same time as updating any other functionality/library. This is because if you encounter a failure and/or change in behavior, it can be challenging to determine the root cause. We recommend performing updates separately to ensure greater control over validations and to use 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)
Upon successfully capturing an image, the onSuccessSelfie method returns a ResultCamera object that has 2 attributes:
Base64 of the captured 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 the image submission via Unico's APIs. Do not open and/or serialize this attribute, as its characteristics may change without notice. Its use must be exclusive to interactions with the APIs to ensure the integrity and security of the data. Unico is not responsible for any damages arising from this practice, as modifications may occur unpredictably. As mentioned, the SDK already provides the Base64 attribute to obtain the image in question. An example case in Swift:
Method:
onSuccessSelfieprint("(result.encrypted)")for Encryptedprint("(result.base64)")for Base64print("(result)")for Encrypted and 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 misidentification of errors, testing 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 predefined in the client's instance. It is very important that your implementation uses the same API Key in the capture flow and the sending flow, as this avoids integration errors, facilitates validation, and traceability of processes and flows. If you have 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 less human-readable form, thereby making reverse engineering more difficult. The obfuscation tool you use in your application may affect the functioning of the SDK; therefore, it is necessary that it does not obfuscate the SDK code. A good indicator of obfuscation problems is to check if your application works in debug mode and fails to work when built in release mode, as obfuscation does not modify files in debug mode.
Thus, during the SDK implementation, you need to add the configuration for the Unico SDK to your obfuscation rules; otherwise, you will face issues trying to build the project using the iOS, Android, or Flutter SDK. Below are the links for obfuscation settings for each OS:
Android: Link to Android obfuscation documentation;
iOS: Link to iOS obfuscation documentation.
Perform Tests and Validations in Unico's Staging Environment
Unico provides a staging environment for clients to conduct tests and validations of their implementations before making any changes or alterations in the production environment. We emphasize the importance of this step to ensure greater security when making changes in production. Ensure that your testing plan includes as many validations and scenarios as 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 accounts and specific API Keys (different from the production environment).
Create a Safe Checklist for Production Rollout
Create a checklist considering your company's change management plan:
Ensure you are using the latest version of the SDK;
Ensure that you have done an extensive test in the staging environment;
Ensure that you have followed the steps mentioned in this document;
Check for changes in third-party libraries;
Ensure that you are following your team’s deployment guidelines;
Avoid doing large changes in production.
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