Handling interrupts

Possible interrupts are either dialogs that you have to display to your users or redirects, i.e., links to web pages to which you have to send users to.

Check interrupts:

JavaScript
Kotlin
Rust

switch (response.constructor) {
  case Result: ...; break
  case Dialog: ...; break
  case Redirect: ...; break
  case RedirectHandle: ...; break
}

javascript

when (response) {
    is Response.Dialog -> ...
    is Response.Redirect -> ...
    is Response.RedirectHandle -> ...
    is Response.Result -> ...
}

kotlin

match response {
    OBResponse::Result(result, session, connection_data) => ...
    OBResponse::Dialog(dialog) => ...
    OBResponse::Redirect(redirect) => ...
    OBResponse::RedirectHandle(handle) => ...
}

rust

Handle dialogs

Dialogs consist of an optional message and an optional image to display to the user as well as some input definition. Possible input types are:

Confirmation: The user needs to confirm the dialog. This is typically used when waiting for a decoupled authentication, e.g., confirmation in the bank’s app.
Selection: The user needs to choose from a list of options and confirm the choice.
Actions: The user needs to choose from a list of actions. This is very similar to a selection and could actually be implemented the same way but it might get rendered differently, typically as buttons that immediately confirm the dialog.
Field: A text input field in which the user has to enter some value.

Example 1. Confirmation dialog with message

Please confirm the transaction in your authenticator app.

Example 2. Selection dialog without message

mobileTAN

pushTAN

Example 3. Actions dialog without message

What kind of TAN do you want to use?

Example 4. Input dialog with message and image

Please use your TAN reader and enter the generated TAN.

The input details contain a context to continue with the process. Each service that might return interrupts also provides two ways for that, depending on the input type, e.g., for the accounts service:

Confirm dialog without input for the accounts service:

JavaScript
Kotlin
Rust

response = await client.confirmAccounts({ ticket, context })

javascript

response = client.confirmAccounts(ticket, context)

kotlin

let response = client.confirm_accounts(ticket, context).await?;

rust

Respond to any other dialog for the accounts service:

JavaScript
Kotlin
Rust

response = await client.respondAccounts({ ticket, context, response })

javascript

response = client.respondAccounts(ticket, context, response)

kotlin

let response = client.respond_accounts({ticket, context, response}).await?;

rust

The passed response is either the user’s choice from the list of options/actions or the user’s input. The result is, again, either another interrupt or the desired data.

This is an example for the Accounts service. See your client SDK for the respective methods for other services.

Handle redirects

In case of a redirect, the user gets sent to a given URL. Desktop or mobile applications could either open it in a browser or inside an element like a WebView. Eventually, the user gets redirected to a URI that you provide. You may use it to redirect the user back to a web application or to jump back into the context of a desktop or mobile application.

The easiest and most efficient way to obtain a redirect URL is to provide your redirect URI before calling any service:

Set redirect URI:

JavaScript
Kotlin
Rust

await client.setRedirectUri('myapp://redirect?context=signup')

javascript

client.setRedirectUri(java.net.URI("myapp://redirect?context=signup"))

kotlin

client.set_redirect_uri("myapp://redirect?context=signup")?;

rust

With a pre-set redirect URI services will provide redirect objects with the URL to send the user to and the context required to continue with the service.

If no redirect URI was set, the context will get returned along a handle that can be used to register a redirect URI and receive the redirect URL to use:

Register redirect URI:

JavaScript
Kotlin
Rust

let redirectUrl = await client.registerRedirectUri({
  ticket,
  handle,
  redirectUri: 'myapp://redirect?context=signup'
})

javascript

client.registerRedirectUri(
    ticket,
    handle,
    java.net.URI("myapp://redirect?context=signup"),
)

kotlin

let redirect_url = client.register_redirect_uri(
    ticket,
    handle,
    "myapp://redirect?context=signup",
).await?;

rust

When the redirect should be done, e.g., the URL that you provided got called or the user manually confirmed that he finished the process, you can continue with the redirect’s context as you would for a confirmation dialog:

Confirm redirect for the accounts service:

JavaScript
Kotlin
Rust

response = await client.confirmAccounts({
  ticket,
  context: redirect.context
})

javascript

client.confirmAccounts(
    ticket,
    context = redirect.context,
)

kotlin

let response = client
    .confirm_accounts(ticket, redirect.context)
    .await?;

rust

This is an example for the Accounts service. See your client SDK for the respective methods for other services.