Documentation du manifeste d'application

Comprendre le manifeste d'application, un index de tous les champs, types et descriptions de votre fichier de manifeste d'application.

Un manifeste d’application décrit comment votre application s’intègre à la plateforme Stripe. Chaque application Stripe a besoin d’un fichier de manifeste stripe-app.json en racine de la structure de répertoire du projet.

Vous pouvez mettre à jour le manifeste de l’application à l’aide de la CLI Stripe Apps, ou le modifier directement. Par exemple, vous pouvez ajouter une autorisation en utilisant la commande stripe apps grant permission ou en ajoutant directement une permissionRequest au manifeste de l’application.

Les fichiers du manifeste de l’application suit le schéma décrit ci-dessous.

Exemple

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "permissions": [
    {
      "permission": "invoice_write",
      "purpose": "Allows [YOUR APP] to add shipping line items to an invoice."
    },
    {
      "permission": "product_read",
      "purpose": "Allows [YOUR APP] to use product sizes for calculating shipping."
    }
  ],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "AddShipping"
      }
    ],
    "content_security_policy": {
      "connect-src": [
        "https://api.example.com/a_specific_endpoint",
        "https://api.example.com/a_whole_subdirectory/"
      ],
      "image-src": [
        "https://images.example.com/one_image.jpg",
        "https://images.example.com/a_whole_subdirectory/"
      ],
      "purpose": "These URLs allow the app to contact [YOUR APP] for creating shipping details and loading images of shipping partner logos"
    }
  },
  "post_install_action": {
    "type": "external",
    "url": "https://example.com"
  },
  "constants": {
    "API_BASE": "https://api.example.com"
  }
}

Schéma

Les fichiers de manifeste d’application sont des fichiers JSON qui comportent les champs suivants :

Nom du champ	Type	Exemples
id	slug	com.invoicing.myapp
Un identifiant unique pour votre application, que vous définissez. Stripe le valide lors de la soumission initiale.
version	chaîne	1.2.4
Une version d’application que vous définissez. Vous pouvez utiliser le format de votre choix pour les identifiants de version.
name	chaîne	Mon Application
Le nom affiché dans l’interface utilisateur lorsque l’on fait référence à votre application. Les applications à distribution publique ne doivent pas comporter les termes « Stripe », « application », « gratuit » ou « payant ».
icon	chaîne	./favicon.png
Le chemin relatif dans le paquet d’application menant vers une icône PNG 300x300 pixels à afficher avec l’attribution.
distribution_type	« publique » \| « privée »	« publique »
Le type de distribution de l’application.
stripe_api_access_type	« plateforme » \| « oauth » \| « restricted_api_key »	oauth
La méthode d’authentification de l’API de votre application.
allowed_redirect_uris	Matrice<String>	none
Les URL vers lesquelles les utilisateurs sont redirigés après l’installation de votre application avec OAuth ou avec un lien d’installation.
permissions	Tableau<PermissionRequest>	none
Les autorisations dont l’application a besoin pour fonctionner.
ui_extension	UIExtensionManifest	none
Configuration spécifique de la fonctionnalité « Extension d’interface utilisateur ».
post_install_action	PostInstallAction	none
Configuration facultative qui redirige les utilisateurs vers un emplacement personnalisé une fois l’application installée.
constantes	Objet	`{"API_BASE": "https://api.example.com/v1"}`
Un objet avec des valeurs constantes arbitraires auxquelles vous pouvez accéder dans les propriétés de contexte de l’extension d’interface utilisateur et remplacer pour le développement local à l’aide de l’indicateur de manifeste de la CLI.

PermissionRequest

Une demande d’autorisation comporte les champs suivants :

Nom du champ	Type	Exemple
permission	chaîne	customer_write
Autorisations demandées par l’application. En savoir plus sur les autorisations.
purpose	chaîne \| Map<locale, string>	« Cette application charge des images depuis images.example.com. »
Une explication destinée à l’utilisateur dévoilant aux personnes qui installent votre application les raisons pour lesquelles celle-ci a besoin de ces autorisations.
name	chaîne	« Il est nécessaire pour [VOTRE APPLICATION] de mettre à jour les factures associées aux frais de livraison sélectionnés »
Une explication destinée à Stripe dévoilant aux réviseurs de l’application les raisons pour lesquelles votre application a besoin de ces autorisations.

UiExtensionManifest

Un manifeste d’extension d’interface utilisateur comporte les champs suivants :

Nom du champ	Type	Exemple
views	Tableau<ViewManifest>	none
Composants React qui s’affichent dans le Dashboard à un endroit distinct. En savoir plus.
content_security_policy	CSPRequest	none
Requête pour que votre extension d’interface utilisateur obtienne un accès à des URL spécifiques pour un motif donné.

ViewManifest

Un manifeste de vue comporte les champs suivants :

Nom du champ	Type	Exemple
viewport	chaîne	stripe.dashboard.invoice.detail
Un identifiant qui indique à quel endroit peut apparaître une extension d’interface utilisateur dans le Dashboard. Consultez la liste des fenêtres d’affichage disponibles.
component	chaîne	AddShippingSelector
Un composant React exporté qui utilise l’un de nos composants de vue.

CSPRequest

Une demande de politique de sécurité du contenu comporte les champs suivants :

Nom du champ	Type	Exemple
connect-src	Tableau<string>	https://o0.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. Pour en savoir plus, consultez la section sur l’utilisation d’API tierces.
image-src	Tableau<string>	https://images.example.com/
URLs the Img component can load from. If the URL ends in a slash, all of its children also receive permission.
purpose	chaîne \| Map<locale, string>	« Cette application charge des images depuis https://images.example.com et envoie des rapports d’erreur anonymes à notre partenaire Sentry à des fins de débogage. »
Explication à présenter aux utilisateurs lors de l’installation de l’application, décrivant la raison pour laquelle le plugin doit communiquer directement avec ces URL.

Les URL doivent être conformes aux directives de la politique de sécurité du contenu. Nous n’autorisons que les schémas HTTPS.

PostInstallAction

Une action post-installation comporte les champs suivants :

Nom du champ	Type	Exemple
type	chaîne	`external`, `settings`
Action supplémentaire à réaliser après l’installation de votre application dans le Dashboard Stripe par vos utilisateurs. Pour en savoir plus, consultez la page relative à l’activation de la configuration post-installation.
url	chaîne	https://example.com
URL externe vers laquelle rediriger les utilisateurs une fois qu’ils ont installé votre application. Obligatoire uniquement si le type d’action de post-installation est `external`.

Utiliser un fichier manifeste étendu pour le développement

Lors du développement local, il se peut que vous deviez utiliser des valeurs de manifeste d’application différentes de celles que vous utilisez en mode production. Par exemple, le back-end de votre application peut se trouver sur https://api.example.com/v1, alors que votre back-end de développement local s’exécute sur http://localhost:8888/v1.

Compte tenu de cet exemple de fichier manifeste :

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [],
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.invoice.detail",
        "component": "InvoiceDetail"
      }
    ],
    "content_security_policy": {
      "connect-src": ["https://api.example.com/v1"],
      "purpose": "Allow the app to retrieve example data"
    }
  },
  "constants": {
    "API_BASE": "https://api.example.com/v1"
  }
}

Créez un autre fichier manifeste nommé stripe-app.[anything].json qui étend votre manifeste principal et le remplace par des valeurs locales. Par exemple :

stripe-app.dev.json
{
  "extends": "stripe-app.json",
  "ui_extension": {
    "content_security_policy": {
      "connect-src": ["http://localhost:8888/v1"]
    }
  },
  "constants": {
    "API_BASE": "http://localhost:8888/v1"
  }
}

Pour utiliser le fichier manifeste local pendant le développement, chargez-le à l’aide de l’indicateur --manifest. Par exemple :

Command Line
stripe apps start --manifest stripe-app.dev.json

Accédez aux valeurs constants dans vos vues à l’aide des propriétés contextuelles. Par exemple :

import {useEffect, useState} from 'react';
import type {ExtensionContextValue} from '@stripe/ui-extension-sdk/context';
import {Box} from '@stripe/ui-extension-sdk/ui';

const InvoiceDetail = ({environment}: ExtensionContextValue) => {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch(`${environment.constants.API_BASE}/some-endpoint`)
      .then(response => response.json())
      .then(json => setData(json));
  }, []);

  return data ? <Box>Here is your message: {data.message}</Box> : 'Loading...';
};