Справочник App Manifest
Файл манифеста stripe-app.json, центральная конфигурация вашего Stripe App. В нём объявляются идентичность приложения, разрешения, UI-представления, политики безопасности и поведение после установки.
Полный пример манифеста
{ "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" }}Справочник схемы
Поля верхнего уровня
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | строка | Да | Уникальный идентификатор приложения в формате обратной доменной нотации |
version | строка | Да | Семантическая версия (например, "1.2.0") |
name | строка | Да | Отображаемое имя на маркетплейсе (макс. 35 символов) |
icon | строка | Да | Относительный путь к файлу иконки приложения (300x300 PNG или SVG) |
distribution_type | строка | Да | "public" для маркетплейса или "private" для внутреннего использования |
sandbox_install_compatible | булево | Нет | Может ли приложение устанавливаться в sandbox/тестовом режиме |
stripe_api_access_type | строка | Нет | Метод доступа к API: "oauth" или "api_key" |
allowed_redirect_uris | string[] | Нет | Разрешённые URI перенаправления OAuth для процесса установки |
permissions | PermissionRequest[] | Да | Массив запросов разрешений |
ui_extension | UIExtensionManifest | Нет | Конфигурация UI-расширения |
post_install_action | PostInstallAction | Нет | Действие после установки приложения |
constants | object | Нет | Пары ключ-значение, доступные в приложении во время выполнения |
id
"id": "com.tajo.brevo-integration"- Должен быть глобально уникальным среди всех Stripe Apps
- Используйте только строчные буквы, цифры, дефисы и точки
- Нельзя изменить после создания приложения
- Определяет URL приложения на маркетплейсе
version
Следует семантическому версионированию:
"version": "1.2.0"- MAJOR: Критические изменения или значительные новые функции
- MINOR: Новые функции, обратно совместимые
- PATCH: Исправления ошибок и незначительные улучшения
- Должна увеличиваться при каждой загрузке
distribution_type
| Значение | Описание |
|---|---|
"public" | Доступно на Stripe App Marketplace для всех пользователей |
"private" | Устанавливается только вашим собственным аккаунтом Stripe |
stripe_api_access_type
| Значение | Описание |
|---|---|
"oauth" | Использует OAuth 2.0 для аутентификации (рекомендуется для публичных приложений) |
"api_key" | Использует ограниченные API-ключи (подходит для приватных приложений) |
PermissionRequest
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
permission | строка | Да | Идентификатор разрешения (см. Справочник разрешений) |
purpose | строка | Да | Понятное объяснение, зачем нужно это разрешение |
UIExtensionManifest
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
views | ViewManifest[] | Да | Массив объявлений представлений |
content_security_policy | CSPRequest | Нет | Content Security Policy для внешних ресурсов |
ViewManifest
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
viewport | строка | Да | Место в Dashboard (см. Справочник вьюпортов) |
component | строка | Да | Имя React-компонента для рендеринга |
CSPRequest
{ "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" }}Caution
Включайте только домены, к которым приложению действительно нужен доступ. Избыточные записи CSP могут привлечь дополнительное внимание при проверке.
PostInstallAction
{ "post_install_action": { "type": "onboarding" }}Типы действий
| Тип | Поведение |
|---|---|
"onboarding" | Открывает представление онбординга приложения в Dashboard |
"settings" | Открывает представление настроек приложения в Dashboard |
"external" | Перенаправляет пользователя на внешний URL (требует поле url) |
Constants
{ "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- Все значения должны быть строками
- Constants встраиваются в приложение во время сборки
- Никогда не храните secrets или API-ключи как constants, используйте Secret Store API
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Валидация
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkРаспространённые ошибки валидации:
| Ошибка | Причина | Решение |
|---|---|---|
Invalid permission | Неизвестный идентификатор разрешения | Проверьте Справочник разрешений |
Invalid viewport | Неизвестный идентификатор вьюпорта | Проверьте Справочник вьюпортов |
Missing purpose | Разрешение без поля purpose | Добавьте строку purpose к каждому разрешению |
Invalid version | Строка версии не в формате semver | Используйте формат MAJOR.MINOR.PATCH |
Icon not found | Путь к иконке не разрешается | Убедитесь, что файл иконки существует по указанному пути |