---
title: "Riferimento del manifest dell’app | Tajo"
description: "Riferimento completo dello schema del file manifest stripe-app.json usato per configurare le Stripe Apps"
url: https://tajo.io/it/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/it/docs/stripe-apps/app-manifest.md
lang: it-IT
author: "Set Noa"
author_url: https://tajo.io/it/set-noa/
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Riferimento del manifest dell’app

[Set Noa](https://tajo.io/it/set-noa/)

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.

Caution

**Stato: pianificata, non realizzata.** Tajo non ha un’app Stripe, quindi oggi nulla di questa sezione può essere installato. Gli identificatori dell’app, gli URL e le credenziali presenti in questa pagina sono segnaposto illustrativi, non endpoint reali.

## Esempio di manifest completo

```json
{
  "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": "Read 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.example.com",
        "https://api.brevo.com"
      ],
      "image-src": [
        "https://cdn.example.com",
        "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.example.com/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:

```json
"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:

```json
"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:

```json
{
  "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](https://tajo.io/it/docs/stripe-apps/permissions)) |
| `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:

```json
{
  "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:

```json
{
  "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](https://tajo.io/it/docs/stripe-apps/viewports)) |
| `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:

```json
"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:

```json
{
  "content_security_policy": {
    "connect-src": [
      "https://api.example.com",
      "https://api.brevo.com"
    ],
    "image-src": [
      "https://cdn.example.com"
    ],
    "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:

```json
{
  "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:

```json
// 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](https://tajo.io/it/docs/stripe-apps/post-install) per i pattern di implementazione dettagliati.

## Constants

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

```json
{
  "constants": {
    "API_BASE_URL": "https://api.example.com/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:

```typescript
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:

```json
{
  "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:

```bash
# 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](https://tajo.io/it/docs/stripe-apps/permissions) |
| `Invalid viewport` | Identificatore di viewport sconosciuto | Controlla il [Riferimento dei viewport](https://tajo.io/it/docs/stripe-apps/viewports) |
| `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 |