Dokumentacja manifestu aplikacji
Plik manifestu stripe-app.json to centralna konfiguracja Twojej aplikacji Stripe. Deklaruje tożsamość aplikacji, uprawnienia, widoki interfejsu, zasady bezpieczeństwa oraz zachowanie po instalacji.
Pełny przykład manifestu
{ "id": "com.tajo.brevo-integration", "version": "1.2.0", "name": "Tajo for Brevo", "icon": "./assets/icon.png", "distribution_type": "public", "sandbox_install_compatible": true, "stripe_api_access_type": "oauth", "allowed_redirect_uris": [ "https://tajo.io/stripe/callback", "https://tajo.io/stripe/oauth/complete" ], "permissions": [ { "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts" }, { "permission": "customer_write", "purpose": "Update customer metadata with Brevo sync status" }, { "permission": "charge_read", "purpose": "Access payment history for Brevo event tracking" }, { "permission": "product_read", "purpose": "Sync product catalog to Brevo for personalized campaigns" }, { "permission": "event_read", "purpose": "Subscribe to real-time events for Brevo automation triggers" }, { "permission": "invoice_read", "purpose": "Track invoice lifecycle events in Brevo" } ], "ui_extension": { "views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.customer.list", "component": "CustomerListView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }, { "viewport": "stripe.dashboard.drawer.default", "component": "DrawerView" }, { "viewport": "stripe.dashboard.settings", "component": "SettingsView" }, { "viewport": "stripe.dashboard.onboarding", "component": "OnboardingView" } ], "content_security_policy": { "connect-src": [ "https://api.tajo.io", "https://api.brevo.com" ], "image-src": [ "https://cdn.tajo.io", "https://assets.brevo.com" ], "purpose": "Connect to Tajo API for data sync and Brevo API for contact management" } }, "post_install_action": { "type": "onboarding" }, "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300" }}Dokumentacja schematu
Pola najwyższego poziomu
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
id | string | Tak | Unikalny identyfikator aplikacji w odwróconej notacji domenowej (format slug) |
version | string | Tak | Ciąg wersji semantycznej (np. "1.2.0") |
name | string | Tak | Nazwa wyświetlana w marketplace (maks. 35 znaków) |
icon | string | Tak | Względna ścieżka do pliku ikony aplikacji (PNG lub SVG 300x300) |
distribution_type | string | Tak | "public" dla marketplace lub "private" do użytku wewnętrznego |
sandbox_install_compatible | boolean | Nie | Czy aplikację można zainstalować w trybie sandbox/testowym |
stripe_api_access_type | string | Nie | Metoda dostępu do API: "oauth" lub "api_key" |
allowed_redirect_uris | string[] | Nie | Dozwolone adresy przekierowania OAuth w procesie instalacji |
permissions | PermissionRequest[] | Tak | Tablica żądań uprawnień |
ui_extension | UIExtensionManifest | Nie | Konfiguracja rozszerzenia interfejsu |
post_install_action | PostInstallAction | Nie | Działanie wykonywane po instalacji aplikacji |
constants | object | Nie | Pary klucz-wartość dostępne w aplikacji w czasie działania |
id
Identyfikator aplikacji to ciąg w formacie slug, zwykle w odwróconej notacji domenowej:
"id": "com.tajo.brevo-integration"- Musi być globalnie unikalny wśród wszystkich aplikacji Stripe Apps
- Używaj wyłącznie małych liter, cyfr, myślników i kropek
- Nie można go zmienić po utworzeniu aplikacji
- Wyznacza adres URL aplikacji w marketplace
version
Stosuje wersjonowanie semantyczne:
"version": "1.2.0"- MAJOR: zmiany łamiące zgodność lub istotne nowe funkcje
- MINOR: nowe funkcje, zgodne wstecz
- PATCH: poprawki błędów i drobne usprawnienia
- Musi być zwiększana przy każdym przesłaniu aplikacji
distribution_type
Decyduje o tym, kto może zainstalować Twoją aplikację:
| Wartość | Opis |
|---|---|
"public" | Dostępna w Stripe App Marketplace dla wszystkich użytkowników |
"private" | Instalowalna wyłącznie na Twoim własnym koncie Stripe |
stripe_api_access_type
Określa, jak Twoja aplikacja uwierzytelnia się w API Stripe:
| Wartość | Opis |
|---|---|
"oauth" | Używa procesu OAuth 2.0 do uwierzytelniania (zalecane dla aplikacji publicznych) |
"api_key" | Używa kluczy API z ograniczeniami (odpowiednie dla aplikacji prywatnych) |
PermissionRequest
Każde żądanie uprawnienia deklaruje konkretne uprawnienie API Stripe, którego potrzebuje Twoja aplikacja:
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
permission | string | Tak | Identyfikator uprawnienia (zobacz Dokumentację uprawnień) |
purpose | string | Tak | Zrozumiałe dla człowieka wyjaśnienie, dlaczego to uprawnienie jest potrzebne |
Wskazówki do pola purpose:
- Pisz jasne, konkretne wyjaśnienia, zrozumiałe dla sprzedawców
- Wyjaśniaj, do czego uprawnienie służy, a nie tylko co daje
- Formułuj opisy zwięźle (jedno zdanie)
- Unikaj technicznego żargonu
UIExtensionManifest
Konfiguruje komponenty interfejsu Twojej aplikacji:
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
views | ViewManifest[] | Tak | Tablica deklaracji widoków |
content_security_policy | CSPRequest | Nie | Content Security Policy dla zasobów zewnętrznych |
ViewManifest
Każdy widok przypisuje komponent React do viewportu w Stripe Dashboard:
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
viewport | string | Tak | Miejsce w Dashboardzie, w którym renderuje się ten widok (zobacz Dokumentację viewportów) |
component | string | Tak | Nazwa komponentu React do wyrenderowania (musi odpowiadać nazwie eksportowanego komponentu) |
Pojedyncza aplikacja może deklarować wiele widoków dla różnych viewportów:
"views": [ { "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView" }, { "viewport": "stripe.dashboard.payment.detail", "component": "PaymentDetailView" }, { "viewport": "stripe.dashboard.home.overview", "component": "OverviewView" }]CSPRequest
Content Security Policy określa, z jakimi zewnętrznymi domenami może łączyć się Twoja aplikacja:
{ "content_security_policy": { "connect-src": [ "https://api.tajo.io", "https://api.brevo.com" ], "image-src": [ "https://cdn.tajo.io" ], "purpose": "Connect to Tajo API for data sync and load images from CDN" }}| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
connect-src | string[] | Nie | Domeny, do których aplikacja może wysyłać żądania sieciowe |
image-src | string[] | Nie | Domeny, z których aplikacja może ładować obrazy |
purpose | string | Tak | Wyjaśnienie, dlaczego te połączenia zewnętrzne są potrzebne |
Caution
Wpisuj wyłącznie domeny, z którymi Twoja aplikacja faktycznie musi się łączyć. Nadmiar wpisów CSP może wywołać dodatkową, wnikliwszą weryfikację.
PostInstallAction
Konfiguruje to, co dzieje się bezpośrednio po zainstalowaniu aplikacji przez użytkownika:
{ "post_install_action": { "type": "onboarding" }}| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
type | string | Tak | Typ działania (zobacz poniżej) |
url | string | Warunkowo | Adres URL dla działań typu external |
Typy działań
| Typ | Zachowanie |
|---|---|
"onboarding" | Otwiera widok wdrożeniowy aplikacji w Dashboardzie |
"settings" | Otwiera widok ustawień aplikacji w Dashboardzie |
"external" | Przekierowuje użytkownika pod zewnętrzny adres URL (wymaga pola url) |
Przykłady:
// Open onboarding flow{ "post_install_action": { "type": "onboarding" }}
// Open settings page{ "post_install_action": { "type": "settings" }}
// Redirect to external setup{ "post_install_action": { "type": "external", "url": "https://app.tajo.io/stripe/setup" }}Szczegółowe wzorce implementacji znajdziesz w przewodniku po działaniach poinstalacyjnych.
Constants
Zdefiniuj statyczne pary klucz-wartość dostępne w aplikacji w czasie działania:
{ "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- Wszystkie wartości muszą być ciągami znaków
- Stałe są osadzane w aplikacji na etapie budowania
- Używaj stałych do konfiguracji, która różni się między środowiskami
- Nigdy nie przechowuj sekretów ani kluczy API jako stałych, użyj do tego Secret Store API
Dostęp do stałych w kodzie aplikacji:
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Rozszerzony manifest na potrzeby dewelopmentu
Podczas lokalnego dewelopmentu dostępne są dodatkowe pola:
{ "id": "com.tajo.brevo-integration", "version": "0.1.0", "name": "Tajo for Brevo (Dev)", "icon": "./assets/icon-dev.png", "distribution_type": "private", "sandbox_install_compatible": true, "dev": { "hot_reload": true, "port": 4242 }}Sekcja dev jest usuwana podczas budowania wersji produkcyjnej i przesyłania aplikacji. Używaj jej wyłącznie do ustawień ułatwiających pracę lokalną.
Walidacja
Zweryfikuj manifest przed przesłaniem:
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkCzęste błędy walidacji:
| Błąd | Przyczyna | Rozwiązanie |
|---|---|---|
Invalid permission | Nieznany identyfikator uprawnienia | Sprawdź Dokumentację uprawnień |
Invalid viewport | Nieznany identyfikator viewportu | Sprawdź Dokumentację viewportów |
Missing purpose | Uprawnienie bez pola purpose | Dodaj ciąg purpose do każdego uprawnienia |
Invalid version | Ciąg wersji niezgodny z semver | Użyj formatu MAJOR.MINOR.PATCH |
Icon not found | Ścieżka ikony nie działa | Sprawdź, czy plik ikony istnieje we wskazanej lokalizacji |