Požiadajte o skorý prístup

Uveďte svoje krstné meno a e-mailovú adresu alebo telefónne číslo. Pošleme Vám podrobnosti o prístupe k platforme Tajo.

Referencia manifestu aplikácie

Súbor manifestu stripe-app.json je centrálnou konfiguráciou Vašej aplikácie Stripe App. Deklaruje identitu aplikácie, oprávnenia, UI pohľady, bezpečnostné politiky a správanie po inštalácii.

Úplný príklad 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"
}
}

Referencia schémy

Polia najvyššej úrovne

PoleTypPovinnéPopis
idstringÁnoJedinečný identifikátor aplikácie v obrátenej doménovej notácii (formát slug)
versionstringÁnoReťazec sémantickej verzie (napríklad "1.2.0")
namestringÁnoZobrazovaný názov v marketplace (maximálne 35 znakov)
iconstringÁnoRelatívna cesta k súboru s ikonou aplikácie (300x300 PNG alebo SVG)
distribution_typestringÁno"public" pre marketplace alebo "private" pre interné použitie
sandbox_install_compatiblebooleanNieČi sa aplikácia dá nainštalovať v režime sandbox alebo test
stripe_api_access_typestringNieSpôsob prístupu k API: "oauth" alebo "api_key"
allowed_redirect_urisstring[]NiePovolené OAuth presmerovacie URI pre inštalačný postup
permissionsPermissionRequest[]ÁnoPole požiadaviek na oprávnenia
ui_extensionUIExtensionManifestNieKonfigurácia rozšírenia používateľského rozhrania
post_install_actionPostInstallActionNieAkcia, ktorá sa vykoná po inštalácii aplikácie
constantsobjectNieDvojice kľúč a hodnota dostupné v aplikácii za behu

id

Identifikátor aplikácie je reťazec vo formáte slug, zvyčajne v obrátenej doménovej notácii:

"id": "com.tajo.brevo-integration"
  • Musí byť globálne jedinečný naprieč všetkými aplikáciami Stripe Apps
  • Používajte iba malé písmená, číslice, spojovníky a bodky
  • Po vytvorení aplikácie sa už nedá zmeniť
  • Určuje URL aplikácie v marketplace

version

Riadi sa sémantickým verzovaním:

"version": "1.2.0"
  • MAJOR: nekompatibilné zmeny alebo významné rozšírenia funkcií
  • MINOR: nové funkcie, spätne kompatibilné
  • PATCH: opravy chýb a drobné vylepšenia
  • Pri každom nahratí sa musí zvýšiť

distribution_type

Určuje, kto si môže Vašu aplikáciu nainštalovať:

HodnotaPopis
"public"Dostupná všetkým používateľom v Stripe App Marketplace
"private"Nainštalovateľná iba vo Vašom vlastnom účte Stripe

stripe_api_access_type

Určuje, ako sa Vaša aplikácia autentifikuje voči Stripe API:

HodnotaPopis
"oauth"Používa postup OAuth 2.0 na autentifikáciu (odporúčané pre verejné aplikácie)
"api_key"Používa obmedzené API kľúče (vhodné pre súkromné aplikácie)

PermissionRequest

Každá požiadavka na oprávnenie deklaruje konkrétne oprávnenie Stripe API, ktoré Vaša aplikácia potrebuje:

{
"permission": "customer_read",
"purpose": "Read customer profiles to sync with Brevo contacts"
}
PoleTypPovinnéPopis
permissionstringÁnoIdentifikátor oprávnenia (pozrite Referenciu oprávnení)
purposestringÁnoĽudsky zrozumiteľné vysvetlenie, prečo je toto oprávnenie potrebné

Odporúčania pre pole purpose:

  • Píšte jasné a konkrétne vysvetlenia, ktorým obchodníci rozumejú
  • Vysvetlite, na čo sa oprávnenie používa, nielen čo umožňuje
  • Popisy udržujte stručné (jedna veta)
  • Vyhnite sa technickému žargónu

UIExtensionManifest

Konfiguruje UI komponenty Vašej aplikácie:

{
"ui_extension": {
"views": [...],
"content_security_policy": {...}
}
}
PoleTypPovinnéPopis
viewsViewManifest[]ÁnoPole deklarácií pohľadov
content_security_policyCSPRequestNieContent Security Policy pre externé zdroje

ViewManifest

Každý pohľad mapuje React komponent na viewport v Stripe Dashboarde:

{
"viewport": "stripe.dashboard.customer.detail",
"component": "CustomerDetailView"
}
PoleTypPovinnéPopis
viewportstringÁnoMiesto v Dashboarde, kde sa tento pohľad vykreslí (pozrite Referenciu viewportov)
componentstringÁnoNázov React komponentu, ktorý sa má vykresliť (musí zodpovedať názvu exportovaného komponentu)

Jediná aplikácia môže deklarovať viacero pohľadov pre rôzne viewporty:

"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 určuje, ku ktorým externým doménam sa Vaša aplikácia môže pripájať:

{
"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"
}
}
PoleTypPovinnéPopis
connect-srcstring[]NieDomény, na ktoré aplikácia môže posielať sieťové požiadavky
image-srcstring[]NieDomény, z ktorých aplikácia môže načítavať obrázky
purposestringÁnoVysvetlenie, prečo sú tieto externé spojenia potrebné

Caution

Uvádzajte iba domény, ku ktorým sa Vaša aplikácia naozaj potrebuje pripájať. Nadmerný počet položiek v CSP môže vyvolať prísnejšiu kontrolu pri posudzovaní.

PostInstallAction

Konfiguruje, čo sa stane hneď po tom, ako si používateľ nainštaluje Vašu aplikáciu:

{
"post_install_action": {
"type": "onboarding"
}
}
PoleTypPovinnéPopis
typestringÁnoTyp akcie (pozrite nižšie)
urlstringPodmieneneURL pre akcie typu external

Typy akcií

TypSprávanie
"onboarding"Otvorí onboardingový pohľad aplikácie v Dashboarde
"settings"Otvorí pohľad s nastaveniami aplikácie v Dashboarde
"external"Presmeruje používateľa na externú URL (vyžaduje pole url)

Príklady:

// 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"
}
}

Podrobné implementačné vzory nájdete v príručke k akciám po inštalácii.

Konštanty

Definujte statické dvojice kľúč a hodnota dostupné vo Vašej aplikácii za behu:

{
"constants": {
"API_BASE_URL": "https://api.tajo.io/v1",
"SYNC_INTERVAL_SECONDS": "300",
"MAX_BATCH_SIZE": "100"
}
}
  • Všetky hodnoty musia byť reťazce
  • Konštanty sa do aplikácie vkladajú pri zostavovaní
  • Konštanty používajte na konfiguráciu, ktorá sa líši medzi prostrediami
  • Nikdy neukladajte tajomstvá ani API kľúče ako konštanty, namiesto toho použite Secret Store API

Prístup ku konštantám v kóde aplikácie:

import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;

Rozšírený manifest pre vývoj

Počas lokálneho vývoja sú dostupné ďalšie polia:

{
"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
}
}

Sekcia dev sa pri produkčných zostaveniach a nahrávaní aplikácie odstraňuje. Používajte ju iba na pohodlné nastavenia počas lokálneho vývoja.

Validácia

Pred nahratím si manifest overte:

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

Bežné validačné chyby:

ChybaPríčinaRiešenie
Invalid permissionNeznámy identifikátor oprávneniaSkontrolujte Referenciu oprávnení
Invalid viewportNeznámy identifikátor viewportuSkontrolujte Referenciu viewportov
Missing purposeOprávnenie bez poľa purposeKu každému oprávneniu doplňte reťazec purpose
Invalid versionReťazec verzie, ktorý nie je semverPoužite formát MAJOR.MINOR.PATCH
Icon not foundCesta k ikone sa nedá vyhodnotiťOverte, či súbor s ikonou existuje na zadanej ceste

Požiadajte o skorý prístup

Uveďte svoje krstné meno a e-mailovú adresu alebo telefónne číslo. Pošleme Vám podrobnosti o prístupe k platforme Tajo.

automatické rozpoznanie
AI asistent

Ahoj! Opýtajte sa ma na dokumentáciu.