---
title: "Справочник за манифеста на приложението | Tajo"
description: "Пълен справочник за схемата на файла stripe-app.json, използван за конфигуриране на Stripe Apps"
url: https://tajo.io/bg/docs/stripe-apps/app-manifest/
markdown: https://tajo.io/bg/docs/stripe-apps/app-manifest.md
lang: bg-BG
author: "Set Noa"
author_url: https://tajo.io/bg/set-noa/
robots: noindex
---

Заявете ранен достъп

Въведете собственото си име и служебен имейл адрес. Ще ви изпратим връзка за потвърждение на заявката за достъп до Tajo.

# Справочник за манифеста на приложението

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

Файлът с манифест `stripe-app.json` е централната конфигурация на Вашето Stripe App. Той декларира идентичността на приложението, разрешенията, изгледите на потребителския интерфейс, политиките за сигурност и поведението след инсталация.

Caution

**Статус: планирано, не е изградено.** Tajo няма приложение за Stripe, така че нищо в този раздел не може да бъде инсталирано днес. Идентификаторите на приложения, адресите и идентификационните данни на тази страница са илюстративни примери, а не действащи крайни точки.

## Пълен пример за манифест

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

## Справочник за схемата

### Полета от най-горно ниво

| Поле | Тип | Задължително | Описание |
| --- | --- | --- | --- |
| `id` | string | Да | Уникален идентификатор на приложението в обратна доменна нотация (формат slug) |
| `version` | string | Да | Низ със семантична версия (например `"1.2.0"`) |
| `name` | string | Да | Показвано име в marketplace (максимум 35 знака) |
| `icon` | string | Да | Относителен път до файла с иконата на приложението (PNG или SVG с размер 300x300) |
| `distribution_type` | string | Да | `"public"` за marketplace или `"private"` за вътрешна употреба |
| `sandbox_install_compatible` | boolean | Не | Дали приложението може да се инсталира в sandbox или тестов режим |
| `stripe_api_access_type` | string | Не | Метод за достъп до API: `"oauth"` или `"api_key"` |
| `allowed_redirect_uris` | string\[\] | Не | Разрешени OAuth адреси за пренасочване при процеса на инсталация |
| `permissions` | PermissionRequest\[\] | Да | Масив от заявки за разрешения |
| `ui_extension` | UIExtensionManifest | Не | Конфигурация на разширението на потребителския интерфейс |
| `post_install_action` | PostInstallAction | Не | Действие, което да се извърши след инсталация на приложението |
| `constants` | object | Не | Двойки ключ и стойност, достъпни в приложението по време на изпълнение |

### id

Идентификаторът на приложението е низ във формат slug, обикновено в обратна доменна нотация:

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

- Трябва да е глобално уникален за всички Stripe Apps
- Използвайте само малки букви, цифри, тирета и точки
- Не може да бъде променян след създаването на приложението
- Определя URL адреса на приложението в marketplace

### version

Следва семантичното версиониране:

```json
"version": "1.2.0"
```

- **MAJOR**: несъвместими промени или значителни нови функции
- **MINOR**: нови функции, съвместими с предишни версии
- **PATCH**: поправки на грешки и дребни подобрения
- Трябва да се увеличава при всяко качване

### distribution\_type

Управлява кой може да инсталира Вашето приложение:

| Стойност | Описание |
| --- | --- |
| `"public"` | Достъпно в Stripe App Marketplace за всички потребители |
| `"private"` | Може да се инсталира само от Вашия собствен Stripe акаунт |

### stripe\_api\_access\_type

Определя как Вашето приложение се удостоверява пред Stripe API:

| Стойност | Описание |
| --- | --- |
| `"oauth"` | Използва OAuth 2.0 за удостоверяване (препоръчително за публични приложения) |
| `"api_key"` | Използва ограничени API ключове (подходящо за частни приложения) |

## PermissionRequest

Всяка заявка за разрешение декларира конкретно разрешение за Stripe API, от което Вашето приложение се нуждае:

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

| Поле | Тип | Задължително | Описание |
| --- | --- | --- | --- |
| `permission` | string | Да | Идентификаторът на разрешението (вижте [Справочник за разрешенията](https://tajo.io/bg/docs/stripe-apps/permissions)) |
| `purpose` | string | Да | Разбираемо за човек обяснение защо е необходимо това разрешение |

**Насоки за purpose:**

- Пишете ясни и конкретни обяснения, които търговците могат да разберат
- Обяснявайте за какво се използва разрешението, а не само какво дава то
- Поддържайте описанията кратки (едно изречение)
- Избягвайте технически жаргон

## UIExtensionManifest

Конфигурира компонентите на потребителския интерфейс на Вашето приложение:

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

| Поле | Тип | Задължително | Описание |
| --- | --- | --- | --- |
| `views` | ViewManifest\[\] | Да | Масив от декларации на изгледи |
| `content_security_policy` | CSPRequest | Не | Content Security Policy за външни ресурси |

## ViewManifest

Всеки изглед свързва React компонент с област от Stripe Dashboard:

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

| Поле | Тип | Задължително | Описание |
| --- | --- | --- | --- |
| `viewport` | string | Да | Мястото в Dashboard, където се показва този изглед (вижте [Справочник за viewports](https://tajo.io/bg/docs/stripe-apps/viewports)) |
| `component` | string | Да | Име на React компонента за визуализиране (трябва да съвпада с името на експортирания компонент) |

Едно приложение може да декларира няколко изгледа за различни viewports:

```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 определя към кои външни домейни Вашето приложение може да се свързва:

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

| Поле | Тип | Задължително | Описание |
| --- | --- | --- | --- |
| `connect-src` | string\[\] | Не | Домейни, към които приложението може да прави мрежови заявки |
| `image-src` | string\[\] | Не | Домейни, от които приложението може да зарежда изображения |
| `purpose` | string | Да | Обяснение защо са необходими тези външни връзки |

Caution

Включвайте само домейни, към които Вашето приложение действително трябва да се свързва. Прекалено многото записи в CSP може да предизвикат допълнителна проверка при прегледа.

## PostInstallAction

Конфигурира какво се случва веднага след като потребител инсталира Вашето приложение:

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

| Поле | Тип | Задължително | Описание |
| --- | --- | --- | --- |
| `type` | string | Да | Типът на действието (вижте по-долу) |
| `url` | string | По условие | URL адрес за действия от тип `external` |

### Типове действия

| Тип | Поведение |
| --- | --- |
| `"onboarding"` | Отваря изгледа за въвеждане в работа на приложението в Dashboard |
| `"settings"` | Отваря изгледа с настройките на приложението в Dashboard |
| `"external"` | Пренасочва потребителя към външен URL адрес (изисква поле `url`) |

Примери:

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

Вижте [ръководството за действия след инсталация](https://tajo.io/bg/docs/stripe-apps/post-install) за подробни модели на внедряване.

## Constants

Дефинирайте статични двойки ключ и стойност, достъпни по време на изпълнение във Вашето приложение:

```json
{
  "constants": {
    "API_BASE_URL": "https://api.example.com/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}
```

- Всички стойности трябва да са низове
- Константите се вграждат в приложението по време на компилация
- Използвайте константи за конфигурация, която се различава между средите
- **Никога** не съхранявайте тайни или API ключове като константи, вместо това използвайте Secret Store API

Достъп до константите в кода на Вашето приложение:

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

const apiUrl = constants.API_BASE_URL;
```

## Разширен манифест за разработка

По време на локална разработка са налични допълнителни полета:

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

Секцията `dev` се премахва при производствени компилации и при качване на приложението. Използвайте я само за удобни настройки при локална разработка.

## Валидация

Валидирайте манифеста си преди качване:

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

# Check for common issues
stripe apps check
```

Чести грешки при валидация:

| Грешка | Причина | Решение |
| --- | --- | --- |
| `Invalid permission` | Непознат идентификатор на разрешение | Проверете [Справочник за разрешенията](https://tajo.io/bg/docs/stripe-apps/permissions) |
| `Invalid viewport` | Непознат идентификатор на viewport | Проверете [Справочник за viewports](https://tajo.io/bg/docs/stripe-apps/viewports) |
| `Missing purpose` | Разрешение без поле purpose | Добавете низ purpose към всяко разрешение |
| `Invalid version` | Низ с версия, който не е semver | Използвайте формат `MAJOR.MINOR.PATCH` |
| `Icon not found` | Пътят до иконата не се открива | Уверете се, че файлът с иконата съществува на посочения път |