The Assentify Component SDK for iOS gives developers direct, native control of individual identity components such as face capture, ID document capture, and data extraction, then lets them submit the collected data to the Digital Experience Platform (DXP).
Install · Initialize · Capture
Platform iOS native (Swift)SDK type Component SDKAlso available Android, Flutter, React NativeDelegate AssentifySdkDelegate
Which SDK is this?
Assentify offers two SDK types. The Flow SDK embeds a whole published DXP flow, a complete guided journey, natively and is driven by a generated flow URL. The Component SDK, which this page documents, gives developers direct control of individual identity components (for example face capture, ID document capture, and extraction) and lets them submit the collected data to the Digital Experience Platform (DXP). For the Flow SDK, see the SDK overview.
Overview
The Assentify SDK has several capabilities and functionalities that empower developers to take complete control of the identity extraction process. The Assentify SDK complements the Assentify DXP platform (SaaS). The developer leverages the available data by using the response information from the supported components or data provided by the app user. The SDK allows the developer to submit all extracted data to Assentify to gain access to further features such as Compliance, AML, client profile, and other features that the DXP covers.
The key components that are supported and available in the SDK are:
Identification Document Capture
A standalone, event-driven component that extracts information from an ID card. The ID type is determined by the configuration set in Assentify DXP.
Face Capture / Matching
A standalone, event-driven component that performs face matching between a live source and a developer-supplied target image.
Context Aware Signing
Retrieves document tokens, creates a user document instance, and applies a base64 signature to produce a signed document URL.
Definitions
Term
Meaning
StepID
The StepID represents the ID of the Step in the Engagement block that you configure in the Flow Builder on the portal (for example, the StepID of Face Capture or ID Capture). You will need it to submit your data to the portal.
Requirements
To initialize the Component SDK you require the following values, all of which can be retrieved from the Assentify DXP portal. Once you have logged in, visit the Developers section and select the flow you would like to use for your application.
Value
Where to retrieve it
API Key
In the Developers section, create a new API Key or use an existing key. You can assign Claims to an API Key to limit the amount of access a specific API Key has.
Tenant Identifier
In Developers › Flow Configuration, select the flow and Engagement block. The Tenant Identifier is shown in the flow information section for that block.
Interaction Hash
In Flow Manager, select your flow. When the Digital Engagement Link loads on the right panel it has the format https://platform.assentify.com?interaction={HASH}. Copy the HASH part.
AvailabilityThe Assentify Component SDK is available for Android native, iOS native, Flutter, and React Native.
Initialization
To leverage the capabilities of the Assentify Component SDK, the developer must initialize the SDK on each application start-up. Initialization ensures the developer has the key information required to begin using the Component SDK.
Step 1 : environmentalConditions configuration
The environmentalConditions variable is instantiated as an object of type EnvironmentalConditions. It is configured with the following parameters.
Parameter
Description
enableDetect
Enables the detection feature.
enableGuide
Enables the guide feature to assist users during scanning.
CountDownNumbersColor
Custom color (hex) for the countdown timer on the Face Match step, for example #610A3A.
HoldHandColor
Color (hex) for the hand-holding guide or indicator, for example #FFC400.
MotionLimit
Number of frames taken before sending in case of a steady hand, for ID Cards on iOS. (Optional)
MotionLimitFace
Number of frames taken before sending in case of a steady hand, for Face on iOS. (Optional)
BRIGHTNESS_HIGH_THRESHOLD
Acceptable high brightness threshold, Android. (Optional)
Local active liveness type: actions (move your head left, right, up, down), wink (your eye, left or right), or blink. (Optional)
activeLivenessCheckCount
The number of times the local active liveness check will be requested. (Optional)
faceLivenessRetryCount
The number of times the user failed the face liveness before passing the step. (Optional)
minRam, minCPUCores
Any Android device with RAM or CPU smaller than these values will use manual scanning instead of automatic detection. (Optional)
Step 2 : assentifySdk configuration
The assentifySdk object is an instance of AssentifySdk and is initialized with several parameters.
Parameter
Description
apiKey
The API Key retrieved from the DXP portal.
tenantIdentifier
The Tenant Identifier retrieved from the DXP portal.
interaction
The interaction (Interaction Hash) value.
environmentalConditions
Passes the previously defined environmentalConditions as part of the SDK configuration.
assentifySdkDelegate
Sets the current class (self) as the callback handler for SDK events.
performActiveLivenessFace
Enables the local active liveness check for face. (Optional)
Initialization delegates
Delegate
Description
onAssentifySdkInitSuccess
An initialization callback fired when the SDK has successfully been initialized.
onAssentifySdkInitError
A callback executed upon failure to initialize the SDK.
Load templates after initUpon completion of the initialization, call the getTemplates function. This returns a List<TemplatesByCountry>. Store the result to be used later in the process when processing an ID card.
Retrieving the values from the DXP portal
Visit the Assentify DXP and click on the Developers section. Then click on the Flow Configuration button.
Select the flow you want to use with your application. Then from the drop-down menu, select the Engagement block you would like to target.
Once you have selected an appropriate block you will see the information related to the flow. Retrieve the Tenant Identifier from this section.
To retrieve the API Key, create a new API Key or use an existing key. You can assign Claims to an API Key to limit the amount of access it has.
To fetch the Interaction Hash, click on the Flow Manager and select your flow. When the Digital Engagement Link loads on the right panel, its format is https://platform.assentify.com?interaction={HASH}. Copy the HASH part to retrieve the interaction hash.
BlockLoader
The Assentify BlockLoader is a core component provided to the developer to perform several functions and capabilities. The BlockLoader gives the developer core properties that must be set to give context to the Assentify DXP platform.
Built-in property
DeviceName
FlowName
TimeStarted
Application
UserAgent
InstanceHash
The properties above are built into the BlockLoader. However, the developer can access the DXP and add additional properties if needed, such as phoneNumber and clientIdentifier. These properties can transfer custom information to Assentify DXP, which can later be mapped to WebHooks or other platform capabilities. The developer has no limit on the number of properties that can be added to the BlockLoader.
How to add a property to the BlockLoader
Go to the Flow Manager and select the flow you want to edit.
Click the view more button on the Engagement Block.
In the input field, type the name of the property. Then press the add button.
Completed.
How to use the BlockLoader properties as a developer
Once the developer adds these properties using the DXP, the developer then defines the added properties inside their application, which they can use to set the BlockLoader step for submission. All custom properties added can be used to perform additional capabilities on the Assentify DXP, such as running decisions and mapping webhooks. To make use of the custom properties, declare them inside your app. Assentify uses OnBoardMe_Property_{propertyName} as the naming nomenclature for all custom properties.
Identification Document Capture
The Identification Document Capture is a standalone, event-driven component that provides a means by which the developer can extract information from an ID card. The ID type is determined by the configuration set in Assentify DXP. The developer or business user can log in to Assentify and manage these configurations anytime, even after the application has gone live. This provides flexibility to support as many ID cards as possible without recompiling and deploying the application.
This component returns many different types of information depending on the ID type being scanned, such as a Civil ID versus a Driving License. This is done using dynamic keys and mappings built into the SDK. A global model is available for developers to extract information from the base model and the available property dictionary.
The component has a built-in user interface that can be used by default, or the developer can use their own custom user interface by turning off the guides and default interface. The component leverages the native tools while providing complete control of what is displayed on the user interface using the events fired during the scanning process.
Methods
Method
Description
startFlow
Initializes and launches the entire flow, including the UI and events configured in the Admin Portal.
getTemplates
Receives all the configured supported Identification Document templates in the system (such as Passport, Lebanese Civil ID, Lebanese Driving License, French Resident Permit). You need the template when starting the ID scanning feature to inform the scanner which template you are using, and to create a list for the user to select which ID they would like to provide.
startScanIDCard
Begins the ID scanning process.
startScanPassport
Begins the passport scanning process.
startScanOther
Begins the scanning process for other ID types.
readPassport
Begins NFC passport scanning.
startFlow parameters
The FlowEnvironmentalConditions parameter carries the following fields.
Field
Description
logoUrl
URL of the logo displayed in the flow header or main screen. (Optional)
svgBackgroundImageUrl
URL of the SVG background image used for the screen background. (Optional)
textColor
Primary text color in HEX format, for example #000000. (Optional)
secondaryTextColor
Secondary text color in HEX format, used for subtitles or less prominent text. (Optional)
backgroundCardColor
Background color for cards and containers in HEX format. (Optional)
accentColor
Accent color used for highlights and interactive elements. (Optional)
backgroundColor
Defines the main background style of the screen. Can be Solid (single color) or Gradient (multiple colors with an angle). (Optional)
clickColor
Defines the background style applied on click or pressed states. (Optional)
backgroundType
Defines how the background should be rendered, for example color or image. This is the only required field.
Language
Optionally set the language that the OCR will process the extracted content from the cards. (Optional)
enableNfc, enableQr
Triggers NFC scanning after scanning a passport, or QR scanning after scanning a card.
blockLoaderCustomProperties
Map containing the custom properties configured in the Admin Portal.
flowDelegate
Specifies the callback function that will be called during flow completion.
from
Current view controller.
startScanIDCard parameters
Parameter
Description
scanIDCardDelegate
Specifies the delegate function that will be called during the scanning process.
templatesByCountry
The object of the templates that are supported to scan.
Language
Optionally set the language that the OCR will process the extracted content from the ID card. (Optional)
startScanPassport and startScanOther parameters
Parameter
Description
scanPassportDelegate / scanOtherDelegate
Specifies the delegate function that will be called during the scanning process.
Language
Optionally set the language that the OCR will process the extracted content from the ID card. (Optional)
How to initialize the flow
Initialize the AssentifySdk object.
Call AssentifySdk.startFlow().
Configure the startFlow parameters.
How to initialize ID card scanning
Initialize the AssentifySdk object.
Call AssentifySdk.startScanIDCard().
Configure the startScanIDCard parameters.
The startScanIDCard method accepts a templatesByCountry parameter that includes all the available retrieved templates.
How to initialize passport scanning
Initialize the AssentifySdk object.
Call AssentifySdk.startScanPassport().
Configure the startScanPassport parameters.
Completed.
How to initialize NFC passport scanning
Initialize the AssentifySdk object.
Call AssentifySdk.readPassport().
Check NFC support.
Enable NFC Tag Reading from Xcode.
How to initialize Other ID scanning
Initialize the AssentifySdk object.
Call AssentifySdk.startScanOther().
Configure the startScanOther parameters.
Completed.
Face Capture / Matching
The Face Capture and Matching step is a standalone, event-driven component that allows the developer to perform face matching between a live source and a target image. The developer offers the target image, while the selfie camera captures the source image. All the features and capabilities of the component are driven by the configuration that the developer or business user can set on Assentify DXP. The developer may choose to override this configuration.
How to use the Face Acquisition component
Initialize the AssentifySdk object.
Call AssentifySdk.startFaceMatch().
Configure the startFaceMatch parameters.
Supply the target base-64 encoded face image.
Add the component to the ViewController as a subview.
Context Aware Signing
How to initialize it
Call startContextAwareSigning.
Wait for onHasTokens: the tokens from your selected document.
Fill the tokens and call createUserDocumentInstance.
Wait for onCreateUserDocumentInstance and call the signature function with the base64 signature.
Wait for onSignature and get the document URL.
Wrap Up
The Wrap Up component is a built-in step that allows the developer to set the TimeEnded value. The developer can supply an end time for the flow.
Submission
Submission is a built-in function of the SDK that allows the developer to initiate the data transmission from the integrating app to Assentify DXP. Submission can be used to add additional properties to the BlockLoader and perform data aggregation and manipulation before sending it to Assentify. For example, the developer can send additional eKYC information, user-specific data, or data to bridge between the Assentify DXP and the back-end services of the integrating application. The developer may also perform additional functions such as custom date formatting, translation, transliteration, and calculations.
One of the key features of the Assentify Component SDK is being able to submit all the collected data to Assentify DXP, allowing business users to review all the collected data. The simplest way to submit data to Assentify is to leverage the existing code provided in the Demo Application (Android, iOS).
How to submit data to Assentify DXP
Retrieve the step definition model so that there is a reference to the List<StepDefinitions>.
Retrieve the output properties model.
Retrieve the output properties for the face from OutPropertiesModelFace.
Define variables for the wrap up, blockLoader, ContextAwareSigning step, face step, and ID capture step.
Loop through the steps and populate the output properties into a map.
Ensure that each SubmitRequestModel is then set into a MutableList<SubmitRequestModel>.
Call the assentifySdk.startSubmitData() method.
Preparing the submit listYou must prepare your list of steps with the outputProperties obtained for each step, for example:
A map containing the extracted data with hash keys for submission.
transformedProperties
A map with extracted data that may be transformed if translation is needed.
additionalDetails
Extra extracted data, particularly for "Other Scanning."
imageUrl
The URL of the ID image.
faces
URLs of faces extracted from the ID.
identificationDocumentCapture
This model contains all extracted data.
baseImageFace
The selfie image used for "Face Match."
secondImageFace
The image provided for comparison in "Face Match."
percentageMatch
Match percentage.
isLive
Liveliness detection result.
error message
The error message, if any.
success
A boolean indicating success.
TemplatesByCountry
Field
Type
Description
name
String
The name of the country.
sourceCountryCode
String
The ISO-2 country code.
flag
String
The country flag image.
templates
List<Templates>
The list of templates by country.
KycDocumentDetails
Field
Type
Description
name
String
The name of the document.
order
Int
The order of the page (front, back, etc.).
templateSpecimen
String
The default specimen that represents the ID type being used (Civil ID, Driving License, etc.).
templateProcessingKeyInformation
String
The template Id.
hasQrCode
Boolean
Whether the ID has a QR code.
Templates
Field
Type
Description
id
Int
The template Id.
sourceCountryFlag
String
The flag of the country as a URL.
sourceCountryCode
String
The ISO-2 country code.
kycDocumentType
String
The name of the template.
sourceCountry
String
The country name.
kycDocumentDetails
List<KycDocumentDetails>
A list of KycDocumentDetails.
ConfigModel
Field
Type
Description
stepId
Int
Identifier for the step.
flowName
String
Name of the flow.
blockName
String
Name of the block.
instanceHash
String
Hash value of the instance.
stepDefinition
Any?
Step definition, can be any type.
flowInstanceId
String
Identifier for the flow instance.
tenantIdentifier
String
Identifier for the tenant.
blockIdentifier
String
Identifier for the block.
flowIdentifier
String
Identifier for the flow.
customProperties
Map<String, Any>
Custom properties map with string keys and any values.
defaultLanguageId
Int
Identifier for the default language.
instanceId
String
Identifier for the instance.
userStateStepMap
Map<String, List<UserState>>
Mapping of user states.
stepDefinitions
List<StepDefinitions>
List of step definitions.
StepDefinitions
Field
Type
Description
stepId
Int
Identifier for the step.
stepDefinition
String
Definition of the step.
customization
Customization
Customization options.
outputProperties
List<OutputProperties>
List of output properties.
OutputProperties
Field
Type
Description
id
Int
Identifier for the output property.
key
String
Key for the output property.
displayName
String
Display name for the output property.
isRequired
Boolean
Whether the property is required.
isExcluded
Boolean
Whether the property is excluded.
type
Int
Type identifier for the property.
Customization
Field
Type
Description
ProcessMrz
Boolean?
Whether to process MRZ (Machine Readable Zone).
StoreCapturedDocument
Boolean?
Whether to store captured documents.
PerformLivenessDetection
Boolean?
Whether to perform liveness detection.
StoreImageStream
Boolean?
Whether to store image streams.
SaveCapturedVideo
Boolean?
Whether to save captured video.
identificationDocuments
List<IdentificationDocuments>?
List of identification documents.
PassportResponseModel
Field
Type
Description
destinationEndpoint
String?
Destination endpoint.
passportExtractedModel
PassportExtractedModel?
Extracted passport model.
error
String?
Error message.
success
Boolean?
Success status.
PassportExtractedModel
Field
Type
Description
outputProperties
Map<String, Any>?
Output properties map.
transformedProperties
Map<String, String>?
Transformed properties map.
extractedData
Map<String, Any>?
Extracted data map.
imageUrl
String?
URL for the image.
faces
List<String>?
List of detected faces.
identificationDocumentCapture
IdentificationDocumentCapture?
Identification document capture details.
OtherResponseModel
Field
Type
Description
destinationEndpoint
String?
Destination endpoint.
otherExtractedModel
OtherExtractedModel?
Extracted model for other data.
error
String?
Error message.
success
Boolean?
Success status.
OtherExtractedModel
Field
Type
Description
outputProperties
Map<String, Any>?
Output properties map.
transformedProperties
Map<String, String>?
Transformed properties map.
extractedData
Map<String, Any>?
Extracted data map.
additionalDetails
Map<String, Any>?
Additional details map.
transformedDetails
Map<String, String>?
Transformed details map.
imageUrl
String?
URL for the image.
faces
List<String>?
List of detected faces.
identificationDocumentCapture
IdentificationDocumentCapture?
Identification document capture details.
IDResponseModel
Field
Type
Description
destinationEndpoint
String?
Destination endpoint.
idExtractedModel
IDExtractedModel?
Extracted model for ID data.
error
String?
Error message.
success
Boolean?
Success status.
IDExtractedModel
Field
Type
Description
outputProperties
Map<String, Any>?
Output properties map.
transformedProperties
Map<String, String>?
Transformed properties map.
extractedData
Map<String, Any>?
Extracted data map.
imageUrl
String?
URL for the image.
faces
List<String>?
List of detected faces.
identificationDocumentCapture
IdentificationDocumentCapture?
Identification document capture details.
FaceResponseModel
Field
Type
Description
destinationEndpoint
String?
Destination endpoint.
faceExtractedModel
FaceExtractedModel?
Extracted model for face data.
error
String?
Error message.
success
Boolean?
Success status.
FaceExtractedModel
Field
Type
Description
outputProperties
Map<String, Any>?
Output properties map.
extractedData
Map<String, Any>?
Extracted data map.
baseImageFace
String?
Base image face.
secondImageFace
String?
Second image face.
percentageMatch
Int?
Percentage match between faces.
isLive
Boolean?
Whether the face is live.
identificationDocumentCapture
IdentificationDocumentCapture?
Identification document capture details.
IdentificationDocumentCapture
Field
Type
Description
name
Any?
Name of the document holder.
surname
Any?
Surname of the document holder.
documentType
Any?
Type of the document.
birthDate
Any?
Birthdate of the document holder.
documentNumber
Any?
Document number.
sex
Any?
Sex of the document holder.
expiryDate
Any?
Expiry date of the document.
country
Any?
Country of the document.
nationality
Any?
Nationality of the document holder.
idType
Any?
ID type of the document.
faceCapture
Any?
Face capture details.
image
Any?
Image of the document.
isSkippedAfterMRZFails
Any?
Whether MRZ failed after skipping.
isFailedFront
Any?
Whether the front check failed.
isFailedBack
Any?
Whether the back check failed.
skippedStatus
Any?
Skipped status.
capturedVideoFront
Any?
Captured video of the front.
capturedVideoBack
Any?
Captured video of the back.
livenessStatus
Any?
Liveness status of the document holder.
isFrontAuth
Any?
Whether the front is authorized.
isBackAuth
Any?
Whether the back is authorized.
isExpired
Any?
The document isExpired (true, false).
isTampering
Any?
The document is tampered (true, false).
tamperHeatMap
Any?
The URL to the tampering heatmap.
isBackTampering
Any?
The back of the document has been tampered.
backTamperHeatmap
Any?
The URL to the heatmap of the back-side of the document.
originalBackImage
Any?
The URL to the back-side of the image.
ghostImage
Any?
The URL to the ghost image.
idMaritalStatus
Any?
The marital status.
idDateOfIssuance
Any?
The date of issuance.
idCivilRegisterNumber
Any?
The civil register number.
idPlaceOfResidence
Any?
The place of residence.
idProvince
Any?
The province.
idGovernorate
Any?
The governorate.
idMothersName
Any?
The mother's name.
idFathersName
Any?
The father's name.
idPlaceOfBirth
Any?
The place of birth.
idBackImage
Any?
The URL to the back image.
idBloodType
Any?
The blood type.
idDrivingCategory
Any?
The driving category.
idIssuanceAuthority
Any?
The issuance authority that issued the ID.
idArmyStatus
Any?
The army status.
idProfession
Any?
The profession of the ID holder.
idUniqueNumber
Any?
The unique number on the ID card.
idDocumentTypeNumber
Any?
The ID document number.
idFees
Any?
The fees paid.
idReference
Any?
The reference data associated with the ID card.
idRegion
Any?
The region.
idRegistrationLocation
Any?
The registration location.
idFaceColor
Any?
The face color.
idEyeColor
Any?
The eye color.
idSpecialMarks
Any?
Any special marks (tattoos, etc.).
idCountryOfStay
Any?
The current country of stay.
idIdentityNumber
Any?
The Identity Number of the ID.
idPresentAddresss
Any?
The card holder present address.
idPermanentAddresss
Any?
The card holder permanent address.
idFamilyNumber
Any?
The family number.
identityNumberBack
Any?
The identity number found on the back of the ID card.
DocumentTokensModel
Field
Type
Description
displayName
String
Token name.
id
int
Token id.
templateId
int
Document id.
tokenTypeEnum
int
Token type.
CreateUserDocumentResponseModel
Field
Type
Description
documentId
int
Document id.
isPdf
bool
Is HTML or PDF.
templateInstance
String
Document as base64 after filling the tokens.
templateInstanceId
int
The new document id.
SignatureResponseModel
Field
Type
Description
fileName
String
Document name.
signedDocument
bool
Document as base64 after signed.
signedDocumentUri
String
Document as URL after signed.
Callback Events
The following callback events are fired against BaseResponseDataModel during processing.
Event
Description
onSend()
Starts processing.
onRetry()
Invoked when processing fails.
onComplete()
Called when processing is complete.
onEnvironmentalConditionsChange()
Provides real-time updates on environmental conditions like brightness and motion changes.
onWrongTemplate() (ID Card)
Called when trying to scan a wrong ID based on the submitted template.
onCurrentLiveMoveChange() (Face)
Provides real-time updates about what the current action required from the user is.
onStartNfcScan() (NFC)
Called when NFC starts.
onCompleteNfcScan() (NFC)
Called when NFC processing is complete.
onErrorNfcScan() (NFC)
Invoked when processing fails.
onCollectingManualImages() (Face)
In manual scan mode, after the user clicks "Take Photo", this function notifies the user that multiple images will be captured in order to verify liveness detection. After that, the onSend function is called.
Language Transformation
A list of LanguageTransformationModel objects is created and populated with different language transformation configurations. Each model specifies the type of language transformation (either translation or transliteration), a key-value pair, the target language, and the data type for that transformation.
Parameter
Description
languageTransformationEnum
The type of transformation (transliteration or translation).
Key and value strings
Placeholders ("Your Key", "Your Value") for specific content you want to work with.
Language
The target language (for example English, Arabic, Azerbaijani).
DataType
The type of data being transformed (text, date, number).
FAQ
Can you set what data the ResponseModels have from the admin page?
No, the response models are static and are based on responses from our core ID orchestrator.
When the onComplete callback is triggered (for example for the passport), can that data be retrieved or a hook triggered on our backend?
When the callback is triggered, the application receives all the information. It is the responsibility of the application to transfer that data to any specific backend at this point. If the data can be transferred at a later stage or when it has been submitted to our platform, then yes, you can define a webhook in the connector block to be triggered after submission to inform your backend or send you specific data.
What are the KycDocumentDetails on the ScanIDCard? How would I know how many to add to the list?
The template chosen from the getTemplates() callback.
Are there any actions allowed to be triggered programmatically on the scan screens (ScanIDCard, FaceMatch, etc.)?
For features like ScanIDCard and FaceMatch, these are returned as fragments, allowing you to draw on top of them. For ScanIDCard, you receive each page in order via the onComplete callback. The camera will automatically start scanning the next page after each callback.
On the FaceMatchActivity there is a static document image being loaded to be matched against the face. How can I get the document scanned on the previous step to pass it to the face match?
You can obtain the imageUrl from the onComplete callback for document scanning, convert it to base64, and use it in face match.
What happens if the document had multiple sides? How can I find which document had the photo of the user to pass to the FaceMatch?
You must choose an order (page) that contains a face to set it for face match. When the document URL is retrieved from the document scan, we flag that it has a face extracted based on the template.
What data should you submit on startSubmitData? Are these specified from the admin page?
You must prepare your list of steps with the outputProperties obtained for each step. For example:
On the StepNames file there are various keys used for uploading the data on startSubmitData. How do these correlate with the admin page? Where can I find this mapping?
In Flow Builder, after selecting a flow from Flow Manager, you are presented with the various blocks that make up the flow. To view the additional keys per flow, select the magnifier icon on the BlockLoader; you can press the magnifier icon and see all the data there. You can also define and add new data points.
