By default, Authologic displays all pages that the user visits. These pages can be adapted to your visual identity, but sometimes it is necessary to prepare a more complex user interface.
Therefore, Authologic provides advanced customization options, where the entire appearance is generated on your side. Importantly, this way of integration is an extension of the standard integration, so the decision on additional customization can be made at any time.
Scheme of operation
In the basic integration, after creating a conversation, the user is redirected to the address on the Authologic side, where information is presented and the necessary data is collected from the user.
In the advanced integration, the user is not redirected to the Authologic pages. Instead, through the API, information is retrieved about which page and how should be displayed and what data from the user should be collected.
Thus, you yourself render the necessary page based on the provided data. Then the data collected from the user is transferred again via API and information about the next step (page) will be returned again. The transmission of data and the return of information about the following pages takes place until the identification is made or it is necessary to redirect the user to an external website, e.g. a bank.
The Customization API consists of the two methods described below.
Current Page
In order to get the current page, please execute the query GET/api/conversations/{conversationId}/page/current.
It is also necessary to set the header X-User-IP with the IP address of the user to whom the page will be shown.
Of course, the Accept,` Content-Type` and Authorization headers should also be set in the same way as for other API methods.
In response, Authologic returns information about the following format:
{
"render":{
"page": "pageName",
"redirect": "https://page.to.redirect/",
"header": {
"main": {
"title": "Page title",
"subtitle": "Page subtitle",
"howItWorks": "Description of how the process works on a given page"
},
"group": {
"title": "Subpage title",
"subtitle": "Subpage subtitle",
"howItWorks": "Description of how the process works on a given subpage"
}
},
"args": {
"list": ["value"],
"obj": {
"field": "value"
}
},
"errors": {
"fields": {
"fieldName": "error description"
},
"accepted": {
"fieldName": "correct value"
},
"rejected":{
"fieldName": "denied value"
},
"globals": [
"error description"
]
},
"reloadCurrent": false
},
"next": {
"call": "nextPageID",
"args": [
"parameterName"
],
"options": {
"_optionName": ["value1", "value2"]
},
"async": 5
}
}Below is a description of each parameter:
| Parameter | Required | Example | Description |
|---|---|---|---|
render.page |
baList |
Name of the page that should be shown. If it is not present, it means that the user should be redirected
to the page specified in |
|
render.redirect |
https address |
The address of the page to which the user should be redirected in order to continue the process. In this case, subsequent pages, if
needed, will be generated by Authologic. If |
|
render.header.main |
- |
A section that defines page descriptions, i.e. the title, subtitle and description of how the process works on the page |
|
render.header.main.title |
title |
Page title |
|
render.header.main.subtitle |
subtitle |
Page subtitle |
|
render.header.main.howItWorks |
action description |
Description of how the process works on a given page |
|
render.header.group |
- |
Section defining subpage descriptions. A subpage can be defined, for example, when we have grouped data to present, where an additional sub-selection is possible for the selected element. An example of a section defining a subpage can be seen in the description of strategy public:bn |
|
render.header.group.title |
title |
Subpage title |
|
render.header.group.subtitle |
subtitle |
Subpage subtitle |
|
render.header.group.howItWorks |
action description |
Description of how the process works on a given subpage |
|
render.args |
any json |
Parameters necessary to display a given page, depending on a specific page. For example, for a page with a list of banks to choose from by the user, it will be a structure containing, among other things, information about available banks. |
|
render.errors.fields |
map with field name and error description |
A map specifying incorrectly entered form fields and a description of the associated error. |
|
render.errors.accepted |
map containing the name of the field and its correctly given value |
A map that specifies correctly entered form fields and the value of this field. For example, for a page with validation errors, but the values are also correct. |
|
render.errors.rejected |
map containing the field name and its incorrect value |
A map specifying incorrectly entered form fields and the value of this field. |
|
render.errors.globals |
list of error descriptions |
A list containing errors not related to specific form fields. |
|
render.reloadCurrent |
true |
Parameter informing that information about the next page should be obtained by calling the method |
|
next.call |
fd78cf43-12a7… |
Name of the page to which the user information should be submitted. Information is sent via the method |
|
next.args |
parameter name list |
List of parameters that should be collected from the user and sent via the method |
|
next.options |
parameter name list |
Optional parameters that can be sent via the |
|
next.async |
numerical value |
The occurrence of this parameter informs that the current page should remain displayed for the user, and at the same time the
method |
The field content may contain additional information about the format that needs to be modified before displaying, e.g. replacing with appropriate HTML tags. There are currently two types of this information:
-
links in the form of [Display Name] (URL).
-
bold text in the form: *text*
{
"disclaimer": "Link to the *Authologic* page is [here](https://www.authologic.com)"
}Data retrieving
After collecting this data from the user (field next.args), it should be passed to the` POST/api/conversations/{conversationId}/page/{pageId}` method.
This method is responsible for collecting and analyzing this data. In the query it is also necessary to set the header X-User-IP with the IP address of the user to whom the page will be shown. Of course, the Accept,` Content-Type` and Authorization headers should also be set in the same way as for other API methods. The content of the query contains a map of parameter values, for example:
{
"consent": true,
"phone": "+48123123123"
}Multi-step verifications
If the process requires multiple redirection of the user to external websites (e.g. logging in to a bank), Authologic must know how to pass control to the place where subsequent pages will be rendered. For this purpose, when creating a conversation, the layoutUrl parameter should be specified. The user will be redirected there if there is a need to view further pages. If the address contains the string {conversationId}, it will be replaced with the current conversation ID.
Multiple Language
Support Authologic returns messages and texts to be displayed in the language specified with the standard HTTP header:
Accept-Language.
Identifiers and names
When creating your integration, please take into account that any identifiers and content provided by Authologic are dynamically generated based on the data of specific identity providers. This means that they can change at any time, and you should not create any business logic from these values. An example of this is bank identifiers. Assigning an identifier to a specific bank may change over time.
Image file formats
In some cases, the identity verification pages present images. An example is the icons of banks. Authologic will then prefer SVG files, but this will not always be possible. By creating your integration, you should assume that the format of these files depends on specific vendors and may change in time.