Справочник за манифеста на приложението
Файлът с манифест stripe-app.json е централната конфигурация на Вашето Stripe App. Той декларира идентичността на приложението, разрешенията, изгледите на потребителския интерфейс, политиките за сигурност и поведението след инсталация.
Пълен пример за манифест
{ "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 | 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, обикновено в обратна доменна нотация:
"id": "com.tajo.brevo-integration"- Трябва да е глобално уникален за всички Stripe Apps
- Използвайте само малки букви, цифри, тирета и точки
- Не може да бъде променян след създаването на приложението
- Определя URL адреса на приложението в marketplace
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 | string | Да | Идентификаторът на разрешението (вижте Справочник за разрешенията) |
purpose | string | Да | Разбираемо за човек обяснение защо е необходимо това разрешение |
Насоки за purpose:
- Пишете ясни и конкретни обяснения, които търговците могат да разберат
- Обяснявайте за какво се използва разрешението, а не само какво дава то
- Поддържайте описанията кратки (едно изречение)
- Избягвайте технически жаргон
UIExtensionManifest
Конфигурира компонентите на потребителския интерфейс на Вашето приложение:
{ "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 | string | Да | Мястото в Dashboard, където се показва този изглед (вижте Справочник за viewports) |
component | string | Да | Име на React компонента за визуализиране (трябва да съвпада с името на експортирания компонент) |
Едно приложение може да декларира няколко изгледа за различни viewports:
"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 | string | Да | Обяснение защо са необходими тези външни връзки |
Caution
Включвайте само домейни, към които Вашето приложение действително трябва да се свързва. Прекалено многото записи в CSP може да предизвикат допълнителна проверка при прегледа.
PostInstallAction
Конфигурира какво се случва веднага след като потребител инсталира Вашето приложение:
{ "post_install_action": { "type": "onboarding" }}| Поле | Тип | Задължително | Описание |
|---|---|---|---|
type | string | Да | Типът на действието (вижте по-долу) |
url | string | По условие | 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 се премахва при производствени компилации и при качване на приложението. Използвайте я само за удобни настройки при локална разработка.
Валидация
Валидирайте манифеста си преди качване:
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkЧести грешки при валидация:
| Грешка | Причина | Решение |
|---|---|---|
Invalid permission | Непознат идентификатор на разрешение | Проверете Справочник за разрешенията |
Invalid viewport | Непознат идентификатор на viewport | Проверете Справочник за viewports |
Missing purpose | Разрешение без поле purpose | Добавете низ purpose към всяко разрешение |
Invalid version | Низ с версия, който не е semver | Използвайте формат MAJOR.MINOR.PATCH |
Icon not found | Пътят до иконата не се открива | Уверете се, че файлът с иконата съществува на посочения път |