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

Посочете името си и имейл адрес или телефонен номер. Ще Ви изпратим информация за достъп до Tajo.

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

Файлът с манифест 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"
}
}

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

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

ПолеТипЗадължителноОписание
idstringДаУникален идентификатор на приложението в обратна доменна нотация (формат slug)
versionstringДаНиз със семантична версия (например "1.2.0")
namestringДаПоказвано име в marketplace (максимум 35 знака)
iconstringДаОтносителен път до файла с иконата на приложението (PNG или SVG с размер 300x300)
distribution_typestringДа"public" за marketplace или "private" за вътрешна употреба
sandbox_install_compatiblebooleanНеДали приложението може да се инсталира в sandbox или тестов режим
stripe_api_access_typestringНеМетод за достъп до API: "oauth" или "api_key"
allowed_redirect_urisstring[]НеРазрешени OAuth адреси за пренасочване при процеса на инсталация
permissionsPermissionRequest[]ДаМасив от заявки за разрешения
ui_extensionUIExtensionManifestНеКонфигурация на разширението на потребителския интерфейс
post_install_actionPostInstallActionНеДействие, което да се извърши след инсталация на приложението
constantsobjectНеДвойки ключ и стойност, достъпни в приложението по време на изпълнение

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"
}
ПолеТипЗадължителноОписание
permissionstringДаИдентификаторът на разрешението (вижте Справочник за разрешенията)
purposestringДаРазбираемо за човек обяснение защо е необходимо това разрешение

Насоки за purpose:

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

UIExtensionManifest

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

{
"ui_extension": {
"views": [...],
"content_security_policy": {...}
}
}
ПолеТипЗадължителноОписание
viewsViewManifest[]ДаМасив от декларации на изгледи
content_security_policyCSPRequestНеContent Security Policy за външни ресурси

ViewManifest

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

{
"viewport": "stripe.dashboard.customer.detail",
"component": "CustomerDetailView"
}
ПолеТипЗадължителноОписание
viewportstringДаМястото в Dashboard, където се показва този изглед (вижте Справочник за viewports)
componentstringДаИме на 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-srcstring[]НеДомейни, към които приложението може да прави мрежови заявки
image-srcstring[]НеДомейни, от които приложението може да зарежда изображения
purposestringДаОбяснение защо са необходими тези външни връзки

Caution

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

PostInstallAction

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

{
"post_install_action": {
"type": "onboarding"
}
}
ПолеТипЗадължителноОписание
typestringДаТипът на действието (вижте по-долу)
urlstringПо условие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 се премахва при производствени компилации и при качване на приложението. Използвайте я само за удобни настройки при локална разработка.

Валидация

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

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

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

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

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

Посочете името си и имейл адрес или телефонен номер. Ще Ви изпратим информация за достъп до Tajo.

автоматично разпознаване
AI асистент

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