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.

Web

iOS

Android

Per una versione immersiva di questa guida, consulta la Guida rapida per l’integrazione dei componenti incorporati di Connect. Puoi anche scaricare un esempio di integrazione. Per personalizzare l’aspetto dei componenti incorporati di Connect, utilizza le opzioniappearance quando utilizzi StripeConnectInstance. Consulta l’elenco completo dei parametri di aspetto.

Inizializzare Connect.js
Lato client
Lato server

Stripe utilizza un oggetto AccountSession per esprimere la tua intenzione di delegare l’accesso API al tuo account connesso.

L’API AccountSessions restituisce una chiave privata client che consente a un componente incorporato di accedere alle risorse di un account connesso come se facessi le chiamate API per suo conto.

Create 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:

Creare l’API Account Session

L’API Create Account Session determina l’accesso ai componenti e alle funzioni per i componenti incorporati 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 la sessione dell’account corrispondano al ruolo dell’utente corrente. Ad esempio, puoi abilitare la gestione dei rimborsi solo per gli amministratori del tuo sito, ma non per gli altri utenti. Per assicurarti che l’accesso al ruolo utente sia applicato, devi associare il ruolo utente del tuo sito ai componenti della sessione dell’account.

Configurare Connect.js Client

Consigliamo di configurare Connect.js con npm come mostrato nell’esempio seguente, ma è possibile anche senza npm.

Installa il pacchetto npm per utilizzare Connect.js come modulo.

Command Line
npm install --save @stripe/connect-js

Caricare e inizializzare 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.

Per creare un componente, chiama create sulla StripeConnectInstance creata in precedenza, poi specifica il nome del componente. Viene restituito un elemento personalizzato 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.

Visualizza l’elenco completo dei componenti incorporati supportati →

Configure Connect.js
Lato client

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

Opzioni	Descrizione
`publishableKey`	La chiave pubblicabile per la tua integrazione.	obbligatorio
`fetchClientSecret`	La funzione che recupera la chiave privata client 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 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 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 o CustomFontSource.	facoltativo

Personalizzare l’aspetto dei componenti incorporati di Connect

Il toolkit Figma di componenti incorporati per personalizzare l’interfaccia utente 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 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, 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 per modificare gli stili nei componenti incorporati di Connect. La famiglia di caratteri e il colore dello sfondo dei componenti incorporati di Connect possono essere sovrascritti con i selettori CSS, ma Stripe non supporta la sovrascrittura di altri stili.

index.js
const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
  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",
    },
  },
});

L’oggetto fonts

L’oggetto fonts in stripeConnect.initialize accetta una matrice di oggetti CssFontSource o CustomFontSource.

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 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. Il file deve essere in hosting su https. Se utilizzi un criterio di sicurezza del contenuto (CSP), il file potrebbe richiedere direttive aggiuntive.

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 valido che punta al file del carattere personalizzato. Di solito, anche se non sempre, si tratta di un collegamento a un file con suffisso `.woff` , `.otf` o `.svg`. Il file deve essere in hosting su https.
`display`	stringa `optional`	`auto`
Un valore 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 valido.
`weight`	stringa `optional`	`400`
Un valore font-weight valido. Si tratta di una stringa, non di un numero.

L’oggetto appearance

L’oggetto appearance in loadConnectAndInitialize accetta le seguenti proprietà opzionali:

Nome	Tipo	Valore di esempio
`overlays`	‘dialog’ (default) \| ‘drawer’	`dialog`
Il tipo di sovrapposizione utilizzato in tutto il sistema di progettazione Connect.js. Impostalo come finestra di dialogo o riquadro a scomparsa.
`variables`	oggetto	`{colorPrimary: "#0074D4"}`
Consulta l’elenco completo delle variabili di aspetto.

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:

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

Nota

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 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.

index.js
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.

index.js
// 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, 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 da utilizzare con componenti incorporati di Connect, l’URL deve essere consentito dalla direttiva CSP connect-src.

L’impostazione di determinate intestazioni di risposta HTTP abilita la piena funzionalità dei componenti incorporati di Connect:

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 nei componenti incorporati di Connect.

Browser supportati

Supportiamo lo stesso set di browser attualmente supportati dalla Dashboard Stripe:

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

I componenti incorporati di Connect sono supportati solo nei browser web e non possono essere utilizzati nelle visualizzazioni web incorporate all’interno di applicazioni desktop o per dispositivi mobili.

Localizzazione

Quando si inizializza Connect.js, è 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.

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 `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	`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 associamo a uno dei tipi seguenti. 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
`api_error`	Errori API relativi a qualsiasi altro tipo di problema, ad esempio un problema temporaneo con i server di Stripe

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.

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

Usare Connect.js senza npm

Ti consigliamo di eseguire l’integrazione con i nostri wrapper di componenti di JavaScript e React, 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.

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

Al termine del caricamento, Connect.js inizializza la variabile StripeConnect della finestra globale e chiama StripeConnect.onLoad, se definito. Puoi inizializzare Connect.js in modo sicuro configurando una funzione onload e chiamando StripeConnect.init con le stesse opzioni di Connect.js di loadConnectAndInitialize. Puoi utilizzare l’istanza di Connect restituita da init nello stesso modo in cui utilizzi l’istanza restituita da loadConnectAndInitialize per creare componenti incorporati in un’integrazione HTML + JS.

index.js
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: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
      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. 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. Ti consigliamo di implementare l’autenticazione a due fattori o misure di sicurezza equivalenti come best practice. 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.

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:

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.
Crea una singola istanza di Connect: crea una singola istanza di Connect chiamando loadConnectAndInitialize solo una volta per sessione. Quindi riutilizza l’istanza per creare e gestire più componenti. Un errore comune consiste nel creare un’istanza di Connect per componente o più istanze di Connect per sessione. Ciò causa un ulteriore consumo di risorse e richieste API. Se utilizzi React, puoi 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 o 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.