1 de 3

Components

In this section, you will find the components that can be used with by Unico

Redirecting the user

In this section, you will find information on how to redirect a user in your applications within the by Unico experience

he userRedirectUrl field is used to direct the user. This field is received in the success response of the process creation when making the CreateProcess request.

Here you will find three ways to manage the user experience in web applications:

(1) Using Redirect:

It is recommended to follow these steps:

In your common flow (which includes the by Unico Registration), you will redirect the client to the link generated through the API;
After that, the client within the platform carries out the necessary procedures to continue the flow;
When completed, they are redirected to your page (using the redirectUrl provided during the process creation).

(2) Using `window.open()`:

The window.open() option consists of opening a new tab in the user's browser so that they can complete the process. At the end, this tab is closed and redirected to your application.

For this, it is recommended to:

ollow the public documentation on this, which can be found here;
Monitorar se houve alteração de URL (para a redirectUrl) e então fechar a aba utilizando window.close().

Step 1: Using CustomTabs for Integration

1 - Add the necessary dependency for using CustomTabs in your app/build.gradle:

implementation("androidx.browser:browser:1.5.0")

Step 2: Opening a CustomTab

import android.net.Uri
import androidx.activity.ComponentActivity
import androidx.browser.customtabs.CustomTabsClient
import androidx.browser.customtabs.CustomTabsIntent

class CustomTabActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       openCustomTab(<URL_CBU>)
    }

    fun openCustomTab(url: String) {
        val builder = CustomTabsIntent.Builder()
        val customTabsIntent = builder.build()
        customTabsIntent.launchUrl(this, Uri.parse(url))
    }
}

Step 3: Modifying AndroidManifest

Add the necessary permissions and intents in the AndroidManifest.xml for the Activity that you want to receive the callback_uri. It is necessary to include the attribute android:launchMode="singleTop" as well as the <data> tag providing the URI data.

xml

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/> 
// ermissions for camera and geolocation are required

<activity
    android:name=".CustomTabActivity"
    android:exported="true"
    android:label="@string/app_name"
    android:theme="@style/Theme.Customtabs"
    android:launchMode="singleTop">

    <intent-filter android:label="Custom Tab">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- scheme e host são os dados fornecidos na criação de um processo no campo callback_uri
        callback_uri: "foobar://success?code=1234" -->
        <data android:scheme="foobar" android:host="success"/>
    </intent-filter>

</activity>

The following permissions are necessary for it to function correctly:

Camera
Geolocation

Step 4: Getting Return Information

o retrieve redirect information with the provided data, you can use the following code in the onNewIntent method of your Activity:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    val url = intent.data
    val scheme = url.scheme // "foobar"
    val host = url.host // "success"
    val code = url.getQueryParameter("code") // "1234"
}

Passo 1: Criar o controlador de autenticação

1 - O primeiro passo é criar o controlador de autenticação, e, para isso crie uma classe chamada UnicoAuthenticationController (ou como preferir chamar).

2 - Na sequência, importe o framework AuthenticationServices no topo da classe.

3 - Declare a classe como NSObject e implemente o protocolo ASWebAuthenticationPresentationContextProviding.

O resultado deve ser:

import AuthenticationServices

class UnicoAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Passo 2: Implementar a autenticação

1 - Abra o arquivo onde você executa a autenticação e adicione as importações necessárias (como exemplo, o ContentView.swift é usado).

import SwiftUI
import AuthenticationServices

2 - Para controlar o estado do fluxo é preciso criar a propriedade @State.

@State private var finished = false

3 - Crie uma instância da classe UnicoAuthenticationController fora do corpo da estrutura ContentView.

let unicoController = UnicoAuthenticationController()

4 - Para a validação do processo, crie uma função chamada redirectUser.

func redirectUser() {
        guard let url = URL(string: "URL_AUTHENTICATION") else { return }

        var session: ASWebAuthenticationSession?
        session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
            guard callbackURL != nil else {
                if let error = error {
                    return print("Erro durante o processo: \(error.localizedDescription)")
                }
                return
            }

            // Processa o URL de callback para verificar se o processo foi finalizado
            session?.cancel()
            finished = true
        }

        session?.presentationContextProvider = unicoController
        session?.prefersEphemeralWebBrowserSession = true
        session?.start()
    }

Ambientes:

Lembre-se de alterar a url URL_AUTHENTICATION para a URL de autenticação recebida em seu processo e também o callbackURLScheme BUNDLE para o redirect informado na criação do processo (o uso do Bundle Identifier de seu aplicativo é recomendado).

Autenticação única:

É importante setar prefersEphemeralWebBrowserSession para true para garantir uma autenticação única por processo.

Our support is limited to applications developed directly on the native Android and iOS platforms, using their respective native modules. At this time, we do not offer support for applications developed in hybrid frameworks, such as React Native, Ionic, or other cross-platform development technologies.

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

iFrame

In this section, you will find information on how to implement the opening of by Unico through an iFrame in web journeys

How to start

The iFrame is widely used in web scenarios. To use by Unico through an iFrame, the first step is to register the domains that will be used as hosts to display the user journey iFrame in by Unico.

Please inform the person responsible for your integration project or the Unico support team to carry out this configuration.

To start using the iFrame, we must begin with the installation of the Unico web SDK. by Unico uses the same SDK that is used for IDPay:

Available methods

init(options)

This method initializes the SDK by preloading assets, creating a smoother experience for the end user. At this point, it is necessary to send the token received as a result of the CreateProcess.

Parameters:

options - an object with the following configuration properties:
- type
  - The type of flow to be initialized. In by Unico, we use the "IFRAME" option.
- token
  - Receives the token of the created process. This token is important to authenticate the journey and ensure that only authorized domains can use it (can be obtained when creating the process via API).

open(options)

This method opens the by Unico experience. For the IFRAME flow, this function displays the already preloaded iFrame and initiates the messaging flow between the client page and the by Unico experience.

Parameters:

options - an object with configuration properties:

processId
- Receives the ID of the created process. This ID is important to obtain the process details and carry out the entire flow correctly (can be obtained when creating the process via API).
token
- Receives the token of the created process. This token is important to authenticate the journey and ensure that only authorized domains can use it (can be obtained when creating the process via API).
onFinish(process)
- Receives a callback function that will be executed at the end of the by Unico journey, passing the process object with the following data: { captureConcluded, concluded, id }.

The sequence diagram below demonstrates how to use the SDK and the API result from by Unico to configure the iFrame:

Opt for the Iframe Solution with Auth Token Instead of CSP

After careful analysis of our needs and challenges, we have decided to adopt a solution based on iframes with authentication tokens rather than implementing a Content Security Policy (CSP). This choice was motivated by various considerations related to the security and flexibility required to meet our clients' demands.

Context and Challenges with CSP

Content Security Policy (CSP) is a powerful tool for protecting web applications against various types of attacks, such as Cross-Site Scripting (XSS) and code injection. However, when configuring a CSP policy, it is necessary to define a strict list of trusted domains. This approach is effective when the domains are fixed and predictable. However, for our clients, who often use dynamic and variable domains, this rigid configuration presents significant challenges.

Vulnerability with Dynamic Domains

Dynamic domains pose a substantial security risk when using CSP. When a client has domains that frequently change or are created dynamically, it would be necessary to constantly update the CSP policy to include these new domains. This not only increases maintenance efforts but also exposes the domains to which the CSP policy applies. Each domain added to the CSP policy is potentially a vulnerability point if not adequately managed.

Solution with Iframe and Auth Token

To mitigate these risks and meet the flexibility required by our clients, we opted to use iframes combined with authentication tokens. This solution provides an additional layer of security and avoids the need to expose or manage an extensive and dynamic list of domains.

How It Works

Secure Authentication: Each iframe is loaded with a unique authentication token for each transaction, ensuring that only authorized users can access the content. This token is verified in real-time, providing an additional layer of security and control.
Content Isolation: The use of iframes allows for the isolation of content in a separate context, reducing the risk of interference between different origins and mitigating potential attacks.
Flexibility for Dynamic Domains: By not relying on a static CSP policy, our solution easily adapts to our clients' dynamic domains without the need for constant updates to security policies.

Redirecting the user

In this section, you will find information on how to redirect a user in your applications within the by Unico experience

he userRedirectUrl field is used to direct the user. This field is received in the success response of the process creation when making the CreateProcess request.

Here you will find three ways to manage the user experience in web applications:

(1) Using Redirect:

It is recommended to follow these steps:

In your common flow (which includes the by Unico Registration), you will redirect the client to the link generated through the API;
After that, the client within the platform carries out the necessary procedures to continue the flow;
When completed, they are redirected to your page (using the redirectUrl provided during the process creation).

(2) Using `window.open()`:

The window.open() option consists of opening a new tab in the user's browser so that they can complete the process. At the end, this tab is closed and redirected to your application.

For this, it is recommended to:

ollow the public documentation on this, which can be found here;
Monitorar se houve alteração de URL (para a redirectUrl) e então fechar a aba utilizando window.close().

Step 1: Using CustomTabs for Integration

1 - Add the necessary dependency for using CustomTabs in your app/build.gradle:

implementation("androidx.browser:browser:1.5.0")

Step 2: Opening a CustomTab

import android.net.Uri
import androidx.activity.ComponentActivity
import androidx.browser.customtabs.CustomTabsClient
import androidx.browser.customtabs.CustomTabsIntent

class CustomTabActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       openCustomTab(<URL_CBU>)
    }

    fun openCustomTab(url: String) {
        val builder = CustomTabsIntent.Builder()
        val customTabsIntent = builder.build()
        customTabsIntent.launchUrl(this, Uri.parse(url))
    }
}

Step 3: Modifying AndroidManifest

xml

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/> 
// ermissions for camera and geolocation are required

<activity
    android:name=".CustomTabActivity"
    android:exported="true"
    android:label="@string/app_name"
    android:theme="@style/Theme.Customtabs"
    android:launchMode="singleTop">

    <intent-filter android:label="Custom Tab">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- scheme e host são os dados fornecidos na criação de um processo no campo callback_uri
        callback_uri: "foobar://success?code=1234" -->
        <data android:scheme="foobar" android:host="success"/>
    </intent-filter>

</activity>

The following permissions are necessary for it to function correctly:

Camera
Geolocation

Step 4: Getting Return Information

o retrieve redirect information with the provided data, you can use the following code in the onNewIntent method of your Activity:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    val url = intent.data
    val scheme = url.scheme // "foobar"
    val host = url.host // "success"
    val code = url.getQueryParameter("code") // "1234"
}

Passo 1: Criar o controlador de autenticação

1 - O primeiro passo é criar o controlador de autenticação, e, para isso crie uma classe chamada UnicoAuthenticationController (ou como preferir chamar).

2 - Na sequência, importe o framework AuthenticationServices no topo da classe.

3 - Declare a classe como NSObject e implemente o protocolo ASWebAuthenticationPresentationContextProviding.

O resultado deve ser:

import AuthenticationServices

class UnicoAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Passo 2: Implementar a autenticação

1 - Abra o arquivo onde você executa a autenticação e adicione as importações necessárias (como exemplo, o ContentView.swift é usado).

import SwiftUI
import AuthenticationServices

2 - Para controlar o estado do fluxo é preciso criar a propriedade @State.

@State private var finished = false

3 - Crie uma instância da classe UnicoAuthenticationController fora do corpo da estrutura ContentView.

let unicoController = UnicoAuthenticationController()

4 - Para a validação do processo, crie uma função chamada redirectUser.

func redirectUser() {
        guard let url = URL(string: "URL_AUTHENTICATION") else { return }

        var session: ASWebAuthenticationSession?
        session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
            guard callbackURL != nil else {
                if let error = error {
                    return print("Erro durante o processo: \(error.localizedDescription)")
                }
                return
            }

            // Processa o URL de callback para verificar se o processo foi finalizado
            session?.cancel()
            finished = true
        }

        session?.presentationContextProvider = unicoController
        session?.prefersEphemeralWebBrowserSession = true
        session?.start()
    }

Ambientes:

Autenticação única:

É importante setar prefersEphemeralWebBrowserSession para true para garantir uma autenticação única por processo.

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

iFrame

In this section, you will find information on how to implement the opening of by Unico through an iFrame in web journeys

How to start

The iFrame is widely used in web scenarios. To use by Unico through an iFrame, the first step is to register the domains that will be used as hosts to display the user journey iFrame in by Unico.

Please inform the person responsible for your integration project or the Unico support team to carry out this configuration.

To start using the iFrame, we must begin with the installation of the Unico web SDK. by Unico uses the same SDK that is used for IDPay:

Available methods

init(options)

This method initializes the SDK by preloading assets, creating a smoother experience for the end user. At this point, it is necessary to send the token received as a result of the CreateProcess.

Parameters:

options - an object with the following configuration properties:
- type
  - The type of flow to be initialized. In by Unico, we use the "IFRAME" option.
- token
  - Receives the token of the created process. This token is important to authenticate the journey and ensure that only authorized domains can use it (can be obtained when creating the process via API).

open(options)

Parameters:

options - an object with configuration properties:

processId
- Receives the ID of the created process. This ID is important to obtain the process details and carry out the entire flow correctly (can be obtained when creating the process via API).
token
- Receives the token of the created process. This token is important to authenticate the journey and ensure that only authorized domains can use it (can be obtained when creating the process via API).
onFinish(process)
- Receives a callback function that will be executed at the end of the by Unico journey, passing the process object with the following data: { captureConcluded, concluded, id }.

The sequence diagram below demonstrates how to use the SDK and the API result from by Unico to configure the iFrame:

Security

Opt for the Iframe Solution with Auth Token Instead of CSP

Context and Challenges with CSP

Vulnerability with Dynamic Domains

Solution with Iframe and Auth Token

How It Works

Secure Authentication: Each iframe is loaded with a unique authentication token for each transaction, ensuring that only authorized users can access the content. This token is verified in real-time, providing an additional layer of security and control.
Content Isolation: The use of iframes allows for the isolation of content in a separate context, reducing the risk of interference between different origins and mitigating potential attacks.
Flexibility for Dynamic Domains: By not relying on a static CSP policy, our solution easily adapts to our clients' dynamic domains without the need for constant updates to security policies.

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our .

Components

Redirecting the user

(1) Using Redirect:

(2) Using window.open():

Step 1: Using CustomTabs for Integration

Step 2: Opening a CustomTab

Step 3: Modifying AndroidManifest

Step 4: Getting Return Information

Passo 1: Criar o controlador de autenticação

Passo 2: Implementar a autenticação

iFrame

How to start

Available methods

init(options)

open(options)

Opt for the Iframe Solution with Auth Token Instead of CSP

Context and Challenges with CSP

Vulnerability with Dynamic Domains

Solution with Iframe and Auth Token

How It Works

Redirecting the user

(1) Using Redirect:

(2) Using window.open():

Step 1: Using CustomTabs for Integration

Step 2: Opening a CustomTab

Step 3: Modifying AndroidManifest

Step 4: Getting Return Information

Passo 1: Criar o controlador de autenticação

Passo 2: Implementar a autenticação

iFrame

How to start

Available methods

init(options)

open(options)

Security

Opt for the Iframe Solution with Auth Token Instead of CSP

Context and Challenges with CSP

Vulnerability with Dynamic Domains

Solution with Iframe and Auth Token

How It Works

Security

(2) Using `window.open()`:

(2) Using `window.open()`: