# Advanced Integration - Java SDK
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.42
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.42")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username","password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
We set:
- the strategy
- the callback URL
- the product that we want to use
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The product that we want to use is the **Identity** product, which allows us to specify what kind of
information about the user we want to get. In our example we would like to retrieve the person first
and last name and to do that we use the `IdentityProductQueryBuilder` class and provide the list of
fields to retrieve:
```java
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
### Working with Callbacks
The Java SDK can also be used to parse the information sent to your callback URL. For example, to run a simple
HTTP web server that is able to accept the conversation callback payload and read the person first and last name
from the above example we could use the following code:
```java
import com.authologic.client.api.*;
import com.authologic.client.json.JacksonJsonEngineProvider;
import io.javalin.Javalin;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
JacksonJsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
Javalin app = Javalin.create()
.post("/", ctx -> {
Callback callback = jsonEngine.deserialize(ctx.body(), Callback.class);
if (callback.isConversationFinished()) {
Conversation conversation = callback.asConversationFinished().getConversation();
PersonName personName = conversation.getResult().getIdentity().getUser().getPerson().getName();
System.out.println("Person: " + personName.getFirstName() + ", " + personName.getLastName());
}
ctx.status(HttpStatus.OK);
})
.start(8080);
}
}
```
The code uses [Javalin](https://javalin.io/) - a simple web framework for Java and Kotlin.
#### Initializing JSON Parser
We start by initializing the JSON parser, so we can easily parse the response.
We do it only once as the parser is thread-safe and can be reused later when needed:
```java
JacksonJsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
```
#### Deserializing the Results
Without focusing on the [Javalin](https://javalin.io/) itself, it provides the `Context` object -
the `ctx` variable in the above example that we can use to read the request body. We retrieve it
and deserialize it to the `CallbackResult` class using the initialized JSON parser:
```java
Callback callbackResult = jsonEngine.deserialize(ctx.body(), Callback.class);
```
The abstract Callback class provides two methods to identify the type of the result:
- the `isConversationFinished` returning `true` if the result is of type `Conversation` representing conversation
- the `isUnknownCallback` returning `true` if the result is of type `UnknownCallback` representing unknown callback
In the example code we expect the FinishedConversationCallback, so we check for it:
```java
if (callback.isConversationFinished()) {
```
After we verified that we got the class we were expecting we can retrieve the conversation from the
deserialized object and print out the identified person first and second name:
```java
Conversation conversation = callback.asConversationFinished().getConversation();
PersonName personName = conversation.getResult().getIdentity().getUser().getPerson().getName();
System.out.println("Person: " + personName.getFirstName() + ", " + personName.getLastName());
```
## License
Copyright 2024 Authologic
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
language governing permissions and limitations under the License.
Despite our sincere intentions, it is difficult to create perfect technical documentation.
If you have an idea on how to improve this documentation, or you have trouble understanding any section,
please email us at [tech-support@authologic.com](mailto:tech-support@authologic.com)