Справочник по манифесту приложения
Файл манифеста 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 | строка | Да | Уникальный идентификатор приложения в обратной доменной нотации (формат slug) |
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
Идентификатор приложения, это строка в формате slug, обычно в обратной доменной нотации:
"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
Определяет, как приложение проходит аутентификацию в Stripe API:
| Значение | Описание |
|---|---|
"oauth" | Использует поток OAuth 2.0 для аутентификации (рекомендуется для публичных приложений) |
"api_key" | Использует ограниченные API-ключи (подходит для приватных приложений) |
PermissionRequest
Каждый запрос разрешения объявляет конкретное разрешение Stripe API, которое нужно приложению:
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
permission | строка | Да | Идентификатор разрешения (см. Справочник по разрешениям) |
purpose | строка | Да | Понятное человеку объяснение, зачем нужно это разрешение |
Рекомендации по полю purpose:
- Пишите ясные и конкретные объяснения, понятные продавцу
- Объясняйте, для чего используется разрешение, а не только что оно даёт
- Формулируйте кратко (одно предложение)
- Избегайте технического жаргона
UIExtensionManifest
Настраивает UI-компоненты приложения:
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
views | ViewManifest[] | Да | Массив объявлений представлений |
content_security_policy | CSPRequest | Нет | Content Security Policy для внешних ресурсов |
ViewManifest
Каждое представление сопоставляет React-компонент с вьюпортом Stripe Dashboard:
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
viewport | строка | Да | Место в Dashboard, где отображается это представление (см. Справочник по вьюпортам) |
component | строка | Да | Имя React-компонента для отрисовки (должно совпадать с именем экспортированного компонента) |
Одно приложение может объявлять несколько представлений для разных вьюпортов:
"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 определяет, к каким внешним доменам может подключаться приложение:
{ "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" }}| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
connect-src | string[] | Нет | Домены, к которым приложение может отправлять сетевые запросы |
image-src | string[] | Нет | Домены, с которых приложение может загружать изображения |
purpose | строка | Да | Объяснение, зачем нужны эти внешние подключения |
Caution
Указывайте только те домены, которые действительно нужны приложению. Избыточные записи CSP могут привлечь дополнительное внимание при проверке.
PostInstallAction
Определяет, что происходит сразу после установки приложения пользователем:
{ "post_install_action": { "type": "onboarding" }}| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
type | строка | Да | Тип действия (см. ниже) |
url | строка | Условно | URL для действий типа external |
Типы действий
| Тип | Поведение |
|---|---|
"onboarding" | Открывает представление онбординга приложения в Dashboard |
"settings" | Открывает представление настроек приложения в Dashboard |
"external" | Перенаправляет пользователя на внешний URL (требуется поле url) |
Примеры:
// 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" }}Подробные схемы реализации описаны в руководстве по действиям после установки.
Constants
Задайте статические пары «ключ, значение», доступные в приложении во время выполнения:
{ "constants": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- Все значения должны быть строками
- Константы встраиваются в приложение на этапе сборки
- Используйте константы для конфигурации, которая различается между окружениями
- Никогда не храните секреты или API-ключи в константах, используйте вместо этого Secret Store API
Обращение к константам в коде приложения:
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Расширенный манифест для разработки
Во время локальной разработки доступны дополнительные поля:
{ "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 удаляется при production-сборках и загрузке приложения. Используйте её только для удобства локальной разработки.
Валидация
Проверьте манифест перед загрузкой:
# 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 | Путь к иконке не разрешается | Проверьте, что файл иконки существует по указанному пути |