Client data

About client data

Our client data feature enables you to attach custom data when starting an authentication or updating an authentication method. This data is held securely during the flow, then is returned to your service when the operation is complete.

This allows you to maintain state or pass essential metadata throughout the flow, ensuring that the context of the original request is preserved.

Example use cases

Use case 1: Maintain transaction context

You can use client data to maintain the context of the transaction. For example:

1. Your end-user initiates a payment in your banking app.
2. Your app passes the transaction details as client data, such as the amount, recipient and unique transaction ID.
3. When your end-user authenticates to approve the payment, this data is returned to the Encap server.
4. The service verifies that the details of the approved transaction match the initial request, preventing data loss or tampering during the flow.

Use case 2: Pass client metadata

You can use client data to pass metadata about the client, then utilise this data as required. For example:

1. You send information about the client environment, such as the application name and version, or a custom user agent string.
2. You use this metadata for server-side logging, analytics, or enabling specific logic or feature flags based on the client that initiated the request.

How to implement client data

When initiating an authentication or adding an authentication method, you provide an optional string of client data.

This string must adhere to the following rules:

• Maximum size: The string must not exceed 1024 bytes and has to be UTF-8 encoded.
• Character encoding: The string must not contain 4-byte UTF-8 characters. This includes most emojis and and certain other symbols, for example: 🎉 and 👍.

To learn about how this might look for both platforms, see the Android and iOS examples below.

Android examples

The example below shows an Android authentication flow with client data:

Example: Start authentication flow with client data

// Controller interface
fun startAuthentication(clientData: String?, appCallback: AsyncCallback<StartAuthenticationResult>)

// Usage
controller.startAuthentication("clientDataExample", appCallback)

The example below shows an Android add or update flow with client data:

Example: Start add or update flow with client data

// Controller interface
fun startAddOrUpdate(startParameter: StartAddOrUpdateParameter, appCallback: AsyncCallback<StartAddOrUpdateResult>)

// Usage
val startParameter = StartAddOrUpdateParameter("clientDataExample", null)
controller.startAddOrUpdate(startParameter, appCallback)

iOS examples

The example below shows an iOS authentication flow with client data:

Example: Start authentication flow with client data

// Controller interface
public func startAuthentication(clientOnly: Bool, clientData: String? = nil, onCompletion: @escaping (Result<StartAuthenticationResult, ErrorResult>) -> ())

// Usage
let clientData = "clientDataExample"
EncapController.shared.startAuthentication(clientOnly: false, clientData: clientData) { result in
    switch result {
        case .success(let successResult):
            //Success
        case .failure(let errorResult):
            // Error
    }
}

The example below shows an iOS add or update flow with client data:

Example: Start add or update flow with client data

// Controller interface
public func startAddOrUpdate(startAddOrUpdateParameter: StartAddOrUpdateParameter? = nil, onCompletion: @escaping (Result<StartAddOrUpdateResult, ErrorResult>) -> ())

// Usage
let clientData = "clientDataExample"
let startParam = EncapStartAddOrUpdateParameter(clientData: clientData, selectedAuthMethod: .device)
EncapController.shared.startAddOrUpdate(startAddOrUpdateParameter: startParam, onCompletion: { onCompletion in
    switch onCompletion {
        case .success(let successResult):
            // Success
        case .failure(let errorResult):
            // Error
    }
})