Richiedi l’accesso anticipato

Inserisci il tuo nome e un indirizzo email o un numero di telefono. Ti contatteremo con tutte le informazioni per accedere a Tajo.

In questa pagina

Riferimento del manifest dell’app

Il file manifest stripe-app.json è la configurazione centrale della tua Stripe App. Dichiara l’identità dell’app, i permessi, le view della UI, le policy di sicurezza e il comportamento successivo all’installazione.

Esempio di manifest completo

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

Riferimento dello schema

Campi di primo livello

Campo	Tipo	Obbligatorio	Descrizione
`id`	string	Sì	Identificatore univoco dell’app in notazione a dominio inverso (formato slug)
`version`	string	Sì	Stringa di versione semantica (per esempio `"1.2.0"`)
`name`	string	Sì	Nome visualizzato nel marketplace (massimo 35 caratteri)
`icon`	string	Sì	Percorso relativo al file dell’icona dell’app (PNG o SVG 300x300)
`distribution_type`	string	Sì	`"public"` per il marketplace oppure `"private"` per uso interno
`sandbox_install_compatible`	boolean	No	Indica se l’app può essere installata in modalità sandbox o test
`stripe_api_access_type`	string	No	Metodo di accesso all’API: `"oauth"` oppure `"api_key"`
`allowed_redirect_uris`	string[]	No	URI di reindirizzamento OAuth consentiti per il flusso di installazione
`permissions`	PermissionRequest[]	Sì	Array di richieste di permesso
`ui_extension`	UIExtensionManifest	No	Configurazione dell’estensione UI
`post_install_action`	PostInstallAction	No	Azione da eseguire dopo l’installazione dell’app
`constants`	object	No	Coppie chiave-valore accessibili nell’app a runtime

id

L’identificatore dell’app è una stringa in formato slug, di solito in notazione a dominio inverso:

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

Deve essere univoco a livello globale tra tutte le Stripe Apps
Usa solo lettere minuscole, numeri, trattini e punti
Non può essere modificato dopo la creazione dell’app
Determina l’URL dell’app sul marketplace

version

Segue il versionamento semantico:

"version": "1.2.0"

MAJOR: modifiche che rompono la compatibilità o aggiunte di funzionalità rilevanti
MINOR: nuove funzionalità, compatibili con le versioni precedenti
PATCH: correzioni di bug e piccoli miglioramenti
Deve essere incrementata a ogni upload

distribution_type

Controlla chi può installare la tua app:

Valore	Descrizione
`"public"`	Disponibile a tutti gli utenti sullo Stripe App Marketplace
`"private"`	Installabile solo dal tuo account Stripe

stripe_api_access_type

Determina come la tua app si autentica con l’API di Stripe:

Valore	Descrizione
`"oauth"`	Usa il flusso OAuth 2.0 per l’autenticazione (consigliato per le app pubbliche)
`"api_key"`	Usa chiavi API ristrette (adatto alle app private)

PermissionRequest

Ogni richiesta di permesso dichiara uno specifico permesso dell’API di Stripe di cui la tua app ha bisogno:

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

Campo	Tipo	Obbligatorio	Descrizione
`permission`	string	Sì	L’identificatore del permesso (vedi il Riferimento dei permessi)
`purpose`	string	Sì	Spiegazione leggibile del motivo per cui questo permesso è necessario

Linee guida per il campo purpose:

Scrivi spiegazioni chiare e specifiche, comprensibili per i merchant
Spiega a cosa serve il permesso, non solo cosa concede
Mantieni le descrizioni concise (una frase)
Evita il gergo tecnico

UIExtensionManifest

Configura i componenti UI della tua app:

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

Campo	Tipo	Obbligatorio	Descrizione
`views`	ViewManifest[]	Sì	Array di dichiarazioni di view
`content_security_policy`	CSPRequest	No	Content Security Policy per le risorse esterne

ViewManifest

Ogni view associa un componente React a un viewport della Stripe Dashboard:

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

Campo	Tipo	Obbligatorio	Descrizione
`viewport`	string	Sì	La posizione della Dashboard in cui questa view viene renderizzata (vedi il Riferimento dei viewport)
`component`	string	Sì	Nome del componente React da renderizzare (deve corrispondere al nome del componente esportato)

Una singola app può dichiarare più view per viewport diversi:

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

CSPRequest

La Content Security Policy controlla a quali domini esterni la tua app può connettersi:

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

Campo	Tipo	Obbligatorio	Descrizione
`connect-src`	string[]	No	Domini verso cui l’app può effettuare richieste di rete
`image-src`	string[]	No	Domini da cui l’app può caricare immagini
`purpose`	string	Sì	Spiegazione del motivo per cui queste connessioni esterne sono necessarie

Caution

Includi solo i domini a cui la tua app ha effettivamente bisogno di connettersi. Un numero eccessivo di voci CSP può innescare controlli più severi in fase di revisione.

PostInstallAction

Configura cosa succede subito dopo che un utente installa la tua app:

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

Campo	Tipo	Obbligatorio	Descrizione
`type`	string	Sì	Il tipo di azione (vedi sotto)
`url`	string	Condizionale	URL per le azioni di tipo `external`

Tipi di azione

Tipo	Comportamento
`"onboarding"`	Apre la view di onboarding dell’app nella Dashboard
`"settings"`	Apre la view delle impostazioni dell’app nella Dashboard
`"external"`	Reindirizza l’utente a un URL esterno (richiede il campo `url`)

Esempi:

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

Consulta la guida alle azioni post-installazione per i pattern di implementazione dettagliati.

Constants

Definisci coppie chiave-valore statiche accessibili a runtime nella tua app:

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

Tutti i valori devono essere stringhe
Le costanti vengono incorporate nell’app in fase di build
Usa le costanti per la configurazione che cambia tra gli ambienti
Non memorizzare mai segreti o chiavi API come costanti, usa invece la Secret Store API

Accedi alle costanti nel codice della tua app:

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

const apiUrl = constants.API_BASE_URL;

Manifest esteso per lo sviluppo

Durante lo sviluppo locale sono disponibili campi aggiuntivi:

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

La sezione dev viene rimossa durante le build di produzione e gli upload dell’app. Usala solo per impostazioni di comodità nello sviluppo locale.

Validazione

Valida il tuo manifest prima di caricarlo:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Errori di validazione più comuni:

Errore	Causa	Soluzione
`Invalid permission`	Identificatore di permesso sconosciuto	Controlla il Riferimento dei permessi
`Invalid viewport`	Identificatore di viewport sconosciuto	Controlla il Riferimento dei viewport
`Missing purpose`	Permesso senza il campo purpose	Aggiungi una stringa purpose a ogni permesso
`Invalid version`	Stringa di versione non conforme a semver	Usa il formato `MAJOR.MINOR.PATCH`
`Icon not found`	Il percorso dell’icona non si risolve	Verifica che il file dell’icona esista nel percorso indicato