# Iniziare a utilizzare i componenti incorporati di Connect

Incorporare le funzionalità della dashboard nel sito web

Utilizza i componenti incorporati di Connect per aggiungere al tuo sito web le funzionalità della Dashboard per gli account connessi. Queste librerie e l’API di supporto ti consentono di concedere agli utenti l’accesso ai prodotti Stripe direttamente dalla Dashboard e dalle applicazioni mobili.

Per una versione immersiva di questa guida, consulta la [Guida rapida per l’integrazione dei componenti incorporati di Connect](https://docs.stripe.com/connect/connect-embedded-components/quickstart.md). Puoi anche scaricare un esempio di integrazione. Per personalizzare l’aspetto dei componenti incorporati di Connect, utilizza le opzioni`appearance` quando utilizzi `StripeConnectInstance`. Consulta l’[elenco completo dei parametri di aspetto](https://docs.stripe.com/connect/customize-connect-embedded-components.md).

## Inizializzare Connect.js [Lato client] [Lato server]

Stripe utilizza un oggetto [AccountSession](https://docs.stripe.com/api/account_sessions.md) per esprimere la tua intenzione di delegare l’accesso API al tuo account connesso.

L’API AccountSessions restituisce una *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) che consente a un componente incorporato di accedere alle risorse di un account connesso come se facessi le chiamate API per suo conto.

### Crea un oggetto AccountSession (Server)

In un’applicazione a pagina singola, il client avvia una richiesta per ottenere la sessione dell’account sul server. Puoi creare un nuovo endpoint sul server che restituisce la chiave privata client al browser:

#### Ruby

```ruby
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret API key.
# Sign in to see your own test API key embedded in code samples.
# Don’t submit any personally identifiable information in requests made with this key.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: {{CONNECTED_ACCOUNT_ID}},
      components: {
        payments: {
          enabled: true,
          features: {
            refund_management: true,
            dispute_management: true,
            capture_payments: true
          }
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end
```

### Creare l’API Account Session

L’[API Create Account Session](https://docs.stripe.com/api/account_sessions/create.md) determina l’accesso ai componenti e alle funzionalità per i componenti integrati di Connect. Stripe applica questi parametri a tutti i componenti che corrispondono alla sessione dell’account. Se il tuo sito supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione dell’account corrispondano al ruolo dell’utente corrente. Se la tua app supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione account corrispondano al ruolo dell’utente corrente. Ad esempio, puoi abilitare la [gestione dei rimborsi](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-payments-features-refund_management) solo per gli amministratori del tuo sito, ma non per gli altri utenti. Per assicurarti che l’accesso ai ruoli utente sia applicato, devi mappare il ruolo utente del tuo sito ai componenti della sessione dell’account.

### Configura Connect.js (Client)

Consigliamo di configurare Connect.js con npm come mostrato nell’esempio seguente, ma è possibile anche [senza npm](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#without-npm).

#### HTML + JS

Installa il [pacchetto npm](https://github.com/stripe/connect-js) per utilizzare Connect.js come modulo.

```bash
npm install --save @stripe/connect-js
```

#### React

Installa Connect.js e le librerie React Connect.js dal [registro pubblico npm](https://www.npmjs.com/package/@stripe/react-connect-js).

```bash
npm install --save @stripe/connect-js @stripe/react-connect-js
```

### Carica e inizializza Connect.js (Client)

Chiama `loadConnectAndInitialize` con la tua chiave pubblicabile e una funzione che recupera una chiave privata client chiamando il nuovo endpoint che hai creato sul tuo server. Utilizza la `StripeConnectInstance` restituita per creare componenti incorporati. Dopo aver inizializzato Connect.js, puoi montare e smontare in qualsiasi momenti i componenti dal DOM, inclusi quelli visualizzati sui portali React o Vue.

#### HTML + JS

Per creare un componente, chiama `create` sulla `StripeConnectInstance` creata in precedenza, poi specifica il nome del componente. Viene restituito un [elemento personalizzato](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) che Connect.js registra e utilizza per collegare automaticamente il tuo DOM a Stripe. Infine utilizza `append` per aggiungere questo elemento al tuo DOM.

Chiama `create` con `payments`, poi aggiungi il risultato al tuo DOM per visualizzare un’interfaccia utente per i pagamenti.

#### React

Per utilizzare i componenti incorporati di Connect con i wrapper di React, inserisci la tua applicazione in `ConnectComponentsProvider` e specifica la `StripeConnectInstance` creata in precedenza.

Utilizza `ConnectPayments` sulla tua pagina per visualizzare un’interfaccia utente per i pagamenti.

#### HTML + JS

```html
<head>
  <script type="module" src="index.js" defer></script>
</head>
<body>
  <h1>Payments</h1>
  <div id="container"></div>
  <div id="error" hidden>Something went wrong!</div>
</body>
```

```javascript
import {loadConnectAndInitialize} from '@stripe/connect-js';

const fetchClientSecret = async () => {
  // Fetch the AccountSession client secret
  const response = await fetch('/account_session', { method: "POST" });
  if (!response.ok) {
    // Handle errors on the client side here
    const {error} = await response.json();
    console.error('An error occurred: ', error);
    document.querySelector('#error').removeAttribute('hidden');
    return undefined;
  } else {
    const {client_secret: clientSecret} = await response.json();
    document.querySelector('#error').setAttribute('hidden', '');
    return clientSecret;
  }
}

const stripeConnectInstance = loadConnectAndInitialize({
    // This is a placeholder - it should be replaced with your publishable API key.
    // Sign in to see your own test API key embedded in code samples.
    // Don’t submit any personally identifiable information in requests made with this key.
    publishableKey: "<<YOUR_PUBLISHABLE_KEY>>",
    fetchClientSecret: fetchClientSecret,
  });
const paymentComponent = stripeConnectInstance.create("payments");
const container = document.getElementById("container");
container.appendChild(paymentComponent);
```

[Visualizza l’elenco completo dei componenti incorporati supportati →](https://docs.stripe.com/connect/supported-embedded-components.md)

## Configure Connect.js [Lato client]

Il metodo `loadConnectAndInitialize` sul client richiede diverse opzioni per configurare Connect.js.

| Opzioni             | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `publishableKey`    | La [chiave pubblicabile](https://docs.stripe.com/keys.md) per la tua integrazione.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | obbligatorio |
| `fetchClientSecret` | La funzione che recupera la *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) restituita da `/v1/account_sessions`. Indica a `StripeConnectInstance` a quale account delegare l’accesso. Questa funzione viene utilizzata anche per recuperare una funzione della chiave privata client al fine di aggiornare la sessione alla scadenza. `fetchClientSecret` deve sempre creare una nuova sessione dell’account e restituire un nuovo `client_secret`. | obbligatorio |
| `appearance`        | Un oggetto per personalizzare l’aspetto dei componenti incorporati di Connect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | facoltativo  |
| `locale`            | Un parametro per specificare le [impostazioni licali](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#localization) utilizzate dai componenti incorporati di Connect. La lingua predefinita è la lingua del browser. Se le impostazioni locali specificate non sono direttamente supportate, utilizziamo un’alternativa ragionevole (ad esempio, per `fr-be` potrebbe essere utilizzato `fr-fr`). Consulta la sezione [localizzazione](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#localization) per l’elenco delle lingue supportate.                     | facoltativo  |
| `fonts`             | Matrice di caratteri personalizzati disponibili per l’utilizzo da parte di qualsiasi componente incorporato creato da una `StripeConnectInstance`. Puoi specificare i tipi di carattere come oggetti [CssFontSource](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#css-font-source) o [CustomFontSource](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#custom-font-source).                                                                                                                                                                                | facoltativo  |

### Personalizzare l’aspetto dei componenti incorporati di Connect

Il [toolkit Figma di componenti incorporati per personalizzare l’interfaccia utente](https://www.figma.com/community/file/1438614134095442934) contiene tutti i componenti, i pattern comuni e un’applicazione esemplificativa. Puoi utilizzarlo per visualizzare e progettare interfacce utente incorporate sul tuo sito web.

Offriamo una [serie di opzioni](https://docs.stripe.com/connect/embedded-appearance-options.md) per personalizzare l’aspetto dei componenti incorporati di Connect. Queste personalizzazioni influiscono su pulsanti, icone e altri elementi del nostro sistema di progettazione.

> #### Finestre popup necessarie
> 
> Alcuni comportamenti nei componenti incorporati, come l’[autenticazione utente](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components), devono essere presentati in una finestra popup. Non è possibile personalizzare il componente incorporato per eliminare tali finestre.

Puoi impostare queste opzioni quando inizializzi `StripeConnectInstance` specificando un aspetto nell’oggetto `appearance`. Puoi utilizzare solo le [opzioni Connect.js](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) per modificare gli stili nei componenti incorporati di Connect. La famiglia di caratteri e il colore dello sfondo dei componenti incorporati di Connect vengono ereditati dal contenitore HTML principale. Devi impostare esplicitamente tutte le altre opzioni.

```javascript
const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "<<YOUR_PUBLISHABLE_KEY>>",
  fetchClientSecret: fetchClientSecret,
  fonts: [
    {
      cssSrc: "https://myfonts.example.com/mycssfile.css",
    },
    {
      src: `url(https://my-domain.com/assets/my-font-2.woff)`,
      family: 'My Font'
    }
  ],
  appearance: {
    // See all possible variables below
    overlays: "dialog",
    variables: {
      fontFamily: 'My Font',
      colorPrimary: "#FF0000",
    },
  },
});
```

Consulta l’[elenco completo delle variabili di aspetto](https://docs.stripe.com/connect/embedded-appearance-options.md).

### L’oggetto fonts

L’oggetto `fonts` in `stripeConnect.initialize` accetta una matrice di oggetti [CssFontSource](https://docs.stripe.com/js/appendix/css_font_source_object) o [CustomFontSource](https://docs.stripe.com/js/appendix/custom_font_source_object).

Se utilizzi caratteri personalizzati nella pagina (ad es. file `.woff` o `.tff`), devi specificare i file dei caratteri durante l’inizializzazione dei componenti incorporati di Connect. In questo modo, i componenti incorporati di Connect possono visualizzare correttamente i caratteri. È possibile specificare i file nel modo seguente:

#### CssFontSource

Utilizza questo oggetto per specificare un URL del foglio di stile che definisce i tuoi caratteri personalizzati quando crei una `StripeConnectInstance`. Con un oggetto `CssFontSource`, la [configurazione CSP](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#csp-and-http-header-requirements) deve consentire il recupero dei domini associati agli URL dei file CSS specificati come CssFontSource.

| Nome     | Tipo               | Valore di esempio                                   |
| -------- | ------------------ | --------------------------------------------------- |
| `cssSrc` | stringa `required` | `https://fonts.googleapis.com/css?family=Open+Sans` | Un URL relativo o assoluto che punta a un file CSS con definizioni di [@font-face](https://developer.mozilla.org/en/docs/Web/CSS/@font-face). Il file deve essere in hosting su https. Se utilizzi un [criterio di sicurezza del contenuto (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy), il file potrebbe richiedere [direttive aggiuntive](https://docs.stripe.com/security/guide.md#content-security-policy). |

#### CustomFontSource

Utilizza questo oggetto per specificare i caratteri personalizzati quando crei una `StripeConnectInstance`.

| Nome           | Tipo               | Valore di esempio                               |
| -------------- | ------------------ | ----------------------------------------------- |
| `family`       | stringa `required` | `Avenir`                                        | Il nome da assegnare al carattere.                                                                                                                                                                                                                                                        |
| `src`          | stringa `required` | `url(https://my-domain.com/assets/avenir.woff)` | Un valore [src](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src) valido che punta al file del carattere personalizzato. Di solito, anche se non sempre, si tratta di un Link a un file con un suffisso `.woff`, `.otf` o `.svg`. Il file deve essere in hosting su https. |
| `display`      | stringa `optional` | `auto`                                          | Un valore [font-display](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) valido.                                                                                                                                                                                |
| `style`        | stringa `optional` | `normal`                                        | Uno dei seguenti valori: `normal`, `italic` o `oblique`.                                                                                                                                                                                                                                  |
| `unicodeRange` | stringa `optional` | `U+0-7F`                                        | Un valore [unicode-range](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range) valido.                                                                                                                                                                              |
| `weight`       | stringa `optional` | `400`                                           | Un valore [font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight) valido. Si tratta di una stringa, non di un numero.                                                                                                                                                 |

### Aggiornare i componenti incorporati di Connect dopo l’inizializzazione

Il metodo `update` supporta l’aggiornamento dei componenti incorporati di Connect dopo l’inizializzazione. È possibile utilizzarlo per cambiare le opzioni di aspetto in fase di esecuzione (senza aggiornare la pagina). Per farlo, utilizza lo stesso oggetto `stripeConnectInstance` che hai creato con `initialize` e chiama il metodo `update`:

```javascript
stripeConnectInstance.update({
  appearance: {
    variables: {
      colorPrimary: "#FF0000",
    },
  },
  locale: 'en-US',
});
```

> Non tutte le opzioni (ad esempio `fonts`) sono aggiornabili. Le opzioni supportate per questo metodo sono un sottoinsieme delle opzioni disponibili in `initialize`. In questo modo puoi aggiornare i parametri `appearance` e `locale`.

### Larghezza e altezza

I componenti incorporati di Connect si comportano come gli elementi HTML `block` standard. Per impostazione predefinita, prendono al 100% il valore `width` del loro elemento HTML principale e aumentano in altezza in base al contenuto visualizzato all’interno. Puoi controllare il valore `width` dei componenti incorporati di Connect specificando il valore `width` dell’elemento HTML principale. Non puoi controllare direttamente il valore `height` in quanto dipende dal contenuto visualizzato. Tuttavia, puoi limitare l’altezza con `maxHeight` e `overflow: scroll`, proprio come con altri elementi HTML `block`.

## Autenticazione

Offriamo una serie di API per gestire le sessioni degli account e le credenziali degli utenti nei componenti incorporati di Connect.

### Aggiornare la chiave privata client

Nelle sessioni di lunga durata, la sessione della *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) fornita inizialmente potrebbe scadere. Quando scade, utilizziamo automaticamente `fetchClientSecret` per recuperare una nuova chiave privata client e aggiornare la sessione. Non devi specificare alcun parametro aggiuntivo.

```javascript
import { loadConnectAndInitialize } from "@stripe/connect-js";
// Example method to retrieve the client secret from your server
const fetchClientSecret = async () => {
  const response = await fetch('/account_session', { method: "POST" });
  const {client_secret: clientSecret} = await response.json();
  return clientSecret;
}

const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "{{PUBLISHABLE_KEY}}",
  fetchClientSecret: fetchClientSecret,
});
```

### Disconnettersi

Ti consigliamo di chiamare `logout` nella `stripeConnectInstance` per eliminare l’oggetto AccountSession associato dopo che un utente si è disconnesso dalla tua app. In questo modo vengono disabilitati tutti i componenti incorporati di Connect che si collegano a quella `stripeConnectInstance`.

> #### Finestre popup necessarie
> 
> Richiama `logout` solo quando l’utente esce dall’app. Non richiamare logout quando un componente viene smontato (quando si naviga verso un’altra pagina o si chiude la pagina) o quando si caricano altri componenti, poiché questo metodo invalida completamente la sessione dell’account corrente e la [sessione utente Stripe](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=web#user-authentication-in-connect-embedded-components). Dopo aver richiamato `logout`, i componenti non vengono più visualizzati per `stripeConnectInstance` associato.

```javascript
// Call this when your user logs out
stripeConnectInstance.logout();
```

## Requisiti per le intestazioni CSP e HTTP

Se il tuo sito web implementa *Criteri di sicurezza del contenuto* (Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks), devi aggiornarli aggiungendo le seguenti regole:

- `frame-src` `https://connect-js.stripe.com` `https://js.stripe.com`
- `img-src` `https://*.stripe.com`
- `script-src` `https://connect-js.stripe.com` `https://js.stripe.com`
- `style-src` `sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk=` (SHA dell’elemento di stile vuoto)

Se utilizzi un file CSS per caricare [caratteri web](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#fonts-object) da utilizzare con componenti incorporati di Connect, l’URL deve essere consentito dalla direttiva CSP [connect-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src).

L’impostazione di determinate [intestazioni di risposta HTTP](https://developer.mozilla.org/en-US/docs/Glossary/Response_header) abilita la piena funzionalità dei componenti incorporati di Connect:

- [Cross-Origin-Opener-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy), `unsafe-none`. Il valore `unsafe-none` è il valore predefinito dell’intestazione, quindi funziona anche senza impostarlo. Altri valori come `same-origin` interrompono l’[autenticazione dell’utente](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components) nei componenti incorporati di Connect.

## Browser supportati

Supportiamo lo stesso set di browser attualmente supportati dalla [Dashboard Stripe](https://docs.stripe.com/dashboard/basics.md):

- Le ultime 20 versioni principali di Chrome e Firefox
- Le ultime due versioni principali di Safari ed Edge
- Le ultime due versioni principali di Safari per dispositivi mobili iOS

Non puoi utilizzare i componenti incorporati di Connect nelle viste web incorporate nelle applicazioni per dispositivi mobili o desktop. Per utilizzare i componenti incorporati di Connect in un’applicazione mobile, utilizza l’SDK [iOS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=ios), [Android](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=android) o [React Native](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=react-native).

Se un componente incorporato non è ancora supportato dai nostri SDK mobili, ti consigliamo di collegarti a un browser web in cui è possibile visualizzare i componenti incorporati.

## Localizzazione

Quando si inizializza [Connect.js](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), è possibile specificare un parametro `locale`. Per abbinare le impostazioni locali di un componente incorporato alle impostazioni locali del tuo sito web, specifica il parametro `locale` con le impostazioni locali dell’interfaccia utente del tuo sito web.

Il valore predefinito del parametro `locale` è determinato dalle impostazioni locali configurate dal browser. Se le impostazioni locali specificate non sono direttamente supportate, viene utilizzata un’alternativa ragionevole (ad esempio, per `fr-be` potrebbe essere utilizzato `fr-fr`).

I componenti incorporati di Connect supportano le seguenti lingue:

| Lingua                            | Codice lingua |
| --------------------------------- | ------------- |
| Bulgaro (Bulgaria)                | `bg-BG`       |
| Cinese (semplificato)             | `zh-Hans`     |
| Cinese (tradizionale - Hong Kong) | `zh-Hant-HK`  |
| Cinese (tradizionale - Taiwan)    | `zh-Hant-TW`  |
| Croato (Croazia)                  | `hr-HR`       |
| Ceco (Cechia)                     | `cs-CZ`       |
| Danese (Danimarca)                | `da-DK`       |
| Olandese (Paesi Bassi)            | `nl-NL`       |
| Inglese (Australia)               | `en-AU`       |
| Inglese (India)                   | `en-IN`       |
| Inglese (Irlanda)                 | `en-IE`       |
| Inglese (Nuova Zelanda)           | `en-NZ`       |
| Inglese (Singapore)               | `en-SG`       |
| Inglese (Regno Unito)             | `en-GB`       |
| Inglese (Stati Uniti)             | `en-US`       |
| Estone (Estonia)                  | `et-EE`       |
| Filippino (Filippine)             | `fil-PH`      |
| Finlandese (Finlandia)            | `fi-FI`       |
| Francese (Canada)                 | `fr-CA`       |
| Francese (Francia)                | `fr-FR`       |
| Tedesco (Germania)                | `de-DE`       |
| Greco (Grecia)                    | `el-GR`       |
| Ungherese (Ungheria)              | `hu-HU`       |
| Indonesiano (Indonesia)           | `id-ID`       |
| Italiano (Italia)                 | `it-IT`       |
| Giapponese (Giappone)             | `ja-JP`       |
| Coreano (Corea del Sud)           | `ko-KR`       |
| Lettone (Lettonia)                | `lv-LV`       |
| Lituano (Lituania)                | `lt-LT`       |
| Malese (Malaysia)                 | `ms-MY`       |
| Maltese (Malta)                   | `mt-MT`       |
| Norvegese bokmål (Norvegia)       | `nb-NO`       |
| Polacco (Polonia)                 | `pl-PL`       |
| Portoghese (Brasile)              | `pt-BR`       |
| Portoghese (Portogallo)           | `pt-PT`       |
| Rumeno (Romania)                  | `ro-RO`       |
| Slovacco (Slovacchia)             | `sk-SK`       |
| Sloveno (Slovenia)                | `sl-SI`       |
| Spagnolo (Argentina)              | `es-AR`       |
| Spagnolo (Brasile)                | `es-BR`       |
| Spagnolo (America Latina)         | `es-419`      |
| Spagnolo (Messico)                | `es-MX`       |
| Spagnolo (Spagna)                 | `es-ES`       |
| Svedese (Svezia)                  | `sv-SE`       |
| Tailandese (Thailandia)           | `th-TH`       |
| Turco (Turchia)                   | `tr-TR`       |
| Vietnamita (Vietnam)              | `vi-VN`       |

## Gestire gli errori di caricamento

Per gestire gli errori di caricamento dei componenti, si può definire un gestore di errori. A seconda della causa dell’errore, il gestore potrebbe essere richiamato più volte e deve garantire un comportamento idempotente.

#### HTML + JS

```js
// Load errors are emitted by all components. We use Balances as an example here.
const balances = stripeConnectInstance.create('balances');
balances.setOnLoadError((loadError) => {
  const componentName = loadError.elementTagName
  const error = loadError.error

  console.log(componentName + " failed to load")
  console.log(`${error.type}: ${error.message}`);
});

container.appendChild(balances);

```

#### HTML + JS

| Metodo           | Descrizione                                                                                   | Variabili                                                                                                                                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setOnLoadError` | Il componente esegue questa funzione di callback quando si verifica un errore di caricamento. | - `loadError.error`: Vedi [l’oggetto load error](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#the-load-object)
  - `loadError.elementTagName`: Nome del tag HTML utilizzato per visualizzare il componente nel browser |

#### React

| React prop    | Descrizione                                                                                   | Variabili                                                                                                                                                                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onLoadError` | Il componente esegue questa funzione di callback quando si verifica un errore di caricamento. | - `loadError.error`: Vedi [l’oggetto load error](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#the-load-object)
  - `loadError.elementTagName`: Nome del tag HTML utilizzato per visualizzare il componente nel browser |

#### L’oggetto `error` del caricamento

Ogni volta che si verifica un errore di caricamento, viene inviato un oggetto `error` al gestore degli errori di caricamento con le seguenti proprietà.

| Nome      | Tipo                                                                                                                             | Valore di esempio                 |
| --------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `type`    | Vedi [Tipi di errori di caricamento](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#the-load-object) | `authentication_error`            | Il tipo di errore                 |
| `message` | stringa | indefinito                                                                                                             | `Failed to fetch account session` | Ulteriore descrizione sull’errore |

#### Tipi di errori di caricamento

Quando un componente non riesce a caricarsi, rileviamo il tipo di errore e lo mappiamo su uno dei tipi riportati di seguito. Se non è possibile determinare il tipo di errore di caricamento, viene contrassegnato come `api_error`.

| Tipo                           | Descrizione                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `api_connection_error`         | Mancata connessione all’API Stripe                                                                                        |
| `authentication_error`         | Mancata esecuzione del flusso di autenticazione nei componenti incorporati di Connect                                     |
| `account_session_create_error` | Creazione della sessione dell’account non riuscita                                                                        |
| `invalid_request_error`        | La richiesta non è riuscita con un codice di stato 4xx, in genere causato da problemi di configurazione della piattaforma |
| `rate_limit_error`             | La richiesta non è andata a buon fine perché è stata rilevata una frequenza di richieste anomala                          |
| `render_error`                 | Impossibilità di visualizzare il componente, solitamente causata da estensioni del browser o problemi di rete.            |
| `api_error`                    | Errori API relativi a qualsiasi altro tipo di problema, ad esempio un problema temporaneo con i server di Stripe          |

#### Interfaccia utente per errori di caricamento

Nella maggior parte dei casi, i componenti incorporati mostrano un messaggio di errore quando non riescono a caricarsi, quindi non è necessario farlo manualmente. È possibile utilizzare un gestore di errori di caricamento per l’analisi o per altri elementi del sito che potrebbero essere interessati da un errore di caricamento.

Tuttavia, i componenti incorporati non visualizzano alcun messaggio per gli errori che si verificano prima dell’invocazione del callback [onLoaderStart](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=web#reacting-to-component-display), poiché ciò significa che non hanno visualizzato alcuna interfaccia utente. In tal caso, il codice dovrebbe mostrare l’interfaccia utente di errore.

## Rilevare la visualizzazione dei componenti incorporati

Dopo la creazione di un componente, la visualizzazione dell’interfaccia utente è subordinata al caricamento e all’analisi del codice JavaScript per il componente. Ciò può comportare un ritardo nella percezione dell’elemento da parte dell’utente. Per evitare questa situazione, visualizza la tua interfaccia utente di caricamento prima della creazione del componente e nascondi l’interfaccia utente dopo la visualizzazione del componente. Tutti i componenti incorporati possono accettare una funzione di callback che viene chiamata immediatamente quando qualsiasi interfaccia utente (inclusi gli indicatori di caricamento) viene visualizzata dall’utente.

#### HTML + JS

```html

<span id="spinner"></span>
<div id="balances-container"></div>

```

```js
// Loader start events are emitted by all components. We use Balances as an example here.
const container = document.getElementById('balances-container');
const balances = stripeConnectInstance.create('balances');

balances.setOnLoaderStart((event) => {
  container.getElementById("spinner").style.display = "none";
  console.log(`${event.elementTagName} is visible to users`)
});

container.appendChild(balances);
```

#### HTML + JS

| Metodo             | Descrizione                                                                                                                                             | Variabili                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `setOnLoaderStart` | Il componente esegue questa funzione di callback quando all’utente viene mostrata qualsiasi interfaccia utente (inclusi gli indicatori di caricamento). | - `event.elementTagName`: Nome del tag HTML utilizzato per visualizzare il componente nel browser |

#### React

| React prop      | Descrizione                                                                                                                                             | Variabili                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `onLoaderStart` | Il componente esegue questa funzione di callback quando all’utente viene mostrata qualsiasi interfaccia utente (inclusi gli indicatori di caricamento). | - `event.elementTagName`: Nome del tag HTML utilizzato per visualizzare il componente nel browser |

## Usare Connect.js senza npm

Ti consigliamo di eseguire l’integrazione con i nostri [wrapper di componenti di JavaScript](https://github.com/stripe/connect-js) e [React](https://github.com/stripe/react-connect-js), che semplificano il caricamento dei componenti incorporati di Connect e forniscono definizioni TypeScript per le interfacce supportate. Se il tuo sistema di compilazione attualmente non supporta le dipendenze dai pacchetti, puoi eseguire l’integrazione senza questi pacchetti.

Aggiungi manualmente il tag di script Connect.js al tag `<head>` di ogni pagina del tuo sito.

```html
<!-- Somewhere in your site's <head> -->
<script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
```

Una volta completato il caricamento, Connect.js inizializza la variabile globale `StripeConnect` e chiama `StripeConnect.onLoad`, se definita. È possibile inizializzare Connect.js in modo sicuro configurando una funzione `onload` e chiamando `StripeConnect.init` con le stesse [opzioni di Connect.js](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) utilizzate da `loadConnectAndInitialize`. È possibile utilizzare l’istanza di Connect restituita da `init` allo stesso modo in cui si utilizza l’istanza restituita da `loadConnectAndInitialize` per creare componenti incorporati in un’[integrazione HTML + JS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?client=js&platform=web#load-and-initialize-connectjs).

```javascript
window.StripeConnect = window.StripeConnect || {};
StripeConnect.onLoad = () => {
  const stripeConnectInstance = StripeConnect.init({
      // This is a placeholder - it should be replaced with your publishable API key.
      // Sign in to see your own test API key embedded in code samples.
      // Don't submit any personally identifiable information in requests made with this key.
      publishableKey: "<<YOUR_PUBLISHABLE_KEY>>",
      fetchClientSecret: fetchClientSecret,
    });

  const payments = stripeConnectInstance.create('payments');
  document.body.appendChild(payments);
};
```

## Autenticazione utente nei componenti incorporati di Connect

In genere, i componenti incorporati di Connect non richiedono l’autenticazione dell’utente. In alcuni casi i componenti incorporati di Connect richiedono che l’account connesso acceda con il proprio account Stripe prima di accedere al componente per eseguire le funzionalità necessarie, ad esempio inviare informazioni alla persona giuridica dell’account nel caso del componente di [attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). Altri componenti potrebbero richiedere l’autenticazione all’interno del componente dopo la visualizzazione iniziale.

L’autenticazione è richiesta per gli account connessi in cui Stripe è responsabile della raccolta di informazioni aggiornate quando i requisiti cambiano. Per gli account connessi in cui sei responsabile della raccolta di informazioni aggiornate quando i requisiti lo presuppongono o cambiano, come gli account Custom, l’autenticazione è Stripe è controllata dalla funzione Sessione account [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication). Ti consigliamo di implementare l’autenticazione a due fattori o misure di sicurezza equivalenti come [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). Per le configurazioni degli account che supportano questa funzionalità, come Custom, ti assumi la responsabilità degli account connessi qualora non possano rimborsare i [saldi negativi](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability).

### Componenti che richiedono l’autenticazione

Per l’autenticazione viene visualizzata una finestra a comparsa di proprietà di Stripe. L’account connesso deve essere autenticato prima di poter continuare il proprio flusso di lavoro.

I seguenti componenti richiedono l’autenticazione degli account connessi in determinati scenari:

- [Attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md)
- [Gestione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-management.md)
- [Saldi](https://docs.stripe.com/connect/supported-embedded-components/balances.md)
- [Bonifici](https://docs.stripe.com/connect/supported-embedded-components/payouts.md)
- [Banner di notifica](https://docs.stripe.com/connect/supported-embedded-components/notification-banner.md)
- [Conto finanziario](https://docs.stripe.com/connect/supported-embedded-components/financial-account.md)
- [Elenco di carte Issuing](https://docs.stripe.com/connect/supported-embedded-components/issuing-cards-list.md)

## applica le pratiche ottimali

Per assicurarti che il tempo di caricamento dei componenti incorporati di Connect sia il più basso possibile, segui questi consigli:

- **Chiama `loadConnectAndInitialize` il prima possibile nel flusso**.
- **Creare una singola istanza di connessione**: crea una singola istanza di connessione chiamando `loadConnectAndInitialize` una sola volta per sessione. Quindi riutilizza tale istanza per creare e gestire più componenti. Un errore comune consiste nel creare un’istanza di connessione per ogni componente o più istanze di connessione per ogni sessione. Ciò comporta un consumo aggiuntivo di risorse e richieste API. Se si utilizza React, è possibile utilizzare una libreria di gestione dello stato o un contesto React per gestire questa istanza.
- **Usare l’ultima versione degli SDK appropriati**: utilizza l’ultima versione degli SDK del pacchetto npm [connect-js](https://www.npmjs.com/package/@stripe/connect-js) o [react-connect-js](https://www.npmjs.com/package/@stripe/react-connect-js). Questi SDK avviano i componenti incorporati in modo da ottimizzare le prestazioni. Sono stati aggiunti miglioramenti delle prestazioni agli SDK, quindi ti consigliamo di eseguire l’aggiornamento se usi una vecchia versione.
- **Carica lo script `connect.js` il prima possibile nel flusso**: il primo modo possibile per caricare lo script è includerlo nel campo `head` HTML. Puoi anche utilizzare il comportamento predefinito dei nostri SDK del pacchetto npm, che lo caricano al primo caricamento JavaScript della pagina.

## Configurare StripeConnect [Lato client] [Lato server]

Stripe utilizza un oggetto [AccountSession](https://docs.stripe.com/api/account_sessions.md) per esprimere la tua intenzione di delegare l’accesso API al tuo account connesso.

L’API AccountSessions restituisce una *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) che consente a un componente incorporato di accedere alle risorse di un account connesso come se facessi le chiamate API per suo conto.

### Crea un oggetto AccountSession (Server)

La tua app deve inviare una richiesta al tuo server per ottenere la sessione dell’account. Puoi creare un nuovo endpoint sul tuo server che restituisca la chiave privata client all’app:

#### Ruby

```ruby
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret API key.
# Sign in to see your own test API key embedded in code samples.
# Don’t submit any personally identifiable information in requests made with this key.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: {{CONNECTED_ACCOUNT_ID}},
      components: {
        account_onboarding: {
          enabled: true,
          features: {
            # We recommend disabling authentication for a better user experience when possible
            disable_stripe_user_authentication: true,
          }
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end
```

### Creare l’API Account Session

L’[API Create Account Session](https://docs.stripe.com/api/account_sessions/create.md) determina l’accesso ai componenti e alle funzionalità per i componenti integrati di Connect. Stripe applica questi parametri a tutti i componenti che corrispondono alla sessione dell’account. Se il tuo sito supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione dell’account corrispondano al ruolo dell’utente corrente. Se la tua app supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione account corrispondano al ruolo dell’utente corrente. Ad esempio, puoi abilitare la [gestione dei rimborsi](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-payments-features-refund_management) solo per gli amministratori del tuo sito, ma non per gli altri utenti. Per assicurarti che l’accesso ai ruoli utente sia applicato, devi mappare il ruolo utente del tuo sito ai componenti della sessione dell’account.

### Installa l’SDK di StripeConnect (Client)

L’[SDK per iOS di Stripe](https://github.com/stripe/stripe-ios) è open source, [completamente documentato](https://stripe.dev/stripe-ios/index.html) e compatibile con le app che supportano iOS 15 o versioni successive.

#### Swift Package Manager

Per installare l’SDK, segui questi passaggi:

1. In Xcode, seleziona **File** > **Aggiungi dipendenze pacchetto…** e inserisci `https://github.com/stripe/stripe-ios-spm` come URL repository.
1. Seleziona il numero dell’ultima versione dalla nostra [pagina delle release](https://github.com/stripe/stripe-ios/releases).
1. Aggiungi il prodotto **StripeConnect** al [target della tua app](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### CocoaPods

1. Se non l’hai ancora fatto, installa la versione più recente di [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).
1. Se non hai un [Podfile](https://guides.cocoapods.org/syntax/podfile.html), esegui il seguente comando per crearne uno:
   ```bash
   pod init
   ```
1. Aggiungi questa riga al tuo `Podfile`:
   ```podfile
   pod 'StripeConnect'
   ```
1. Esegui il seguente comando:
   ```bash
   pod install
   ```
1. Ricordati di utilizzare d’ora in poi il file `.xcworkspace` per aprire il progetto in Xcode, anziché il file `.xcodeproj` file.
1. In futuro, per eseguire l’aggiornamento alla versione più recente dell’SDK, esegui questo comando:
   ```bash
   pod update StripeConnect
   ```

#### Carthage

1. Se non l’hai ancora fatto, installa la versione più recente di [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
1. Aggiungi questa riga al tuo `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. Segui le [istruzioni per l’installazione di Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Assicurati di integrare tutti i framework necessari elencati [qui](https://github.com/stripe/stripe-ios/tree/master/StripeConnect#manual-linking).
1. In futuro, per eseguire l’aggiornamento alla versione più recente del nostro SDK, esegui il seguente comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Framework manuale

1. Vai alla [pagina delle versioni di GitHub](https://github.com/stripe/stripe-ios/releases/latest) e scarica e decomprimi **Stripe.xcframework.zip**.
1. Trascina **StripeConnect.xcframework** nella sezione **Embedded Binaries** (File binari incorporati) delle impostazioni **General** (Generali) nel tuo progetto Xcode. Assicurati che sia selezionato **Copy items if needed** (Copia elementi se necessario).
1. Ripeti il passaggio 2 per tutti i framework necessari elencati [qui](https://github.com/stripe/stripe-ios/tree/master/StripeConnect#manual-linking).
1. In futuro, per eseguire l’aggiornamento alla versione più recente del nostro SDK, ripeti i passaggi 1-3.

> Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Versioni](https://github.com/stripe/stripe-ios/releases) su GitHub. Per ricevere notifiche quando viene pubblicata una nuova versione, [guarda le versioni](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) del repository.

### Configura l’autorizzazione per la fotocamera (lato client)

L’SDK iOS di Stripe Connect richiede l’accesso alla fotocamera del dispositivo per acquisire i documenti di identità. Per fare in modo che la tua app richieda le autorizzazioni per la fotocamera:

1. Apri il file **Info.plist** del tuo progetto in Xcode.
1. Aggiungi la chiave `NSCameraUsageDescription`.
1. Aggiungi un valore stringa che spieghi agli utenti perché la tua app richiede le autorizzazioni per la fotocamera, ad esempio:

> Questa app utilizza la fotocamera per scattare una foto dei tuoi documenti di identità.

Consulta la [documentazione di Apple](https://developer.apple.com/documentation/avfoundation/cameras_and_media_capture/requesting_authorization_for_media_capture_on_ios) per ulteriori informazioni su come richiedere l’autorizzazione per la fotocamera.

### Inizializza EmbeddedComponentManager (Client)

Imposta la tua chiave pubblicabile utilizzando `StripeAPI.shared` e istanzia un [EmbeddedComponentManager](https://stripe.dev/stripe-ios/stripeconnect/documentation/stripeconnect/embeddedcomponentmanager) con una chiusura che recupera una chiave privata client chiamando il nuovo endpoint che hai creato sul tuo server. Per creare un componente, chiama il metodo di creazione appropriato su `EmbeddedComponentManager` che hai istanziato sopra.

L’[attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) restituisce un controller che gestisce la propria presentazione. Altri componenti, come [Payments](https://docs.stripe.com/connect/supported-embedded-components/payments.md), restituiscono un [UIViewController](https://developer.apple.com/documentation/uikit/uiviewcontroller) che è possibile visualizzare nella propria app con maggiore flessibilità.

#### UIKit

```swift
import StripeConnect
import UIKit

class MyViewController: UIViewController {
    let errorView: UIView

    func fetchClientSecret() async -> String? {
        let url = URL(string: "https://{{YOUR_SERVER}}/account_session")!

        var request = URLRequest(url: url)
        request.httpMethod = "POST"

        do {
            // Fetch the AccountSession client secret
            let (data, _) = try await URLSession.shared.data(for: request)
            let json = try JSONSerialization.jsonObject(with: data) as? [String : Any]

            errorView.isHidden = true

            return json?["client_secret"] as? String
        } catch let error {
            // Handle errors on the client side here
            print("An error occurred: \(error)")
            errorView.isHidden = false
            return nil
        }
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        // This is your test publishable API key.
        STPAPIClient.shared.publishableKey =  "{{PUBLISHABLE_KEY}}",
        let embeddedComponentManager = EmbeddedComponentManager(
            fetchClientSecret: fetchClientSecret
        )

        // Account onboarding presents modally and fullscreen
        let controller = embeddedComponentManager.createAccountOnboardingController()
        controller.title = "Onboard with Stripe"
        controller.present(from: self)

        // All other components can be flexibly presented
        let paymentsViewController = embeddedComponentManager.createPaymentsViewController()
        present(paymentsViewController)
    }
}
```

## Configure the Embedded Component Manager [Lato client]

[Consulta la documentazione di riferimento :external:](https://stripe.dev/stripe-ios/stripeconnect/documentation/stripeconnect/embeddedcomponentmanager/init\(apiClient:appearance:fonts:fetchClientSecret:\)).

### Personalizzare l’aspetto dei componenti incorporati di Connect

Il [toolkit Figma di componenti incorporati per personalizzare l’interfaccia utente](https://www.figma.com/community/file/1438614134095442934) contiene tutti i componenti, i pattern comuni e un’applicazione esemplificativa. Puoi utilizzarlo per visualizzare e progettare interfacce utente incorporate sul tuo sito web.

Offriamo una [serie di opzioni](https://docs.stripe.com/connect/embedded-appearance-options.md) per personalizzare l’aspetto dei componenti incorporati di Connect. Queste personalizzazioni influiscono su pulsanti, icone e altri elementi del nostro sistema di progettazione.

> #### Finestre popup necessarie
> 
> Alcuni comportamenti nei componenti incorporati, come l’[autenticazione utente](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components), devono essere presentati in una vista web autenticata. Non puoi personalizzare il componente incorporato per eliminare tali WebView.

Puoi impostare queste opzioni usando [EmbeddedComponentManager.Appearance](https://stripe.dev/stripe-ios/stripeconnect/documentation/stripeconnect/embeddedcomponentmanager/appearance) quando inizializzi `EmbeddedComponentManager`.

```swift
func fetchClientSecret() async -> String? {
    let url = URL(string: "https://{{YOUR_SERVER}}/account_session")!

    var request = URLRequest(url: url)
    request.httpMethod = "POST"

    do {
        let (data, _) = try await URLSession.shared.data(for: request)
        let json = try JSONSerialization.jsonObject(with: data) as? [String : Any]

        return json?["client_secret"] as? String
    } catch {
        return nil
    }
}

// Specify custom fonts
var customFonts: [CustomFontSource] = []
let myFont = UIFont(name: "My Font", size: 16)!
let fontUrl = Bundle.main.url(forResource: "my-font-2", withExtension: "woff")!
do {
    let customFontSource = try CustomFontSource(font: myFont, fileUrl: fontUrl)
    customFonts.append(customFontSource)
} catch {
    print("Error loading custom font: \(error)")
}

// Customize appearance
var appearance = EmbeddedComponentManager.Appearance()
appearance.typography.font.base = myFont
appearance.typography.fontSizeBase = 16 // Unscaled font size
appearance.colors.primary = UIColor { traitCollection in
    if traitCollection.userInterfaceStyle == .dark {
        return UIColor(red: 0.455, green: 0.424, blue: 1.000, alpha: 1.0)
    } else {
        return UIColor(red: 0.404, green: 0.365, blue: 1.000, alpha: 1.0)
    }
}

STPAPIClient.shared.publishableKey =  "{{PUBLISHABLE_KEY}}",
let embeddedComponentManager = EmbeddedComponentManager(
    appearance: appearance,
    fonts: customFonts,
    fetchClientSecret: fetchClientSecret
)
```

I colori dell’aspetto che utilizzano [provider dinamici](https://developer.apple.com/documentation/uikit/uicolor/3238041-init) vengono applicati automaticamente al componente incorporato di Connect quando la relativa [UITraitCollection](https://developer.apple.com/documentation/uikit/uitraitcollection) viene aggiornata, incluse la [modalità scura](https://developer.apple.com/design/human-interface-guidelines/dark-mode) e il [contrasto per l’accessibilità](https://developer.apple.com/documentation/uikit/uiaccessibilitycontrast). L’aspetto predefinito non include i colori della modalità scura, quindi devi specificare un aspetto con colori dinamici in `EmbeddedComponentManager` per supportare la modalità scura nella tua app.

Quando specifichi le dimensioni dei caratteri, usa la dimensione dei caratteri non ridimensionata visualizzata per la classe di dimensioni predefinita del dispositivo. Il componente incorporato ridimensiona automaticamente la dimensione del carattere in base alla relativa [UITraitCollection](https://developer.apple.com/documentation/uikit/uitraitcollection).

 Vedere [l’elenco completo delle opzioni di aspetto](https://docs.stripe.com/connect/embedded-appearance-options.md) su iOS.

### Usa font personalizzati

Se nell’app vengono utilizzati font personalizzati (ad esempio, da file `.otf` o `.tff` incorporati nel binario dell’app), è necessario specificare i file dei font in un [CustomFontSource](https://stripe.dev/stripe-ios/stripeconnect/documentation/stripeconnect/embeddedcomponentmanager/customfontsource) passato all’argomento `fonts` durante l’inizializzazione di `EmbeddedComponentManager`. Ciò consente ai componenti incorporati di Connect di accedere ai file dei font per renderizzarli correttamente.

I caratteri specificati in `appearance` devono utilizzare un [carattere di sistema supportato](https://developer.apple.com/fonts/system-fonts/) o un [CustomFontSource](https://stripe.dev/stripe-ios/stripeconnect/documentation/stripeconnect/embeddedcomponentmanager/customfontsource) passato a `EmbeddedComponentManager` durante l’inizializzazione per essere visualizzati correttamente.

[Consulta la documentazione di riferimento :external:](https://stripe.dev/stripe-ios/stripeconnect/documentation/stripeconnect/embeddedcomponentmanager/customfontsource).

### Aggiornare i componenti incorporati di Connect dopo l’inizializzazione

Chiama il metodo `update` per modificare l’aspetto dei componenti incorporati dopo l’inizializzazione:

```swift
var appearance = EmbeddedComponentManager.Appearance()
appearance.colors.primary = UIColor.red

manager.update(appearance: appearance)
```

## Autenticazione

Offriamo una serie di API per gestire le sessioni degli account e le credenziali degli utenti nei componenti incorporati di Connect.

### Aggiornare la chiave privata client

Nelle sessioni di lunga durata, la sessione della *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) fornita inizialmente potrebbe scadere. Quando scade, utilizziamo automaticamente `fetchClientSecret` per recuperare una nuova chiave privata client e aggiornare la sessione. Non devi specificare alcun parametro aggiuntivo.

```swift
func fetchClientSecret() async -> String? {
    var request = URLRequest(url: URL(string: "https://{{YOUR_SERVER}}/account_session")!)
    request.httpMethod = "POST"

    do {
        let (data, _) = try await URLSession.shared.data(for: request)
        let json = try JSONSerialization.jsonObject(with: data) as? [String : Any]
        return json?["client_secret"] as? String
    } catch let error {
        return nil
    }
}

STPAPIClient.shared.publishableKey =  "{{PUBLISHABLE_KEY}}",
let embeddedComponentManager = EmbeddedComponentManager(
    fetchClientSecret: fetchClientSecret
)
```

## Localizzazione

I componenti incorporati di Connect supportano le seguenti lingue:

| Lingua                            | Codice lingua |
| --------------------------------- | ------------- |
| Bulgaro (Bulgaria)                | `bg-BG`       |
| Cinese (semplificato)             | `zh-Hans`     |
| Cinese (tradizionale - Hong Kong) | `zh-Hant-HK`  |
| Cinese (tradizionale - Taiwan)    | `zh-Hant-TW`  |
| Croato (Croazia)                  | `hr-HR`       |
| Ceco (Cechia)                     | `cs-CZ`       |
| Danese (Danimarca)                | `da-DK`       |
| Olandese (Paesi Bassi)            | `nl-NL`       |
| Inglese (Australia)               | `en-AU`       |
| Inglese (India)                   | `en-IN`       |
| Inglese (Irlanda)                 | `en-IE`       |
| Inglese (Nuova Zelanda)           | `en-NZ`       |
| Inglese (Singapore)               | `en-SG`       |
| Inglese (Regno Unito)             | `en-GB`       |
| Inglese (Stati Uniti)             | `en-US`       |
| Estone (Estonia)                  | `et-EE`       |
| Filippino (Filippine)             | `fil-PH`      |
| Finlandese (Finlandia)            | `fi-FI`       |
| Francese (Canada)                 | `fr-CA`       |
| Francese (Francia)                | `fr-FR`       |
| Tedesco (Germania)                | `de-DE`       |
| Greco (Grecia)                    | `el-GR`       |
| Ungherese (Ungheria)              | `hu-HU`       |
| Indonesiano (Indonesia)           | `id-ID`       |
| Italiano (Italia)                 | `it-IT`       |
| Giapponese (Giappone)             | `ja-JP`       |
| Coreano (Corea del Sud)           | `ko-KR`       |
| Lettone (Lettonia)                | `lv-LV`       |
| Lituano (Lituania)                | `lt-LT`       |
| Malese (Malaysia)                 | `ms-MY`       |
| Maltese (Malta)                   | `mt-MT`       |
| Norvegese bokmål (Norvegia)       | `nb-NO`       |
| Polacco (Polonia)                 | `pl-PL`       |
| Portoghese (Brasile)              | `pt-BR`       |
| Portoghese (Portogallo)           | `pt-PT`       |
| Rumeno (Romania)                  | `ro-RO`       |
| Slovacco (Slovacchia)             | `sk-SK`       |
| Sloveno (Slovenia)                | `sl-SI`       |
| Spagnolo (Argentina)              | `es-AR`       |
| Spagnolo (Brasile)                | `es-BR`       |
| Spagnolo (America Latina)         | `es-419`      |
| Spagnolo (Messico)                | `es-MX`       |
| Spagnolo (Spagna)                 | `es-ES`       |
| Svedese (Svezia)                  | `sv-SE`       |
| Tailandese (Thailandia)           | `th-TH`       |
| Turco (Turchia)                   | `tr-TR`       |
| Vietnamita (Vietnam)              | `vi-VN`       |

## Autenticazione utente nei componenti incorporati di Connect

In genere, i componenti incorporati di Connect non richiedono l’autenticazione dell’utente. In alcuni casi i componenti incorporati di Connect richiedono che l’account connesso acceda con il proprio account Stripe prima di accedere al componente per eseguire le funzionalità necessarie, ad esempio inviare informazioni alla persona giuridica dell’account nel caso del componente di [attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). Altri componenti potrebbero richiedere l’autenticazione all’interno del componente dopo la visualizzazione iniziale.

L’autenticazione è richiesta per gli account connessi in cui Stripe è responsabile della raccolta di informazioni aggiornate quando i requisiti cambiano. Per gli account connessi in cui sei responsabile della raccolta di informazioni aggiornate quando i requisiti lo presuppongono o cambiano, come gli account Custom, l’autenticazione è Stripe è controllata dalla funzione Sessione account [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication). Ti consigliamo di implementare l’autenticazione a due fattori o misure di sicurezza equivalenti come [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). Per le configurazioni degli account che supportano questa funzionalità, come Custom, ti assumi la responsabilità degli account connessi qualora non possano rimborsare i [saldi negativi](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability).

### Componenti che richiedono l’autenticazione

Agli account connessi verrà mostrata una [WebView](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) autenticata nella tua applicazione. L’account connesso deve essere autenticato prima di poter continuare il proprio flusso di lavoro nella WebView.

Il flusso di autenticazione in hosting su Stripe mostra il nome, il colore e l’icona del tuo brand così come sono stati impostati nelle [impostazioni di Connect](https://dashboard.stripe.com/account/applications/settings) e non utilizza l’aspetto e i caratteri personalizzati di [Gestione componenti incorporati](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) fino al completamento dell’autenticazione.

Il seguente componente richiede l’autenticazione degli account connessi in determinati scenari:

- [Attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md)
- [Bonifici](https://docs.stripe.com/connect/supported-embedded-components/payouts.md)

## Gestire gli errori di caricamento [Lato client]

Rispondi agli errori di caricamento dei componenti implementando il metodo del listener `onLoadError` del componente.

Cause di errore diverse potrebbero chiamare il metodo `onLoadError` più volte, quindi qualsiasi logica attivata da `onLoadError` deve essere idempotente.

#### Swift

```swift
// All components emit load errors. This example uses AccountOnboarding.
// All components support didFailLoadWithError.
class MyViewController: UIViewController, AccountOnboardingControllerDelegate {
    func openAccountOnboarding() {
        let accountOnboardingController = embeddedComponentManager.createAccountOnboardingController();
        accountOnboardingController.delegate = self
        accountOnboardingController.present(from: self)
    }

    // MARK: - AccountOnboardingControllerDelegate
    func accountOnboarding(_ accountOnboarding: AccountOnboardingController, didFailLoadWithError error: Error) {
        print("Account onboarding failed to load with error '\(error)'")
    }
}
```

## Configurare StripeConnect [Lato client] [Lato server]

Stripe utilizza un oggetto [AccountSession](https://docs.stripe.com/api/account_sessions.md) per esprimere la tua intenzione di delegare l’accesso API al tuo account connesso.

L’API AccountSessions restituisce una *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) che consente a un componente incorporato di accedere alle risorse di un account connesso come se facessi le chiamate API per suo conto.

### Crea un oggetto AccountSession (Server)

La tua app deve inviare una richiesta al tuo server per ottenere la sessione dell’account. Puoi creare un nuovo endpoint sul tuo server che restituisca la chiave privata client all’app:

#### Ruby

```ruby
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret API key.
# Sign in to see your own test API key embedded in code samples.
# Don’t submit any personally identifiable information in requests made with this key.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: {{CONNECTED_ACCOUNT_ID}},
      components: {
        account_onboarding: {
          enabled: true,
          features: {
            # We recommend disabling authentication for a better user experience when possible
            disable_stripe_user_authentication: true,
          }
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end
```

### Creare l’API Account Session

L’[API Create Account Session](https://docs.stripe.com/api/account_sessions/create.md) determina l’accesso ai componenti e alle funzionalità per i componenti integrati di Connect. Stripe applica questi parametri a tutti i componenti che corrispondono alla sessione dell’account. Se il tuo sito supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione dell’account corrispondano al ruolo dell’utente corrente. Se la tua app supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione account corrispondano al ruolo dell’utente corrente. Ad esempio, puoi abilitare la [gestione dei rimborsi](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-payments-features-refund_management) solo per gli amministratori del tuo sito, ma non per gli altri utenti. Per assicurarti che l’accesso ai ruoli utente sia applicato, devi mappare il ruolo utente del tuo sito ai componenti della sessione dell’account.

### Installa l’SDK di StripeConnect (Client)

L’[SDK per Android di Stripe](https://github.com/stripe/stripe-android) è open source e [completamente documentato](https://stripe.dev/stripe-android/).

Per installare l’SDK, aggiungi `connect` al blocco `dependencies` del tuo file [app/build.gradle](https://developer.android.com/studio/build/dependencies):

#### Kotlin

```kotlin
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Connect Android SDK
  implementation("com.stripe:connect:23.2.0")
}
```

> Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Releases](https://github.com/stripe/stripe-android/releases) su GitHub. Per ricevere una notifica quando viene pubblicata una nuova versione, [imposta il controllo delle versioni per il repository](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).

### Inizializza EmbeddedComponentManager (Client)

Crea un’istanza di [EmbeddedComponentManager](https://stripe.dev/stripe-android/connect/com.stripe.android.connect/-embedded-component-manager/index.html) con la tua chiave pubblicabile e un lambda che recupera una chiave privata client chiamando il nuovo endpoint creato sul server. Per gestire le modifiche alla configurazione, mantieni l’istanza `EmbeddedComponentManager` in un `ViewModel` di attività o frammento.

#### Kotlin

```kotlin
class MyActivityViewModel : ViewModel() {
    val embeddedComponentManager: EmbeddedComponentManager =
        EmbeddedComponentManager(
            // This is a placeholder - it should be replaced with your publishable API key.
            // Sign in to see your own test API key embedded in code samples.
            // Don't submit any personally identifiable information in requests made with this key.
            publishableKey = "<<YOUR_PUBLISHABLE_KEY>>",
            fetchClientSecret = ::fetchClientSecret,
        )

    private suspend fun fetchClientSecret(): String? =
        try {
            // Fetch the AccountSession client secret
            Fuel.post("https://{{YOUR_SERVER_BASE_URL}}/account_session")
                .awaitString()
                .let { JSONObject(it).getString("client_secret") }
        } catch (error: CancellationException) {
            throw error
        } catch (error: Exception) {
            // Handle errors on the client side here
            println("Error fetching client secret: ${error.message}")
            null
        }
}
```

Per creare un componente, chiama prima `EmbeddedComponentManager.onActivityCreate()` nel metodo `onCreate` della tua attività. Quindi, chiama il metodo di creazione appropriato su `EmbeddedComponentManager` che hai istanziato sopra.

L’[attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md) restituisce un controller che gestisce la propria presentazione. Altri componenti, come [Payments](https://docs.stripe.com/connect/supported-embedded-components/payments.md), restituiscono una [Vista](https://developer.android.com/reference/android/view/View) che è possibile visualizzare nell’app con maggiore flessibilità.

#### Rendering di un controller

#### Kotlin

```kotlin
class MyActivity : FragmentActivity() {
    private val viewModel: MyActivityViewModel by viewModels()
    private lateinit var accountOnboardingController: AccountOnboardingController

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        EmbeddedComponentManager.onActivityCreate(this)
        setContentView(R.layout.my_activity)

        accountOnboardingController =
            viewModel.embeddedComponentManager.createAccountOnboardingController(this)
    }

    private fun openAccountOnboarding() {
        accountOnboardingController.show()
    }
}
```

#### Rendering di un `View`

#### Kotlin

```kotlin
class MyActivity : FragmentActivity() {
    private val viewModel: MyActivityViewModel by viewModels()
    private lateinit var paymentsView: View

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        EmbeddedComponentManager.onActivityCreate(this)
        setContentView(R.layout.my_activity)

        paymentsView = viewModel.embeddedComponentManager.createPaymentsView(this)

        // Add the view to your layout
        val container = findViewById<ViewGroup>(R.id.payments_container)
        container.addView(paymentsView)
    }
}
```

## Configure the Embedded Component Manager [Lato client]

[Consulta la documentazione di riferimento :external:](https://stripe.dev/stripe-android/connect/com.stripe.android.connect/-embedded-component-manager/index.html).

### Personalizzare l’aspetto dei componenti incorporati di Connect

Il [toolkit Figma di componenti incorporati per personalizzare l’interfaccia utente](https://www.figma.com/community/file/1438614134095442934) contiene tutti i componenti, i pattern comuni e un’applicazione esemplificativa. Puoi utilizzarlo per visualizzare e progettare interfacce utente incorporate sul tuo sito web.

Offriamo una [serie di opzioni](https://docs.stripe.com/connect/embedded-appearance-options.md) per personalizzare l’aspetto dei componenti incorporati di Connect. Queste personalizzazioni influiscono su pulsanti, icone e altri elementi del nostro sistema di progettazione.

> #### Finestre popup necessarie
> 
> Alcuni comportamenti nei componenti incorporati, come l’[autenticazione utente](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components), devono essere presentati in una vista web autenticata. Non puoi personalizzare il componente incorporato per eliminare tali WebView.

È possibile impostare queste opzioni utilizzando [Appearance](https://stripe.dev/stripe-android/connect/com.stripe.android.connect.appearance/-appearance/index.html) durante l’inizializzazione di `EmbeddedComponentManager`.

#### Kotlin

```kotlin
// Specify custom fonts
val customFonts = listOf(
    CustomFontSource(
        // Font file located in `assets/` folder
        assetsFilePath = "fonts/myCustomFont.ttf",
        name = "myCustomFont",
        weight = 1000,
    )
)

// Customize appearance
val appearance = Appearance.Builder()
    .typography(
        Typography.Builder()
            .fontFamily("myCustomFont") // Same name as the custom font above
            .fontSizeBase(16f) // Unscaled font size
            .build()
    )
    .colors(
        Colors.Builder()
            .primary(Color.RED)
            .build()
    )
    .build()

val embeddedComponentManager = EmbeddedComponentManager(
    publishableKey = "<<YOUR_PUBLISHABLE_KEY>>",
    fetchClientSecret = ::fetchClientSecret,
    appearance = appearance,
    customFonts = customFonts,
)
```

Quando specifichi le dimensioni dei caratteri, usa la dimensione dei caratteri non ridimensionata visualizzata per la classe di dimensioni predefinita del dispositivo. Il componente incorporato ridimensiona automaticamente la dimensione del carattere in base alle [impostazioni del carattere per l’accessibilità](https://support.google.com/accessibility/android/answer/11183305?sjid=3094445894544346025-NA#fontsize) dell’utente.

 Consulta l’[elenco completo delle opzioni di aspetto](https://docs.stripe.com/connect/embedded-appearance-options.md?platform=android) su Android.

### Usa font personalizzati

Se usi caratteri personalizzati nell’app (ad esempio, da file `.otf` o `.tff` incorporati nel file binario dell’app), devi specificare i file dei caratteri in un [CustomFontSource](https://stripe.dev/stripe-android/connect/com.stripe.android.connect.appearance.fonts/-custom-font-source/index.html) specificato nell’argomento `customFonts` durante l’inizializzazione di `EmbeddedComponentManager`. In questo modo, i componenti incorporati di Connect possono accedere ai file dei caratteri per visualizzarli correttamente.

Per una visualizzazione corretta, i caratteri indicati in `appearance` devono utilizzare un [CustomFontSource](https://stripe.dev/stripe-android/connect/com.stripe.android.connect.appearance.fonts/-custom-font-source/index.html) specificato in `EmbeddedComponentManager` al momento dell’inizializzazione.

[Consulta la documentazione di riferimento :external:](https://stripe.dev/stripe-android/connect/com.stripe.android.connect.appearance.fonts/-custom-font-source/index.html).

### Aggiornare i componenti incorporati di Connect dopo l’inizializzazione

Chiama il metodo `update` per modificare l’aspetto dei componenti incorporati dopo l’inizializzazione:

#### Kotlin

```kotlin
val appearance = Appearance.Builder()
    .colors(
        Colors.Builder()
            .primary(ContextCompat.getColor(context, R.color.primary))
            .build()
    )
    .build()
embeddedComponentManager.update(appearance = appearance)
```

## Autenticazione

Offriamo una serie di API per gestire le sessioni degli account e le credenziali degli utenti nei componenti incorporati di Connect.

### Aggiornare la chiave privata client

Nelle sessioni di lunga durata, la sessione della *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) fornita inizialmente potrebbe scadere. Quando scade, utilizziamo automaticamente `fetchClientSecret` per recuperare una nuova chiave privata client e aggiornare la sessione. Non devi specificare alcun parametro aggiuntivo.

#### Kotlin

```kotlin
val embeddedComponentManager: EmbeddedComponentManager =
    EmbeddedComponentManager(
        publishableKey = "<<YOUR_PUBLISHABLE_KEY>>",
        fetchClientSecret = ::fetchClientSecret,
    )

private suspend fun fetchClientSecret(): String? =
    try {
        Fuel.post("https://{{YOUR_SERVER_BASE_URL}}/account_session")
            .awaitString()
            .let { JSONObject(it).getString("client_secret") }
    } catch (error: CancellationException) {
        throw error
    } catch (error: Exception) {
        null
    }
```

## Localizzazione

I componenti incorporati di Connect supportano le seguenti lingue:

| Lingua                            | Codice lingua |
| --------------------------------- | ------------- |
| Bulgaro (Bulgaria)                | `bg-BG`       |
| Cinese (semplificato)             | `zh-Hans`     |
| Cinese (tradizionale - Hong Kong) | `zh-Hant-HK`  |
| Cinese (tradizionale - Taiwan)    | `zh-Hant-TW`  |
| Croato (Croazia)                  | `hr-HR`       |
| Ceco (Cechia)                     | `cs-CZ`       |
| Danese (Danimarca)                | `da-DK`       |
| Olandese (Paesi Bassi)            | `nl-NL`       |
| Inglese (Australia)               | `en-AU`       |
| Inglese (India)                   | `en-IN`       |
| Inglese (Irlanda)                 | `en-IE`       |
| Inglese (Nuova Zelanda)           | `en-NZ`       |
| Inglese (Singapore)               | `en-SG`       |
| Inglese (Regno Unito)             | `en-GB`       |
| Inglese (Stati Uniti)             | `en-US`       |
| Estone (Estonia)                  | `et-EE`       |
| Filippino (Filippine)             | `fil-PH`      |
| Finlandese (Finlandia)            | `fi-FI`       |
| Francese (Canada)                 | `fr-CA`       |
| Francese (Francia)                | `fr-FR`       |
| Tedesco (Germania)                | `de-DE`       |
| Greco (Grecia)                    | `el-GR`       |
| Ungherese (Ungheria)              | `hu-HU`       |
| Indonesiano (Indonesia)           | `id-ID`       |
| Italiano (Italia)                 | `it-IT`       |
| Giapponese (Giappone)             | `ja-JP`       |
| Coreano (Corea del Sud)           | `ko-KR`       |
| Lettone (Lettonia)                | `lv-LV`       |
| Lituano (Lituania)                | `lt-LT`       |
| Malese (Malaysia)                 | `ms-MY`       |
| Maltese (Malta)                   | `mt-MT`       |
| Norvegese bokmål (Norvegia)       | `nb-NO`       |
| Polacco (Polonia)                 | `pl-PL`       |
| Portoghese (Brasile)              | `pt-BR`       |
| Portoghese (Portogallo)           | `pt-PT`       |
| Rumeno (Romania)                  | `ro-RO`       |
| Slovacco (Slovacchia)             | `sk-SK`       |
| Sloveno (Slovenia)                | `sl-SI`       |
| Spagnolo (Argentina)              | `es-AR`       |
| Spagnolo (Brasile)                | `es-BR`       |
| Spagnolo (America Latina)         | `es-419`      |
| Spagnolo (Messico)                | `es-MX`       |
| Spagnolo (Spagna)                 | `es-ES`       |
| Svedese (Svezia)                  | `sv-SE`       |
| Tailandese (Thailandia)           | `th-TH`       |
| Turco (Turchia)                   | `tr-TR`       |
| Vietnamita (Vietnam)              | `vi-VN`       |

## Autenticazione utente nei componenti incorporati di Connect

In genere, i componenti incorporati di Connect non richiedono l’autenticazione dell’utente. In alcuni casi i componenti incorporati di Connect richiedono che l’account connesso acceda con il proprio account Stripe prima di accedere al componente per eseguire le funzionalità necessarie, ad esempio inviare informazioni alla persona giuridica dell’account nel caso del componente di [attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). Altri componenti potrebbero richiedere l’autenticazione all’interno del componente dopo la visualizzazione iniziale.

L’autenticazione è richiesta per gli account connessi in cui Stripe è responsabile della raccolta di informazioni aggiornate quando i requisiti cambiano. Per gli account connessi in cui sei responsabile della raccolta di informazioni aggiornate quando i requisiti lo presuppongono o cambiano, come gli account Custom, l’autenticazione è Stripe è controllata dalla funzione Sessione account [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication). Ti consigliamo di implementare l’autenticazione a due fattori o misure di sicurezza equivalenti come [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). Per le configurazioni degli account che supportano questa funzionalità, come Custom, ti assumi la responsabilità degli account connessi qualora non possano rimborsare i [saldi negativi](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability).

### Componenti che richiedono l’autenticazione

Agli account connessi verrà mostrata una [WebView](https://developer.chrome.com/docs/android/custom-tabs) autenticata nella tua applicazione. L’account connesso deve essere autenticato prima di poter continuare il proprio flusso di lavoro nella WebView.

Il flusso di autenticazione in hosting su Stripe mostra il nome, il colore e l’icona del tuo brand così come sono stati impostati nelle [impostazioni di Connect](https://dashboard.stripe.com/account/applications/settings) e non utilizza l’aspetto e i caratteri personalizzati di [Gestione componenti incorporati](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) fino al completamento dell’autenticazione.

> #### Limitazioni di Android
> 
> A causa di una limitazione delle API Android, i componenti incorporati non possono utilizzare caratteri personalizzati nella WebView autenticata, anche dopo il completamento dell’autenticazione.

Il seguente componente richiede l’autenticazione degli account connessi in determinati scenari:

- [Attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md)
- [Bonifici](https://docs.stripe.com/connect/supported-embedded-components/payouts.md)

## Gestire gli errori di caricamento [Lato client]

Rispondi agli errori di caricamento dei componenti implementando il metodo del listener `onLoadError` del componente.

Cause di errore diverse potrebbero chiamare il metodo `onLoadError` più volte, quindi qualsiasi logica attivata da `onLoadError` deve essere idempotente.

#### Kotlin

```kotlin
// All components emit load errors. This example uses AccountOnboarding.
// All components support onLoadError.
class MyActivity : FragmentActivity() {
    private lateinit var accountOnboardingController: AccountOnboardingController

    override fun onCreate(savedInstanceState: Bundle?) {
        accountOnboardingController =
            embeddedComponentManager.createAccountOnboardingController(this)
        accountOnboardingController.listener = MyAccountOnboardingListener()
    }

    private fun openAccountOnboarding() {
        accountOnboardingController.show()
    }

    private inner class MyAccountOnboardingListener : AccountOnboardingListener {
        override fun onLoadError(error: Throwable) {
            println("Error loading account onboarding: ${error.message}")
        }
    }
}
```

## Configurare StripeConnect [Lato client] [Lato server]

Stripe utilizza un oggetto [AccountSession](https://docs.stripe.com/api/account_sessions.md) per esprimere la tua intenzione di delegare l’accesso API al tuo account connesso.

L’API AccountSessions restituisce una *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) che consente a un componente incorporato di accedere alle risorse di un account connesso come se facessi le chiamate API per suo conto.

### Crea un oggetto AccountSession (Server)

La tua app deve inviare una richiesta al tuo server per ottenere la sessione dell’account. Puoi creare un nuovo endpoint sul tuo server che restituisca la chiave privata client all’app:

#### Ruby

```ruby
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret API key.
# Sign in to see your own test API key embedded in code samples.
# Don’t submit any personally identifiable information in requests made with this key.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: {{CONNECTED_ACCOUNT_ID}},
      components: {
        account_onboarding: {
          enabled: true,
          features: {
            # We recommend disabling authentication for a better user experience when possible
            disable_stripe_user_authentication: true,
          }
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end
```

### Creare l’API Account Session

L’[API Create Account Session](https://docs.stripe.com/api/account_sessions/create.md) determina l’accesso ai componenti e alle funzionalità per i componenti integrati di Connect. Stripe applica questi parametri a tutti i componenti che corrispondono alla sessione dell’account. Se il tuo sito supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione dell’account corrispondano al ruolo dell’utente corrente. Se la tua app supporta più ruoli utente, assicurati che i componenti e le funzioni abilitati per quella sessione account corrispondano al ruolo dell’utente corrente. Ad esempio, puoi abilitare la [gestione dei rimborsi](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-payments-features-refund_management) solo per gli amministratori del tuo sito, ma non per gli altri utenti. Per assicurarti che l’accesso ai ruoli utente sia applicato, devi mappare il ruolo utente del tuo sito ai componenti della sessione dell’account.

### Installa l’SDK Stripe React Native (Client)

Installa l’SDK Stripe React Native utilizzando npm o yarn:

```bash
npm install @stripe/stripe-react-native react-native-webview
# or
yarn add @stripe/stripe-react-native react-native-webview
```

### Inizializza StripeConnectProvider (Client)

Includi la tua richiesta di registrazione con `ConnectComponentsProvider` e fornisci la tua chiave pubblicabile insieme a una funzione che recupera una chiave privata client chiamando il nuovo endpoint che hai creato sul tuo server.

```javascript
import { useState } from 'react';
import { ConnectComponentsProvider } from '@stripe/stripe-react-native';

const fetchClientSecret = async (): Promise<string> => {
  const response = await fetch('https://{{YOUR_SERVER}}/account_session', {
    method: 'POST',
  });
  const { client_secret: clientSecret } = await response.json();
  return clientSecret;
};

export default function App() {
  const [stripeConnectInstance] = useState(() => {
    return loadConnectAndInitialize({
      // This is a placeholder - it should be replaced with your publishable API key.
      // Sign in to see your own test API key embedded in code samples.
      // Don't submit any personally identifiable information in requests made with this key.
      publishableKey: "<<YOUR_PUBLISHABLE_KEY>>",
      fetchClientSecret: fetchClientSecret,
    })
  });

  return (
    <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
      <YourApp />
    </ConnectComponentsProvider>
  );
}
```

Per utilizzare un componente incorporato, importalo e visualizzalo all’interno di `ConnectComponentsProvider`:

```javascript
import { ConnectAccountOnboarding } from '@stripe/stripe-react-native';
import { useState } from 'react';
import { View } from 'react-native';
import Button from '../components/Button';

export default function AccountOnboardingScreen() {
  const [visible, setVisible] = useState(false);

  return (
    <View>
      <Button
        variant="primary"
        title="Show Onboarding"
        onPress={() => setVisible(true)}
      />

      {visible ? (
        <ConnectAccountOnboarding
          onExit={() => {
            setVisible(false);
            console.log('User exited onboarding');
          }}
        />
      ) : null}
    </View>
  );
}
```

## Configure the ConnectComponentsProvider [Lato client]

[Consulta la documentazione di riferimento :external:](https://stripe.dev/stripe-react-native/api-reference/types/StripeConnectInitParams.html).

### Personalizzare l’aspetto dei componenti incorporati di Connect

Il [toolkit Figma di componenti incorporati per personalizzare l’interfaccia utente](https://www.figma.com/community/file/1438614134095442934) contiene tutti i componenti, i pattern comuni e un’applicazione esemplificativa. Puoi utilizzarlo per visualizzare e progettare interfacce utente incorporate sul tuo sito web.

Offriamo una [serie di opzioni](https://docs.stripe.com/connect/embedded-appearance-options.md) per personalizzare l’aspetto dei componenti incorporati di Connect. Queste personalizzazioni influiscono su pulsanti, icone e altri elementi del nostro sistema di progettazione.

> #### Finestre popup necessarie
> 
> Alcuni comportamenti nei componenti incorporati, come l’[autenticazione utente](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#user-authentication-in-connect-embedded-components), devono essere presentati in una vista web autenticata. Non puoi personalizzare il componente incorporato per eliminare tali WebView.

Puoi personalizzare l’aspetto dei componenti incorporati di Connect specificando un’opzione di `appearance` per `loadConnectAndInitialize`.

```javascript
import { ConnectComponentsProvider, loadConnectAndInitialize } from '@stripe/stripe-react-native';
import { useState } from 'react';

const appearance = {
  variables: {
    colorPrimary: '#537D5D',
  },
};

export default function App() {
  const [stripeConnectInstance] = useState(() => {
    const fetchClientSecret = async () => {
      const response = await fetch('/account_session', { method: "POST" });
      const { client_secret: clientSecret } = await response.json();
      return clientSecret;
    };

    return loadConnectAndInitialize({
      publishableKey: "<<YOUR_PUBLISHABLE_KEY>>",
      fetchClientSecret: fetchClientSecret,
      appearance,
    });
  });

  return (
    <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
      {/* Add embedded components and the rest of the UI here */}
    </ConnectComponentsProvider>
  );
}
```

Consulta l’[elenco completo delle opzioni di visualizzazione](https://docs.stripe.com/connect/embedded-appearance-options.md?platform=react-native) di React Native.

### Usa font personalizzati

Se nell’app vengono utilizzati font personalizzati (ad esempio, da file `.otf` o `.ttf` incorporati nell’app), è necessario specificare i file dei font in un `CustomFontSource` specificato nell’opzione `customFonts` quando si chiama `loadConnectAndInitialize`. Ciò consente ai componenti incorporati di Connect di accedere ai file dei font per renderizzarli correttamente.

Per visualizzare correttamente i caratteri specificati in `appearance`, devi utilizzare un `CustomFontSource` specificato in `loadConnectAndInitialize` all’inizializzazione.

### Aggiornare i componenti incorporati di Connect dopo l’inizializzazione

Il metodo `update` supporta l’aggiornamento dei componenti incorporati di Connect dopo l’inizializzazione. Puoi utilizzarlo per cambiare le opzioni di aspetto in fase di esecuzione. Per farlo, utilizza lo stesso oggetto `stripeConnectInstance` che hai creato con `loadConnectAndInitialize` e chiama il metodo `update`:

```javascript
stripeConnectInstance.update({
  appearance: {
    variables: {
      colorPrimary: "#FF0000",
    },
  },
});
```

## Autenticazione

Offriamo una serie di API per gestire le sessioni degli account e le credenziali degli utenti nei componenti incorporati di Connect.

### Aggiornare la chiave privata client

Nelle sessioni di lunga durata, la sessione della *chiave privata client* (The client secret is a unique string returned from Stripe as part of an AccountSession. This string lets the client access a specific Stripe account with Connect embedded components) fornita inizialmente potrebbe scadere. Quando scade, utilizziamo automaticamente `fetchClientSecret` per recuperare una nuova chiave privata client e aggiornare la sessione. Non devi specificare alcun parametro aggiuntivo.

```javascript
import { useState } from 'react';
import { ConnectComponentsProvider } from '@stripe/stripe-react-native';

const fetchClientSecret = async (): Promise<string> => {
  const response = await fetch('https://{{YOUR_SERVER}}/account_session', {
    method: 'POST',
  });
  const { client_secret: clientSecret } = await response.json();
  return clientSecret;
};

export default function App() {
  const [stripeConnectInstance] = useState(() => {
    return loadConnectAndInitialize({
      publishableKey: "{{PUBLISHABLE_KEY}}",
      fetchClientSecret: fetchClientSecret,
    })
  });

  return (
    <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
      <YourApp />
    </ConnectComponentsProvider>
  );
}
```

## Localizzazione

I componenti incorporati di Connect supportano le seguenti lingue:

| Lingua                            | Codice lingua |
| --------------------------------- | ------------- |
| Bulgaro (Bulgaria)                | `bg-BG`       |
| Cinese (semplificato)             | `zh-Hans`     |
| Cinese (tradizionale - Hong Kong) | `zh-Hant-HK`  |
| Cinese (tradizionale - Taiwan)    | `zh-Hant-TW`  |
| Croato (Croazia)                  | `hr-HR`       |
| Ceco (Cechia)                     | `cs-CZ`       |
| Danese (Danimarca)                | `da-DK`       |
| Olandese (Paesi Bassi)            | `nl-NL`       |
| Inglese (Australia)               | `en-AU`       |
| Inglese (India)                   | `en-IN`       |
| Inglese (Irlanda)                 | `en-IE`       |
| Inglese (Nuova Zelanda)           | `en-NZ`       |
| Inglese (Singapore)               | `en-SG`       |
| Inglese (Regno Unito)             | `en-GB`       |
| Inglese (Stati Uniti)             | `en-US`       |
| Estone (Estonia)                  | `et-EE`       |
| Filippino (Filippine)             | `fil-PH`      |
| Finlandese (Finlandia)            | `fi-FI`       |
| Francese (Canada)                 | `fr-CA`       |
| Francese (Francia)                | `fr-FR`       |
| Tedesco (Germania)                | `de-DE`       |
| Greco (Grecia)                    | `el-GR`       |
| Ungherese (Ungheria)              | `hu-HU`       |
| Indonesiano (Indonesia)           | `id-ID`       |
| Italiano (Italia)                 | `it-IT`       |
| Giapponese (Giappone)             | `ja-JP`       |
| Coreano (Corea del Sud)           | `ko-KR`       |
| Lettone (Lettonia)                | `lv-LV`       |
| Lituano (Lituania)                | `lt-LT`       |
| Malese (Malaysia)                 | `ms-MY`       |
| Maltese (Malta)                   | `mt-MT`       |
| Norvegese bokmål (Norvegia)       | `nb-NO`       |
| Polacco (Polonia)                 | `pl-PL`       |
| Portoghese (Brasile)              | `pt-BR`       |
| Portoghese (Portogallo)           | `pt-PT`       |
| Rumeno (Romania)                  | `ro-RO`       |
| Slovacco (Slovacchia)             | `sk-SK`       |
| Sloveno (Slovenia)                | `sl-SI`       |
| Spagnolo (Argentina)              | `es-AR`       |
| Spagnolo (Brasile)                | `es-BR`       |
| Spagnolo (America Latina)         | `es-419`      |
| Spagnolo (Messico)                | `es-MX`       |
| Spagnolo (Spagna)                 | `es-ES`       |
| Svedese (Svezia)                  | `sv-SE`       |
| Tailandese (Thailandia)           | `th-TH`       |
| Turco (Turchia)                   | `tr-TR`       |
| Vietnamita (Vietnam)              | `vi-VN`       |

## Autenticazione utente nei componenti incorporati di Connect

In genere, i componenti incorporati di Connect non richiedono l’autenticazione dell’utente. In alcuni casi i componenti incorporati di Connect richiedono che l’account connesso acceda con il proprio account Stripe prima di accedere al componente per eseguire le funzionalità necessarie, ad esempio inviare informazioni alla persona giuridica dell’account nel caso del componente di [attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md). Altri componenti potrebbero richiedere l’autenticazione all’interno del componente dopo la visualizzazione iniziale.

L’autenticazione è richiesta per gli account connessi in cui Stripe è responsabile della raccolta di informazioni aggiornate quando i requisiti cambiano. Per gli account connessi in cui sei responsabile della raccolta di informazioni aggiornate quando i requisiti lo presuppongono o cambiano, come gli account Custom, l’autenticazione è Stripe è controllata dalla funzione Sessione account [disable_stripe_user_authentication](https://docs.stripe.com/api/account_sessions/create.md#create_account_session-components-account_onboarding-features-disable_stripe_user_authentication). Ti consigliamo di implementare l’autenticazione a due fattori o misure di sicurezza equivalenti come [best practice](https://docs.stripe.com/connect/risk-management/best-practices.md#prevent-account-take-overs). Per le configurazioni degli account che supportano questa funzionalità, come Custom, ti assumi la responsabilità degli account connessi qualora non possano rimborsare i [saldi negativi](https://docs.stripe.com/connect/risk-management/best-practices.md#decide-your-approach-to-negative-balance-liability).

### Componenti che richiedono l’autenticazione

Agli account connessi verrà mostrata una  autenticata nella tua applicazione. L’account connesso deve essere autenticato prima di poter continuare il proprio flusso di lavoro nella WebView.

Il flusso di autenticazione in hosting su Stripe mostra il nome, il colore e l’icona del tuo brand così come sono stati impostati nelle [impostazioni di Connect](https://dashboard.stripe.com/account/applications/settings) e non utilizza l’aspetto e i caratteri personalizzati di [Gestione componenti incorporati](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#configuring-connect) fino al completamento dell’autenticazione.

Il seguente componente richiede l’autenticazione degli account connessi in determinati scenari:

- [Attivazione dell’account](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md)
- [Bonifici](https://docs.stripe.com/connect/supported-embedded-components/payouts.md)

## Gestire gli errori di caricamento [Lato client]

Rispondi agli errori di caricamento dei componenti implementando il metodo del listener `onLoadError` del componente.

Cause di errore diverse potrebbero chiamare il metodo `onLoadError` più volte, quindi qualsiasi logica attivata da `onLoadError` deve essere idempotente.

#### TypeScript

```javascript
// All components emit load errors. This example uses AccountOnboarding.
// All components support onLoadError.
import { ConnectPayouts } from '@stripe/stripe-react-native';

export default function MyComponent() {
  const handleLoadError = (error: Error) => {
    console.log(`Error loading payouts: ${error.message}`);
  };

  return <ConnectPayouts onLoadError={handleLoadError} />;
}
```

## Richiedi accesso  (Private preview)

Accedi per richiedere l’accesso ai componenti incorporati di Connect per React Native in anteprima privata. Se non hai un account Stripe, puoi [registrarti ora](https://dashboard.stripe.com/register).