Poproś o wcześniejszy dostęp

Podaj imię oraz adres e-mail lub numer telefonu. Wyślemy Ci informacje o dostępie do Tajo.

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

PoleTypWymaganeOpis
idstringTakUnikalny identyfikator aplikacji w odwróconej notacji domenowej (format slug)
versionstringTakCiąg wersji semantycznej (np. "1.2.0")
namestringTakNazwa wyświetlana w marketplace (maks. 35 znaków)
iconstringTakWzględna ścieżka do pliku ikony aplikacji (PNG lub SVG 300x300)
distribution_typestringTak"public" dla marketplace lub "private" do użytku wewnętrznego
sandbox_install_compatiblebooleanNieCzy aplikację można zainstalować w trybie sandbox/testowym
stripe_api_access_typestringNieMetoda dostępu do API: "oauth" lub "api_key"
allowed_redirect_urisstring[]NieDozwolone adresy przekierowania OAuth w procesie instalacji
permissionsPermissionRequest[]TakTablica żądań uprawnień
ui_extensionUIExtensionManifestNieKonfiguracja rozszerzenia interfejsu
post_install_actionPostInstallActionNieDziałanie wykonywane po instalacji aplikacji
constantsobjectNiePary 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"
}
PoleTypWymaganeOpis
permissionstringTakIdentyfikator uprawnienia (zobacz Dokumentację uprawnień)
purposestringTakZrozumiał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": {...}
}
}
PoleTypWymaganeOpis
viewsViewManifest[]TakTablica deklaracji widoków
content_security_policyCSPRequestNieContent 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"
}
PoleTypWymaganeOpis
viewportstringTakMiejsce w Dashboardzie, w którym renderuje się ten widok (zobacz Dokumentację viewportów)
componentstringTakNazwa 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"
}
}
PoleTypWymaganeOpis
connect-srcstring[]NieDomeny, do których aplikacja może wysyłać żądania sieciowe
image-srcstring[]NieDomeny, z których aplikacja może ładować obrazy
purposestringTakWyjaś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"
}
}
PoleTypWymaganeOpis
typestringTakTyp działania (zobacz poniżej)
urlstringWarunkowoAdres URL dla działań typu external

Typy działań

TypZachowanie
"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:

Terminal window
# Validate manifest syntax and schema
stripe apps validate
# Check for common issues
stripe apps check

Częste błędy walidacji:

BłądPrzyczynaRozwiązanie
Invalid permissionNieznany identyfikator uprawnieniaSprawdź Dokumentację uprawnień
Invalid viewportNieznany identyfikator viewportuSprawdź Dokumentację viewportów
Missing purposeUprawnienie bez pola purposeDodaj ciąg purpose do każdego uprawnienia
Invalid versionCiąg wersji niezgodny z semverUżyj formatu MAJOR.MINOR.PATCH
Icon not foundŚcieżka ikony nie działaSprawdź, czy plik ikony istnieje we wskazanej lokalizacji

Poproś o wcześniejszy dostęp

Podaj imię oraz adres e-mail lub numer telefonu. Wyślemy Ci informacje o dostępie do Tajo.

rozpoznajemy automatycznie
Asystent AI

Cześć! Zapytaj mnie o dokumentację.