Подайте заявку на ранний доступ

Укажите имя, а также email или номер телефона. Мы отправим Вам информацию о доступе к Tajo.

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

Файл манифеста 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_urisstring[]НетРазрешённые URI перенаправления OAuth для процесса установки
permissionsPermissionRequest[]ДаМассив запросов разрешений
ui_extensionUIExtensionManifestНетКонфигурация UI-расширения
post_install_actionPostInstallActionНетДействие, выполняемое после установки приложения
constantsobjectНетПары «ключ, значение», доступные в приложении во время выполнения

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": {...}
}
}
ПолеТипОбязательноеОписание
viewsViewManifest[]ДаМассив объявлений представлений
content_security_policyCSPRequestНет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-srcstring[]НетДомены, к которым приложение может отправлять сетевые запросы
image-srcstring[]НетДомены, с которых приложение может загружать изображения
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-сборках и загрузке приложения. Используйте её только для удобства локальной разработки.

Валидация

Проверьте манифест перед загрузкой:

Terminal window
# Validate manifest syntax and schema
stripe apps validate
# Check for common issues
stripe apps check

Частые ошибки валидации:

ОшибкаПричинаКак исправить
Invalid permissionНеизвестный идентификатор разрешенияСверьтесь со Справочником по разрешениям
Invalid viewportНеизвестный идентификатор вьюпортаСверьтесь со Справочником по вьюпортам
Missing purposeРазрешение без поля purposeДобавьте строку purpose к каждому разрешению
Invalid versionСтрока версии не в формате semverИспользуйте формат MAJOR.MINOR.PATCH
Icon not foundПуть к иконке не разрешаетсяПроверьте, что файл иконки существует по указанному пути

Подайте заявку на ранний доступ

Укажите имя, а также email или номер телефона. Мы отправим Вам информацию о доступе к Tajo.

определим автоматически
AI-ассистент

Привет! Спрашивайте меня о документации.