Documentation de l'API Extension SDK

Les extensions d’interface utilisateur ont accès aux propriétés de contexte et aux fonctions utilitaires 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.

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 :

RôleDéfinition

Une définition de rôle comprend les champs suivants :

Environnement

La propriété environment contient des données à propos de la page affichée par le client, notamment les champs suivants :

Contexte OAuth

La propriété oauthContext comporte des informations concernant le flux OAuth en cours, le cas échéant.

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 :

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 : écrivez du texte dans le presse-papiers de l’utilisateur final.
• createHttpClient : obtenez un client API Stripe authentifié.
• createOAuthState : obtenez les valeurs à utiliser lors de la création d’un lien d’autorisation dans un workflow OAuth.
• fetchStripeSignature : obtenez une signature des serveurs de Stripe.
• getDashboardUserEmail : obtenez l’adresse e-mail du client final.
• getUserAuthorizedPermissions : permet de recevoir la correspondance entre les autorisations accordées pour l’application et celles de l’utilisateur actuel du Dashboard.
• isPermissionAuthorized : indiquez si une autorisation fait actuellement partie des autorisations accordées pour une application.
• isSourceInAuthorizedCSP : indiquez si une URL se trouve actuellement dans la politique de sécurité du contenu autorisé d’une application.
• showToast : montre un message transitoire à l’utilisateur.
• useRefreshDashboardData : permet à votre affichage de mettre à jour les données dans le Dashboard.
• useStockage : 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.

Pour utiliser cette fonction, importez-la d’abord depuis le SDK :

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.

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 (
    <Button
      onPress={writeToClipboard}
    >
      Copy to clipboard
    </Button>
  );
};

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.

Pour utiliser cette fonctionnalité, importez-la d’abord depuis le SDK, puis fournissez ses valeurs au constructeur Stripe depuis stripe-node.

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.

createOAuthState

Obtenez les valeurs state et challenge à utiliser lors de la création d’un lien d’autorisation dans un flux OAuth.

Pour utiliser cette fonction, importez-la d’abord depuis le SDK.

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.

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.

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.

getDashboardUserEmail

Obtenez l’adresse e-mail de l’utilisateur de l’application.

Pour utiliser cette fonction, importez-la d’abord depuis le SDK.

import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils';

Vous devez également inclure l’autorisation user_email_read dans le manifeste de votre application. Ajoutez-la en utilisant via la CLI ou en modifiant directement le manifeste de l’application.

stripe apps grant permission user_email_read 
"EXPLANATION"

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.

import {useEffect, useState} from 'react';
import {getDashboardUserEmail} from '@stripe/ui-extension-sdk/utils';

export const useDashboardUserEmail = () => {
  const [email, setEmail] = useState<string | null>(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 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.

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.

Pour utiliser cette fonction, importez-la d’abord depuis le SDK.

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.

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.

Pour utiliser cette fonction, importez-la d’abord depuis le SDK.

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.

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 :

type ToastType = "success" | "caution" | "pending" | undefined;
type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; }
(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.

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.

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.

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.

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

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.

import React from 'react';
import {Box, TextField} from '@stripe/ui-extension-sdk/ui';
import {useStorage} from '@stripe/ui-extension-sdk/data';

const [name, setName] = useStorage('name');
const greeting = name ? `Hey ${name}!` : `Hello!`;

return (
  <Box css={{stack: 'y', alignY: 'top', gap: 'medium', width: 'fill'}}>
    <TextField
      label="Full name"
      placeholder="Enter your name"
      defaultValue={name || ''}
      onChange={(e) => setName(e.target.value)}
    />
    <Box css={{font: 'title'}}>{greeting}</Box>
  </Box>
)