Zaprosite za zgodnji dostop

Vnesite ime ter e-poštni naslov ali telefonsko številko. Poslali vam bomo podrobnosti o dostopu do platforme Tajo.

Na tej strani

Referenca manifesta aplikacije

Datoteka manifesta stripe-app.json je osrednja konfiguracija vaše aplikacije Stripe App. Določa identiteto aplikacije, dovoljenja, poglede vmesnika, varnostne politike in vedenje po namestitvi.

Celoten primer manifesta

{
  "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"
  }
}

Referenca sheme

Polja na najvišji ravni

Polje	Tip	Obvezno	Opis
`id`	string	Da	Enolični identifikator aplikacije v obrnjenem domenskem zapisu (oblika slug)
`version`	string	Da	Niz semantične različice (na primer `"1.2.0"`)
`name`	string	Da	Prikazno ime na tržnici (največ 35 znakov)
`icon`	string	Da	Relativna pot do datoteke z ikono aplikacije (PNG ali SVG velikosti 300x300)
`distribution_type`	string	Da	`"public"` za tržnico ali `"private"` za interno rabo
`sandbox_install_compatible`	boolean	Ne	Ali je aplikacijo mogoče namestiti v peskovniku oziroma testnem načinu
`stripe_api_access_type`	string	Ne	Način dostopa do API: `"oauth"` ali `"api_key"`
`allowed_redirect_uris`	string[]	Ne	Dovoljeni preusmeritveni naslovi OAuth za namestitveni potek
`permissions`	PermissionRequest[]	Da	Polje zahtev za dovoljenja
`ui_extension`	UIExtensionManifest	Ne	Konfiguracija razširitve vmesnika
`post_install_action`	PostInstallAction	Ne	Dejanje po namestitvi aplikacije
`constants`	object	Ne	Pari ključ-vrednost, dostopni v aplikaciji med izvajanjem

id

Identifikator aplikacije je niz v obliki slug, običajno v obrnjenem domenskem zapisu:

"id": "com.tajo.brevo-integration"

Mora biti enolični med vsemi aplikacijami Stripe Apps
Uporabljajte samo male črke, števke, vezaje in pike
Po ustvarjanju aplikacije ga ni več mogoče spremeniti
Določa naslov URL aplikacije na tržnici

version

Sledi semantičnemu določanju različic:

"version": "1.2.0"

MAJOR: nezdružljive spremembe ali obsežne nove funkcije
MINOR: nove funkcije, združljive nazaj
PATCH: odprava napak in manjše izboljšave
Ob vsakem nalaganju jo je treba povečati

distribution_type

Določa, kdo lahko namesti vašo aplikacijo:

Vrednost	Opis
`"public"`	Na voljo vsem uporabnikom na tržnici Stripe App Marketplace
`"private"`	Namestljiva samo z vašim lastnim računom Stripe

stripe_api_access_type

Določa, kako se vaša aplikacija overi pri API-ju Stripe:

Vrednost	Opis
`"oauth"`	Uporablja potek OAuth 2.0 za preverjanje pristnosti (priporočeno za javne aplikacije)
`"api_key"`	Uporablja omejene ključe API (primerno za zasebne aplikacije)

PermissionRequest

Vsaka zahteva za dovoljenje navede določeno dovoljenje za API Stripe, ki ga vaša aplikacija potrebuje:

{
  "permission": "customer_read",
  "purpose": "Read customer profiles to sync with Brevo contacts"
}

Polje	Tip	Obvezno	Opis
`permission`	string	Da	Identifikator dovoljenja (glejte referenco dovoljenj)
`purpose`	string	Da	Človeku razumljiva razlaga, zakaj je to dovoljenje potrebno

Smernice za polje purpose:

Napišite jasne in konkretne razlage, ki jih trgovci razumejo
Pojasnite, čemu je dovoljenje namenjeno, ne le kaj omogoča
Opisi naj bodo jedrnati (en stavek)
Izogibajte se tehničnemu žargonu

UIExtensionManifest

Konfigurira komponente vmesnika vaše aplikacije:

{
  "ui_extension": {
    "views": [...],
    "content_security_policy": {...}
  }
}

Polje	Tip	Obvezno	Opis
`views`	ViewManifest[]	Da	Polje deklaracij pogledov
`content_security_policy`	CSPRequest	Ne	Varnostna politika vsebine za zunanje vire

ViewManifest

Vsak pogled preslika komponento React v izsek nadzorne plošče Stripe:

{
  "viewport": "stripe.dashboard.customer.detail",
  "component": "CustomerDetailView"
}

Polje	Tip	Obvezno	Opis
`viewport`	string	Da	Mesto na nadzorni plošči, kjer se pogled izriše (glejte referenco izsekov)
`component`	string	Da	Ime komponente React za izris (ujemati se mora z imenom izvožene komponente)

Ena aplikacija lahko določi več pogledov za različne izseke:

"views": [
  {
    "viewport": "stripe.dashboard.customer.detail",
    "component": "CustomerDetailView"
  },
  {
    "viewport": "stripe.dashboard.payment.detail",
    "component": "PaymentDetailView"
  },
  {
    "viewport": "stripe.dashboard.home.overview",
    "component": "OverviewView"
  }
]

CSPRequest

Varnostna politika vsebine določa, s katerimi zunanjimi domenami se lahko vaša aplikacija poveže:

{
  "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"
  }
}

Polje	Tip	Obvezno	Opis
`connect-src`	string[]	Ne	Domene, na katere lahko aplikacija pošilja omrežne zahteve
`image-src`	string[]	Ne	Domene, s katerih lahko aplikacija nalaga slike
`purpose`	string	Da	Razlaga, zakaj so te zunanje povezave potrebne

Caution

Navedite samo domene, s katerimi se vaša aplikacija resnično mora povezati. Prevelik nabor vnosov CSP lahko sproži dodatno pregledovanje.

PostInstallAction

Konfigurira, kaj se zgodi takoj po tem, ko uporabnik namesti vašo aplikacijo:

{
  "post_install_action": {
    "type": "onboarding"
  }
}

Polje	Tip	Obvezno	Opis
`type`	string	Da	Vrsta dejanja (glejte spodaj)
`url`	string	Pogojno	Naslov URL za dejanja vrste `external`

Vrste dejanj

Vrsta	Vedenje
`"onboarding"`	Odpre uvajalni pogled aplikacije na nadzorni plošči
`"settings"`	Odpre pogled z nastavitvami aplikacije na nadzorni plošči
`"external"`	Preusmeri uporabnika na zunanji naslov URL (zahteva polje `url`)

Primeri:

// 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"
  }
}

Podrobne vzorce izvedbe najdete v vodniku po dejanjih po namestitvi.

Konstante

Določite statične pare ključ-vrednost, ki so v aplikaciji dostopni med izvajanjem:

{
  "constants": {
    "API_BASE_URL": "https://api.tajo.io/v1",
    "SYNC_INTERVAL_SECONDS": "300",
    "MAX_BATCH_SIZE": "100"
  }
}

Vse vrednosti morajo biti nizi
Konstante se v aplikacijo vgradijo med gradnjo
Konstante uporabite za konfiguracijo, ki se razlikuje med okolji
Nikoli ne shranjujte skrivnosti ali ključev API kot konstant, uporabite Secret Store API

Do konstant v kodi aplikacije dostopate takole:

import { constants } from '@stripe/ui-extension-sdk/constants';

const apiUrl = constants.API_BASE_URL;

Razširjeni manifest za razvoj

Med lokalnim razvojem so na voljo dodatna polja:

{
  "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
  }
}

Razdelek dev se med produkcijskimi gradnjami in nalaganjem aplikacije odstrani. Uporabljajte ga izključno za nastavitve, ki olajšajo lokalni razvoj.

Preverjanje

Pred nalaganjem preverite svoj manifest:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Pogoste napake pri preverjanju:

Napaka	Vzrok	Rešitev
`Invalid permission`	Neznan identifikator dovoljenja	Preverite referenco dovoljenj
`Invalid viewport`	Neznan identifikator izseka	Preverite referenco izsekov
`Missing purpose`	Dovoljenje brez polja purpose	Vsakemu dovoljenju dodajte niz purpose
`Invalid version`	Niz različice ni v obliki semver	Uporabite obliko `MAJOR.MINOR.PATCH`
`Icon not found`	Pot do ikone se ne razreši	Preverite, ali datoteka z ikono obstaja na navedeni poti