# Documentation de l'API Extension SDK Un index de tous les champs, types et descriptions de l'API Extension SDK. Les *extensions d’interface utilisateur* (A set of APIs that allow you to inject user interface elements into the Stripe Dashboard using TypeScript and React) ont accès aux [propriétés de contexte](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#props) et aux [fonctions utilitaires](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#functions) qui leur permettent d’interagir avec l’utilisateur de l’application et l’écosystème du Dashboard Stripe. Cette page décrit ces valeurs et ces fonctions. ## Propriétés Les vues sont des propriétés transmises que l’extension peut utiliser pour connaître la position de son affichage. Votre vue peut intégrer une partie ou la totalité de ces propriétés en tant qu’arguments. Elles sont de type `ExtensionContextValue`. ```ts import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context'; const ExampleApp = ({ userContext, environment, oauthContext, appContext}: ExtensionContextValue) => { ... } ``` ### Contexte utilisateur La propriété `userContext` contient des données concernant l’utilisateur final de votre application, notamment les champs suivants : | Champ | Type | Exemple | | ----------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------- | | name | chaîne | Florence Martin | Nom de l’utilisateur de l’application | | account.country | chaîne | Royaume-Uni | Pays de l’utilisateur de l’application | | account.id | chaîne | acct_1032D82eZvKYlo2C | ID du compte de l’utilisateur de l’application | | account.name | chaîne | Jenny’s Llama Emporium | Le nom du compte Stripe | | account.org_id | chaîne | org_1032D82eZvKYlo2C | ID de l’organisation Stripe à laquelle appartient l’utilisateur de l’application | | account.isSandbox | Booléen | véritable | Indique si le compte Stripe est un environnement de test ou non | | postes | Tableau<[RoleDefinition](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#roledefinition)\> | | Une liste des [rôles d’utilisateurs](https://docs.stripe.com/get-started/account/teams/roles.md) de l’utilisateur actif. | | locale | chaîne | en-GB | ID de la langue du système de l’utilisateur de l’application | ### RôleDéfinition Une définition de rôle comprend les champs suivants : | Nom du champ | Type | Exemple | | ------------ | -------------------- | ----------- | | type | ‘builtIn’ | ‘custom’ | builtIn | Spécifie le type de rôle. Les rôles personnalisés ne sont disponibles que pour les [applications privées](https://docs.stripe.com/stripe-apps/distribution-options.md#share-with-team-members). | | name | chaîne | Développeur | Le nom du rôle d’utilisateur. | ### Environnement La propriété `environment` contient des données à propos de la page affichée par le client, notamment les champs suivants : | Champ | Type | Exemple | | -------------------- | --------------- | ------------------------------------------------ | | viewportID | chaîne | stripe.dashboard.payment.list | Fenêtre actuelle affichant votre vue | | mode | ‘live’ | ‘test’ | live | Le mode de l’API Stripe dans lequel se trouve la page actuelle | | objectContext.id | chaîne | ch_3L0pjB2eZvKYlo2C1u1vZ7aK | Dans les objets `ObjectView`, il s’agit de l’ID de l’objet que l’utilisateur visualise actuellement dans le Dashboard. | | objectContext.object | chaîne | charge | Dans les objets `ObjectView`, il s’agit du type de l’objet que l’utilisateur visualise actuellement dans le Dashboard. | | constantes | Objet | `{"API_BASE": "https://api.example.com/v1"}` | Un objet avec des valeurs constantes arbitraires transmises à partir du *manifeste de l’application* (In a Stripe App, the app manifest is a stripe-app.json file in your app's root directory. It defines your app's ID, views, permissions, and other essential properties), qui peut être [remplacé pour le développement local à l’aide de l’indicateur de manifeste de l’interface de ligne de commande](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#extended-manifest). | | queryParams | Objet | `{"task": "onboardingStart", "source": "email"}` | Paramètres de requête transmis à votre application avec une URL [deep link](https://docs.stripe.com/stripe-apps/deep-links.md). Le préfixe `app_` est supprimé lorsqu’il est transmis avec la propriété `queryParams`. | ### Contexte OAuth La propriété `oauthContext` comporte des informations concernant le [flux OAuth](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md) en cours, le cas échéant. | Champ | Type | Exemple | | -------- | ------ | ------- | | error | chaîne | | Code d’erreur OAuth | | code | chaîne | | Code d’autorisation OAuth | | state | chaîne | | État OAuth utilisé par votre application | | verifier | chaîne | | Vérificateur de code OAuth | ### Contexte de l’application La propriété `appContext` contient des informations sur l’installation de l’application par l’utilisateur et comprend les champs suivants : | Champ | Type | Exemple | | ------------------------ | --------------- | --------------------------------------------------------------- | | authorizedPermissions | Tableau | `['event_read', 'charge_write']` | Autorisations actuellement accordées pour l’application | | authorizedCSP.connectSrc | Tableau | `['http://o.ingest.sentry.io/api/']` | Les URL des API tierces autorisées. Si l’URL se termine par une barre oblique, tous ses enfants reçoivent également l’autorisation. | | authorizedCSP.imageSrc | Tableau | `['https://images.example.com/', 'https://images.example.org']` | URL à partir desquelles charger le composant [Img](https://stripe.com/stripe-apps/ui-toolkit/components/img). Si l’URL termine par une barre oblique, tous ses enfants sont également autorisés. | ## Fonctions utilitaires Le SDK de l’extension d’interface utilisateur fournit ces fonctions afin d’aider les applications à interagir avec l’API Stripe et l’utilisateur du Dashboard. - [clipboardWriteText](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#clipboardWriteText) : écrivez du texte dans le presse-papiers de l’utilisateur final. - [createHttpClient](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#createHttpClient) : obtenez un client API Stripe authentifié. - [createOAuthState](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#createOAuthState) : obtenez les valeurs à utiliser lors de la création d’un lien d’autorisation dans un workflow OAuth. - [fetchStripeSignature](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#fetchStripeSignature) : obtenez une signature des serveurs de Stripe. - [getDashboardUserEmail](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#getDashboardUserEmail) : obtenez l’adresse e-mail du client final. - [getUserAuthorizedPermissions](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#getUserAuthorizedPermissions) : permet de recevoir la correspondance entre les autorisations accordées pour l’application et celles de l’utilisateur actuel du Dashboard. - [isPermissionAuthorized](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#isPermissionAuthorized) : indiquez si une autorisation fait actuellement partie des autorisations accordées pour une application. - [isSourceInAuthorizedCSP](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#isSourceInAuthorizedCSP) : indiquez si une URL se trouve actuellement dans la politique de sécurité du contenu autorisé d’une application. - [showToast](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#showToast) : montre un message transitoire à l’utilisateur. - [useRefreshDashboardData](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#useRefreshDashboardData) : permet à votre affichage de mettre à jour les données dans le Dashboard. - [useStockage](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#useStorage) : partagez des données entre différentes fenêtres d’affichage d’une application Stripe. ### clipboardWriteText Écrivez du texte dans le presse-papiers de l’utilisateur de l’application. L’utilisateur peut aussi le coller comme s’il l’avait copié lui-même. | Argument | Type | Exemple | | -------- | ------ | ------------- | | text | chaîne | Hello, world! | Texte à copier | Pour utiliser cette fonction, importez-la d’abord depuis le SDK : ```ts import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils'; ``` Par exemple, ajoutez un bouton qui copie `Hello, world!` dans le presse-papiers lorsque l’on clique dessus. Dans l’application réelle, vous pouvez l’utiliser pour copier une adresse, un numéro de facture ou d’autres informations importantes. ```ts import {useCallback} from 'react'; import {Button} from '@stripe/ui-extension-sdk/ui'; import {clipboardWriteText} from '@stripe/ui-extension-sdk/utils'; const App = () => { const writeToClipboard = useCallback(async () => { try { await clipboardWriteText('Hello, world!'); // Writing to the clipboard succeeded } catch (e) { // Writing to the clipboard failed } }, []); return ( ); }; ``` ### createHttpClient Obtenez un client API Stripe authentifié pour le compte de l’utilisateur installé. Vous devez utiliser la `STRIPE_API_KEY` fournie par le SDK pour donner à votre client les autorisations définies dans le [manifeste de l’application](https://docs.stripe.com/stripe-apps/reference/app-manifest.md). Pour utiliser cette fonctionnalité, importez-la d’abord depuis le SDK, puis fournissez ses valeurs au constructeur Stripe depuis [stripe-node](https://github.com/stripe/stripe-node). ```ts import {createHttpClient, STRIPE_API_KEY} from '@stripe/ui-extension-sdk/http_client'; import Stripe from 'stripe'; const stripe = new Stripe( STRIPE_API_KEY, { httpClient: createHttpClient(), apiVersion: '2022-11-15' } ); ``` Pour découvrir un exemple en contexte, consultez la page dédiée à la [création d’une interface utilisateur](https://docs.stripe.com/stripe-apps/build-ui.md#code-sample-update-customer-name). ### createOAuthState Obtenez les valeurs `state` et `challenge` à utiliser lors de la [création d’un lien d’autorisation](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md#create-authorization-link) dans un flux OAuth. Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {createOAuthState} from '@stripe/ui-extension-sdk/utils'; ``` Pour voir un exemple en contexte, consultez la page consacrée à l’[ajout de flux d’autorisation](https://docs.stripe.com/stripe-apps/pkce-oauth-flow.md). ### fetchStripeSignature Obtenez une signature des serveurs Stripe. Votre extension de l’interface utilisateur peut utiliser cette signature pour envoyer des requêtes signées au back-end de votre application. Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {fetchStripeSignature} from '@stripe/ui-extension-sdk/utils'; ``` Pour en savoir plus et voir un exemple en contexte, consultez la documentation relative à la [logique côté serveur](https://docs.stripe.com/stripe-apps/build-backend.md). ### getDashboardUserEmail Obtenez l’adresse e-mail de l’utilisateur de l’application. Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils'; ``` Vous devez également inclure l’autorisation `user_email_read` dans le [manifeste de votre application](https://docs.stripe.com/stripe-apps/reference/app-manifest.md). Ajoutez-la en utilisant via la CLI ou en modifiant directement le manifeste de l’application. #### Commande de la CLI ```bash stripe apps grant permission user_email_read "EXPLANATION" # Une explication de la raison pour laquelle votre application a besoin de ces autorisations. Les administrateurs la voient lorsqu'ils décident s'ils doivent approuver les autorisations. ``` Par exemple, accédez à l’adresse e-mail de l’utilisateur de l’application dans une vue en utilisant la fonction `getDashboardUserEmail` et en l’enregistrant dans une variable d’état React. ```ts import {useEffect, useState} from 'react'; import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils'; export const useDashboardUserEmail = () => { const [email, setEmail] = useState(null); const fetchEmail = async () => { try { const {email} = await getDashboardUserEmail(); setEmail(email); } catch(e) { console.error(e); } }; useEffect(() => { fetchEmail(); }, []); return email; }; const App = () => { const dashboardUserEmail = useDashboardUserEmail(); ... }; ``` ### getUserAuthorizedPermissions Permet de recevoir la correspondance entre les autorisations accordées pour l’application et celles de l’utilisateur actuel du Dashboard. Par exemple, si les [autorisations actuellement accordées](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md#appContext) pour l’application sont `event_read` et `charge_write`, mais que l’utilisateur actuel du Dashboard dispose d’un rôle `view_only` (c’est-à-dire qu’il ne dispose d’aucune autorisation de modification), l’appel de la fonction renvoie le tableau `['event_read']`. Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {getUserAuthorizedPermissions} from '@stripe/ui-extension-sdk/utils'; ``` ### isPermissionAuthorized Indiquez si une autorisation fait partie des autorisations accordées pour l’application. Renvoie une erreur si l’autorisation ne figure pas dans le manifeste de l’application. | Argument | Type | Exemple | | ---------- | ------ | ----------- | | permission | chaîne | charge_read | Autorisation de vérification | Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {isPermissionAuthorized} from '@stripe/ui-extension-sdk/utils'; ``` #### Fonctionnalités de limitation d’accès selon l’autorisation Cette fonction permet de limiter les fonctionnalités de l’application en fonction des autorisations accordées par l’utilisateur. Par exemple, sur la page relative aux informations d’un client, ne mettez à jour les informations d’un client que si l’utilisateur de l’application dispose de l’autorisation `customer_write`. ```ts import {isPermissionAuthorized} from '@stripe/ui-extension-sdk/utils'; const App = () => { const updateCustomer = useCallback(async () => { const customerWriteEnabled = await isPermissionAuthorized('customer_write'); if (customerWriteEnabled){ await updateCurrentCustomer() } ... }) } ``` ### isSourceInAuthorizedCSP Indiquez si une URL se trouve dans les sources de connexion ou les sources d’images autorisées de l’application. | Argument | Type | Exemple | | -------- | ------ | --------------------------- | | source | chaîne | https://images.example.org/ | URL à vérifier | Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {isSourceInAuthorizedCSP} from '@stripe/ui-extension-sdk/utils'; ``` ### showToast Affichez un message transitoire en bas de votre vue pour informer l’utilisateur de l’état d’une action, par exemple pour lui signaler la réussite ou de l’échec d’un appel à l’API. ```ts import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = () => { fetch(...) .then((response) => { showToast("Invoice updated", {type: "success"}) return response.json() }) .catch(() => { showToast("Invoice could not be updated", {type: "caution"}) }) } // Use the `handleClick`... } ``` La fonction `showToast()` accepte deux arguments : `message` et `options`. La fonction est définie comme suit : ```ts type ToastType = "success" | "caution" | "pending" | undefined; type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; } const showToast: (message: string, options?: ToastOptions) => Promise<{ update: (updateMessage: string, updateOptions?: ToastOptions) => void; dismiss: () => void; }>; ``` Les messages transitoires ne peuvent pas comporter plus de 30 caractères ni être vides. Si un message est trop long ou vide, la console enregistre une erreur. Les messages transitoires se ferment automatiquement, sauf s’ils sont de type `pending`. | En attente | A une action | Délai expiré | | ---------- | ------------ | ------------ | | `false` | `false` | 4s | | `false` | `true` | 6s | | `true` | `false` | Aucune | | `true` | `true` | Aucune | ```ts import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = async () => { const { dismiss, update } = await showToast("Refreshing data", { type: "pending", }); try { await refreshData(); dismiss(); } catch (error) { update("Data could not be refreshed", { type: "caution" }); } } // Use the `handleClick`... } ``` Les messages transitoires peuvent également inviter l’utilisateur à effectuer une action. Cliquer sur le bouton d’action permet alors de fermer automatiquement le message transitoire. ```ts import {showToast} from '@stripe/ui-extension-sdk/utils'; const App = () => { const handleClick = async () => { let timeout; const { dismiss } = await showToast('Message "sent"', { action: "Undo", onAction: () => { clearTimeout(timeout); showToast('Message "unsent"'); }, }); timeout = setTimeout(() => { sendMessage(); dismiss(); }, 3000); } // Use the `handleClick`... } ``` ### useRefreshDashboardData Autorisez votre vue à mettre à jour les données dans le Dashboard. Cette fonction renvoie une autre fonction de rappel. Enregistrez ce rappel et appelez-le en cas de modification des données Stripe. Le Dashboard s’actualise alors pour tenir compte des nouvelles valeurs. Pour utiliser cette fonction, importez-la d’abord depuis le SDK. ```ts import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils'; ``` Par exemple, sur la page relative aux informations d’un client, obtenez la fonction de rappel qui actualise les données du Dashboard et appelez-la après avoir mis à jour les données du client. ```ts import {useCallback} from 'react'; import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/utils'; const App = () => { const refreshDashboardData = useRefreshDashboardData(); const updateCustomer = useCallback(async () => { try { await updateCurrentCustomer(); await refreshDashboardData(); } catch (error) {} }, [refreshDashboardData]); } ``` ### useStorage > Le hook React `useStorage` est uniquement disponible dans la version 9.x du SDK. Vous pouvez utiliser le hook React `useStorage` pour lire et écrire des données partagées entre différentes fenêtres d’affichage d’une application Stripe. Ce hook synchronise l’état de toutes les instances actives (fenêtres d’affichage) de votre application Stripe dans un même navigateur. Lorsque la valeur est mise à jour dans une instance, toutes les autres instances de ce navigateur répercutent automatiquement la modification. Il s’agit d’un stockage basé sur les sessions, qui ne persiste que pendant l’exécution de l’application. Ce hook peut vous aider à : - Coordonnez l’état entre plusieurs fenêtres d’affichage de votre application. - Évitez les appels redondants à l’API en mettant en cache les données extraites et en les partageant avec les différentes fenêtres d’affichage. Le hook présente les limitations suivantes : - Les valeurs étant limitées aux chaînes, utilisez `JSON.stringify` ou `JSON.parse` pour les objets complexes. - Le stockage ne persiste pas d’une session d’application à une autre. - Les modifications apportées au stockage ne sont pas synchronisées entre différents navigateurs ou appareils. L’exemple suivant montre comment deux instances indépendantes de la même application peuvent synchroniser la valeur d’une variable sur différentes fenêtres d’affichages. Essayez d’ouvrir cette application dans plusieurs onglets pour voir comment fonctionne la synchronisation entre fenêtres. ## See also - [Fonctionnement des extensions d’interface utilisateur](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md) - [Documentation relative aux fenêtres d’affichage](https://docs.stripe.com/stripe-apps/reference/viewports.md) - [Utilisation de rôles dans les extensions d’interface utilisateur](https://docs.stripe.com/stripe-apps/using-roles-in-ui-extensions.md)