Concevoir une interface utilisateur

Concevez, testez et modifiez votre interface utilisateur personnalisée pour enrichir les fonctionnalités du Dashboard Stripe.

Attribuez à votre application une interface utilisateur en utilisant TypeScript, React, ainsi que le SDK de l’extension d’interface utilisateur et les outils d’interface utilisateur de Stripe pour ajouter des fonctionnalités au Dashboard Stripe. Ce guide vous explique comment concevoir une interface utilisateur simple en créant et en supprimant des vues.

Pour obtenir un aperçu plus technique, familiarisez-vous avec les extensions d’interface utilisateur.

Ajouter une vue

Utilisez des vues pour développer l’interface utilisateur de votre application. Une vue est l’association d’un composant React et d’une fenêtre d’affichage donnée. Le composant React est constitué d’éléments provenant de notre kit d’outils d’interface utilisateur. La fenêtre d’affichage désigne la page ou la section du Dashboard Stripe où vous souhaitez l’afficher.

Utilisez la commande add dans le répertoire racine de votre projet :
Command Line
```
stripe apps add view
```
Suivez les invites :
- Sélectionnez la fenêtre d’affichage sur laquelle vous souhaitez faire apparaître votre vue. Consultez la liste des fenêtres d’affichage disponibles.
- Nommez votre vue (par exemple, NomComposant). La CLI suggère des noms en se basant sur la fenêtre d’affichage que vous avez sélectionnée.
Stripe ajoute automatiquement votre vue au tableau views dans votre manifeste de l’application, et crée un nouveau fichier de composant React dans le répertoire src/views ainsi qu’un fichier de test unitaire.

Prévisualiser l’application

Dans le Dashboard, vous pouvez exécuter votre application en local, y apporter des modifications et en afficher un aperçu.

Dans le répertoire racine de votre projet, démarrez le serveur de développement :
Command Line
```
stripe apps start
```
Appuyez sur Entrée pour ouvrir votre navigateur.
Cliquez sur Continuer pour afficher un aperçu de l’application sur votre compte Stripe :
Pour arrêter le serveur de développement, saisissez Ctrl+C dans la ligne de commande.

Une fois que le serveur de développement est en cours d’exécution, vous pouvez apporter des modifications à votre application et les voir en temps réel dans le Dashboard, sans avoir à rafraîchir la page. Les erreurs s’affichent automatiquement dans le Dashboard et la CLI Stripe, ainsi que dans les outils de développement de votre navigateur jusqu’à ce que vous les résolviez.

Changer d’aperçu

Vous pouvez désactiver la prévisualisation de la version locale de votre application pour prévisualiser la dernière version installée en mode test ou un environnement de test. Si vous n’avez jamais installé une version de votre application en mode test ou dans un environnement de test, vous ne pouvez pas changer d’aperçu.

Pour afficher un aperçu de la dernière version de votre application installée en mode test ou dans un environnement de test, démarrez votre serveur de développement et suivez ces étapes :

Dans votre application, cliquez sur le menu de débordement situé en haut à droite.
Cliquez sur Désactiver l’aperçu de l’application, puis sur Continuer.

Accéder aux objets Stripe dans le Dashboard

Lorsque vous attribuez un composant à une fenêtre d’affichage, celui-ci peut recevoir du contexte à propos de l’objet Stripe de la page en utilisant l’objet environment.objectContext.

Par exemple, si vous créez une vue qui utilise la fenêtre d’affichage stripe.dashboard.customer.detail, l’objet environment.objectContext renvoie un type d’objet customer et l’ID du client actuel. Vous pouvez ensuite utiliser ces valeurs afin d’obtenir davantage d’informations sur l’objet Customer et modifier ses attributs (adresse, description, etc.).

Pour obtenir l’index des objets proposés par une fenêtre d’affichage, consultez la documentation relative aux fenêtres d’affichage.

Exemple : Mettre à jour le nom du client

Le code suivant permet de mettre à jour le nom du client à l’aide du client API Node.js Stripe et l’ID environment.objectContext de la fenêtre d’affichage :

Ajoutez l’autorisation customer_write à votre application :

Command Line
stripe apps grant permission "customer_write" "Allows the app to update the name of the customer."

Utilisez l’API Stripe dans votre application pour mettre à jour le nom du client :

import {createHttpClient, STRIPE_API_KEY} from '@stripe/ui-extension-sdk/http_client';
import Stripe from 'stripe';

// Initiate communication with the stripe client.
const stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient(),
  apiVersion: '2022-08-01',
})

const App = ({environment, userContext}) => {
  // Call the Stripe API to make updates to customer details.
  const updateCurrentCustomer = async (newCustomerName) => {
    try {
      // If the user has permission to update customers, this should succeed.
      const updatedCustomer = await stripe.customers.update(
        // We can use the current objectContext to get the customer ID.
        environment.objectContext.id,
        {name: newCustomerName}
      );

      console.log(updatedCustomer.name);
    } catch (error) {}
  };
}

Exemple : Mettre à jour les données du Dashboard

Si votre application modifie des données dans le Dashboard, utilisez la fonction useRefreshDashboardData pour générer un rappel qui actualise les données :

import {useCallback} from 'react';
import {useRefreshDashboardData} from '@stripe/ui-extension-sdk/context';

const App = () => {
  // Get the callback used to refresh the dashboard data
  const refreshDashboardData = useRefreshDashboardData();

  // Stripe API call
  const updateCustomer = useCallback(async () => {
    try {
      await updateCurrentCustomer();

      // Call to refresh the data in the Dashboard
      refreshDashboardData();
    } catch (error) {}
  }, [refreshDashboardData]);
}

Utiliser des API tierces

Votre extension d’interface utilisateur peut appeler des API tierces (votre API ou n’importe quelle API publique) pour obtenir ou envoyer des données à partir de votre application.

Utilisez la commande grant url pour ajouter l’URL de l’API tierce :

Command Line
stripe apps grant url "https://*.api.example.com/path/" "Send data to example service..."

L’URL connect-src doit répondre aux exigences suivantes :

Exigence	Exemple
Utilisez le protocole sécurisé HTTPS.	https://www.example.com/api/users/
Contient un chemin d’accès.	Exemple valide : https://www.example.com/api/users/ Exemple non valide : https://www.example.com/
Utilisez un chemin d’accès de base se terminant par une barre oblique pour autoriser tous les chemins qui commencent par celui-ci.	https://www.example.com/api/ permet d’appeler https://www.example.com/api/users/abc123/address.
Ne peut pas être un appel à une API Stripe.
Si vous utilisez un caractère générique (`*`), vous devez l’insérer dans le libellé de DNS situé le plus à gauche.	*https://.example.com/api/users/**

Mise en garde

Si vous rencontrez des problèmes CSP dans le navigateur, vérifiez si vous avez bien ajouté une barre oblique à la fin de votre URL connect-src.

Stripe Apps ajoute l’URL dans le tableau connect-src du manifeste de l’application de votre projet :

"ui_extension": {
    "views": [],
    "actions": [],
    "content_security_policy": {
      "connect-src": [
        "https://*.api.example.com/",
        "https://o0.ingest.example.io/api/",
      ],
      "purpose": "Send data to example service. The Example app sends data to the Example service to provide its functionality and sends anonymous error reports to our partner Example for debugging purposes"
    }
  }

Pour supprimer l’URL d’un connect-src, vous pouvez aussi utiliser la CLI Stripe :

Command Line
stripe apps revoke connect-src "https://*.api.example.com/path/"

Pour afficher un aperçu de votre application dans le navigateur, démarrez votre serveur de développement et suivez les invites de la CLI :
Command Line
```
stripe apps start
```

Ajoutez l’appel fetch à l’API tierce de votre application, accompagné de l’URL.

Par exemple, si vous ajoutez l’URL connect-src https://www.example.com/api/users à votre manifeste de l’application, vous pouvez utiliser cet appel de récupération :

const makeRequestToService = (endpoint, requestData) => {
  return fetch(`https://www.example.com/api/${endpoint}/`, {
    'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: requestData,
  });
};

Pour utiliser différentes valeurs de manifeste d’application en mode production et développement local, chargez un fichier manifeste étendu.
Si l’API tierce dispose d’une bibliothèque JavaScript cliente, vous pouvez ajouter la dépendance à votre application à l’aide de la commande npm add.

Déboguer l’application

Lorsque vous développez votre application, vous pouvez utiliser la console des outils de développement de votre navigateur comme outil de débogage.

Pour isoler les messages liés à votre application :

Accédez à l’ID de votre application dans le manifeste de l’application.
Dans le panneau de commande des outils de développement de votre navigateur, saisissez [Stripe App <your app ID>] dans la zone Filtre (par exemple, [Stripe App com.example.helloworld]).

Écrire des tests pour votre vue

Nous vous recommandons d’écrire des tests pour vos vues. En plus de vérifier que votre vue se comporte comme prévu, les tests unitaires permettent de modifier le code de manière plus sécurisée à l’avenir.

Lorsque vous créez votre vue, le fichier de test se terminant par .test.tsx contient un test de la vue par défaut :

import {render, getMockContextProps} from "@stripe/ui-extension-sdk/testing";
import {ContextView} from "@stripe/ui-extension-sdk/ui";

import App from "./App";

describe("App", () => {
  it("renders ContextView", () => {
    const {wrapper} = render(<App {...getMockContextProps()} />);

    expect(wrapper.find(ContextView)).toContainText("save to reload this view");
  });
});

Vous pouvez exécuter tous vos tests en utilisant l’exécuteur de test Jest inclus, à l’aide de la commande npm run test ou yarn test. Si vous avez déjà utilisé des outils de test React populaires comme Testing Library et Enzyme, vous reconnaîtrez le package de test compris dans @stripe/ui-extension-sdk/testing.

Un test type respecte le schéma suivant :

Affichez la vue.
Effectuez une assertion sur l’état initial, comme du texte existant.
Interagissez avec la vue.
Effectuez une assertion sur le nouvel état, comme du texte supplémentaire qui s’affiche.

Pour découvrir d’autres méthodes et fonctionnalités du package de test, consultez la référence du test de l’interface utilisateur.