Solicită acces anticipat

Spune-ne prenumele și o adresă de e-mail sau un număr de telefon. Îți vom trimite detaliile de acces la Tajo.

Pe această pagină

Referință pentru manifestul aplicației

Fișierul manifest stripe-app.json este configurația centrală a aplicației tale Stripe. El declară identitatea aplicației, permisiunile, vizualizările din interfață, politicile de securitate și comportamentul de după instalare.

Exemplu complet de manifest

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

Referință de schemă

Câmpuri de nivel superior

Câmp	Tip	Obligatoriu	Descriere
`id`	string	Da	Identificator unic al aplicației, în notație de domeniu inversată (format slug)
`version`	string	Da	Șir de versiune semantică (de exemplu `"1.2.0"`)
`name`	string	Da	Numele afișat în marketplace (maximum 35 de caractere)
`icon`	string	Da	Calea relativă către fișierul de pictogramă al aplicației (PNG sau SVG de 300x300)
`distribution_type`	string	Da	`"public"` pentru marketplace sau `"private"` pentru uz intern
`sandbox_install_compatible`	boolean	Nu	Dacă aplicația poate fi instalată în modul sandbox sau de test
`stripe_api_access_type`	string	Nu	Metoda de acces la API: `"oauth"` sau `"api_key"`
`allowed_redirect_uris`	string[]	Nu	URI-urile de redirecționare OAuth permise în fluxul de instalare
`permissions`	PermissionRequest[]	Da	Lista cererilor de permisiuni
`ui_extension`	UIExtensionManifest	Nu	Configurația extensiei de interfață
`post_install_action`	PostInstallAction	Nu	Acțiunea executată după instalarea aplicației
`constants`	object	Nu	Perechi cheie-valoare accesibile în aplicație la execuție

id

Identificatorul aplicației este un șir în format slug, de obicei în notație de domeniu inversată:

"id": "com.tajo.brevo-integration"

Trebuie să fie unic la nivel global, între toate aplicațiile Stripe
Folosește doar litere mici, cifre, cratime și puncte
Nu poate fi schimbat după crearea aplicației
Determină URL-ul aplicației în marketplace

version

Respectă versionarea semantică:

"version": "1.2.0"

MAJOR: modificări incompatibile sau funcționalități semnificative
MINOR: funcționalități noi, compatibile cu versiunile anterioare
PATCH: remedieri de erori și îmbunătățiri minore
Trebuie incrementată la fiecare încărcare

distribution_type

Controlează cine poate instala aplicația ta:

Valoare	Descriere
`"public"`	Disponibilă tuturor utilizatorilor în Stripe App Marketplace
`"private"`	Poate fi instalată doar de propriul tău cont Stripe

stripe_api_access_type

Determină modul în care aplicația ta se autentifică la API-ul Stripe:

Valoare	Descriere
`"oauth"`	Folosește fluxul OAuth 2.0 pentru autentificare (recomandat pentru aplicațiile publice)
`"api_key"`	Folosește chei API restricționate (potrivit pentru aplicațiile private)

PermissionRequest

Fiecare cerere de permisiune declară o anumită permisiune din API-ul Stripe de care are nevoie aplicația ta:

{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}

Câmp	Tip	Obligatoriu	Descriere
`permission`	string	Da	Identificatorul permisiunii (vezi Referința permisiunilor)
`purpose`	string	Da	Explicație pe înțelesul oamenilor pentru care este necesară această permisiune

Recomandări pentru câmpul purpose:

Scrie explicații clare și concrete, pe care comercianții le pot înțelege
Explică la ce folosești permisiunea, nu doar ce acordă ea
Păstrează descrierile scurte (o singură propoziție)
Evită jargonul tehnic

UIExtensionManifest

Configurează componentele de interfață ale aplicației tale:

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}

Câmp	Tip	Obligatoriu	Descriere
`views`	ViewManifest[]	Da	Lista declarațiilor de vizualizări
`content_security_policy`	CSPRequest	Nu	Politica de securitate a conținutului pentru resursele externe

ViewManifest

Fiecare vizualizare asociază o componentă React unui viewport din panoul de administrare Stripe:

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}

Câmp	Tip	Obligatoriu	Descriere
`viewport`	string	Da	Locul din panoul de administrare unde se afișează vizualizarea (vezi Referința viewporturilor)
`component`	string	Da	Numele componentei React care se afișează (trebuie să corespundă numelui componentei exportate)

O singură aplicație poate declara mai multe vizualizări pentru viewporturi diferite:

"views": [
  {
    "viewport": "stripe.dashboard.customer.detail",
    "component": "CustomerDetailView"
  },
  {
    "viewport": "stripe.dashboard.payment.detail",
    "component": "PaymentDetailView"
  },
  {
    "viewport": "stripe.dashboard.home.overview",
    "component": "OverviewView"
  }
]

CSPRequest

Politica de securitate a conținutului controlează domeniile externe la care se poate conecta aplicația ta:

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

Câmp	Tip	Obligatoriu	Descriere
`connect-src`	string[]	Nu	Domeniile către care aplicația poate face cereri de rețea
`image-src`	string[]	Nu	Domeniile de unde aplicația poate încărca imagini
`purpose`	string	Da	Explicația motivului pentru care sunt necesare aceste conexiuni externe

Caution

Include doar domeniile la care aplicația ta chiar are nevoie să se conecteze. Intrările CSP în exces pot atrage o verificare suplimentară la evaluare.

PostInstallAction

Configurează ce se întâmplă imediat după ce un utilizator îți instalează aplicația:

{
  "post_install_action": {
    "type": "onboarding"
  }
}

Câmp	Tip	Obligatoriu	Descriere
`type`	string	Da	Tipul acțiunii (vezi mai jos)
`url`	string	Condiționat	URL-ul pentru acțiunile de tip `external`

Tipuri de acțiuni

Tip	Comportament
`"onboarding"`	Deschide vizualizarea de inițiere a aplicației în panoul de administrare
`"settings"`	Deschide vizualizarea de setări a aplicației în panoul de administrare
`"external"`	Redirecționează utilizatorul către un URL extern (necesită câmpul `url`)

Exemple:

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

Consultă ghidul acțiunilor de după instalare pentru modele detaliate de implementare.

Constants

Definește perechi cheie-valoare statice, accesibile la execuție în aplicația ta:

{
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}

Toate valorile trebuie să fie șiruri de caractere
Constantele sunt incluse în aplicație la momentul compilării
Folosește constante pentru configurațiile care diferă între medii
Niciodată nu stoca secrete sau chei API drept constante, folosește în schimb Secret Store API

Accesează constantele în codul aplicației tale:

import { constants } from '@stripe/ui-extension-sdk/constants';

const apiUrl = constants.API_BASE_URL;

Manifest extins pentru dezvoltare

În timpul dezvoltării locale sunt disponibile câmpuri suplimentare:

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

Secțiunea dev este eliminată la compilările de producție și la încărcarea aplicației. Folosește-o doar pentru setări care ușurează dezvoltarea locală.

Validare

Validează manifestul înainte de încărcare:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Erori frecvente de validare:

Eroare	Cauză	Soluție
`Invalid permission`	Identificator de permisiune necunoscut	Verifică Referința permisiunilor
`Invalid viewport`	Identificator de viewport necunoscut	Verifică Referința viewporturilor
`Missing purpose`	Permisiune fără câmpul purpose	Adaugă un șir purpose la fiecare permisiune
`Invalid version`	Șir de versiune care nu respectă semver	Folosește formatul `MAJOR.MINOR.PATCH`
`Icon not found`	Calea pictogramei nu poate fi rezolvată	Verifică dacă fișierul de pictogramă există la calea indicată