---
title: "Dokumentacja manifestu aplikacji | Tajo"
description: "Kompletna dokumentacja schematu pliku manifestu stripe-app.json używanego do konfiguracji aplikacji Stripe Apps"
url: https://tajo.io/pl/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/pl/docs/stripe-apps/app-manifest.md
lang: pl-PL
author: "Set Noa"
author_url: https://tajo.io/pl/set-noa/
robots: noindex
---

Poproś o wcześniejszy dostęp

Podaj imię i firmowy adres e-mail. Wyślemy Ci link potwierdzający prośbę o dostęp do Tajo.

# Dokumentacja manifestu aplikacji

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

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.

Caution

**Status: planowana, niezbudowana.** Tajo nie ma aplikacji Stripe App, więc niczego z tej sekcji nie można dziś zainstalować. Identyfikatory aplikacji, adresy URL i dane dostępowe na tej stronie są przykładowymi symbolami zastępczymi, a nie działającymi endpointami.

## Pełny przykład manifestu

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

## Dokumentacja schematu

### Pola najwyższego poziomu

| Pole | Typ | Wymagane | Opis |
| --- | --- | --- | --- |
| `id` | string | Tak | Unikalny identyfikator aplikacji w odwróconej notacji domenowej (format slug) |
| `version` | string | Tak | Ciąg wersji semantycznej (np. `"1.2.0"`) |
| `name` | string | Tak | Nazwa wyświetlana w marketplace (maks. 35 znaków) |
| `icon` | string | Tak | Względna ścieżka do pliku ikony aplikacji (PNG lub SVG 300x300) |
| `distribution_type` | string | Tak | `"public"` dla marketplace lub `"private"` do użytku wewnętrznego |
| `sandbox_install_compatible` | boolean | Nie | Czy aplikację można zainstalować w trybie sandbox/testowym |
| `stripe_api_access_type` | string | Nie | Metoda dostępu do API: `"oauth"` lub `"api_key"` |
| `allowed_redirect_uris` | string\[\] | Nie | Dozwolone adresy przekierowania OAuth w procesie instalacji |
| `permissions` | PermissionRequest\[\] | Tak | Tablica żądań uprawnień |
| `ui_extension` | UIExtensionManifest | Nie | Konfiguracja rozszerzenia interfejsu |
| `post_install_action` | PostInstallAction | Nie | Działanie wykonywane po instalacji aplikacji |
| `constants` | object | Nie | Pary 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:

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

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

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

| Pole | Typ | Wymagane | Opis |
| --- | --- | --- | --- |
| `permission` | string | Tak | Identyfikator uprawnienia (zobacz [Dokumentację uprawnień](https://tajo.io/pl/docs/stripe-apps/permissions)) |
| `purpose` | string | Tak | Zrozumiał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:

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

| Pole | Typ | Wymagane | Opis |
| --- | --- | --- | --- |
| `views` | ViewManifest\[\] | Tak | Tablica deklaracji widoków |
| `content_security_policy` | CSPRequest | Nie | Content Security Policy dla zasobów zewnętrznych |

## ViewManifest

Każdy widok przypisuje komponent React do viewportu w Stripe Dashboard:

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

| Pole | Typ | Wymagane | Opis |
| --- | --- | --- | --- |
| `viewport` | string | Tak | Miejsce w Dashboardzie, w którym renderuje się ten widok (zobacz [Dokumentację viewportów](https://tajo.io/pl/docs/stripe-apps/viewports)) |
| `component` | string | Tak | Nazwa komponentu React do wyrenderowania (musi odpowiadać nazwie eksportowanego komponentu) |

Pojedyncza aplikacja może deklarować wiele widoków dla różnych viewportów:

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

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

| Pole | Typ | Wymagane | Opis |
| --- | --- | --- | --- |
| `connect-src` | string\[\] | Nie | Domeny, do których aplikacja może wysyłać żądania sieciowe |
| `image-src` | string\[\] | Nie | Domeny, z których aplikacja może ładować obrazy |
| `purpose` | string | Tak | Wyjaś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:

```json
{
  "post_install_action": {
    "type": "onboarding"
  }
}
```

| Pole | Typ | Wymagane | Opis |
| --- | --- | --- | --- |
| `type` | string | Tak | Typ działania (zobacz poniżej) |
| `url` | string | Warunkowo | Adres URL dla działań typu `external` |

### Typy działań

| Typ | Zachowanie |
| --- | --- |
| `"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:

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

Szczegółowe wzorce implementacji znajdziesz w [przewodniku po działaniach poinstalacyjnych](https://tajo.io/pl/docs/stripe-apps/post-install).

## Constants

Zdefiniuj statyczne pary klucz-wartość dostępne w aplikacji w czasie działania:

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

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

```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
  }
}
```

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:

```bash
# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check
```

Częste błędy walidacji:

| Błąd | Przyczyna | Rozwiązanie |
| --- | --- | --- |
| `Invalid permission` | Nieznany identyfikator uprawnienia | Sprawdź [Dokumentację uprawnień](https://tajo.io/pl/docs/stripe-apps/permissions) |
| `Invalid viewport` | Nieznany identyfikator viewportu | Sprawdź [Dokumentację viewportów](https://tajo.io/pl/docs/stripe-apps/viewports) |
| `Missing purpose` | Uprawnienie bez pola purpose | Dodaj ciąg purpose do każdego uprawnienia |
| `Invalid version` | Ciąg wersji niezgodny z semver | Użyj formatu `MAJOR.MINOR.PATCH` |
| `Icon not found` | Ścieżka ikony nie działa | Sprawdź, czy plik ikony istnieje we wskazanej lokalizacji |