คู่มืออ้างอิง App Manifest
ไฟล์ manifest stripe-app.json คือศูนย์กลางการกำหนดค่าของ Stripe App ของคุณ ไฟล์นี้ประกาศตัวตนของแอป สิทธิ์การเข้าถึง มุมมอง UI นโยบายความปลอดภัย และพฤติกรรมหลังการติดตั้ง
ตัวอย่าง Manifest ฉบับเต็ม
{ "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 | ใช่ | ตัวระบุแอปที่ไม่ซ้ำกัน ในรูปแบบ reverse domain notation (รูปแบบ slug) |
version | string | ใช่ | สตริงเวอร์ชันแบบ semantic version เช่น "1.2.0" |
name | string | ใช่ | ชื่อที่แสดงในมาร์เก็ตเพลส (สูงสุด 35 ตัวอักษร) |
icon | string | ใช่ | พาธแบบสัมพัทธ์ไปยังไฟล์ไอคอนของแอป (PNG หรือ SVG ขนาด 300x300) |
distribution_type | string | ใช่ | "public" สำหรับมาร์เก็ตเพลส หรือ "private" สำหรับใช้ภายใน |
sandbox_install_compatible | boolean | ไม่ | ระบุว่าติดตั้งแอปในโหมด sandbox หรือโหมดทดสอบได้หรือไม่ |
stripe_api_access_type | string | ไม่ | วิธีเข้าถึง API: "oauth" หรือ "api_key" |
allowed_redirect_uris | string[] | ไม่ | OAuth redirect URI ที่อนุญาตสำหรับขั้นตอนการติดตั้ง |
permissions | PermissionRequest[] | ใช่ | อาร์เรย์ของคำขอสิทธิ์การเข้าถึง |
ui_extension | UIExtensionManifest | ไม่ | การกำหนดค่าส่วนขยาย UI |
post_install_action | PostInstallAction | ไม่ | การกระทำที่จะเกิดขึ้นหลังติดตั้งแอป |
constants | object | ไม่ | คู่คีย์และค่าที่แอปเข้าถึงได้ขณะทำงาน |
id
ตัวระบุแอปเป็นสตริงรูปแบบ slug โดยทั่วไปอยู่ในรูปแบบ reverse domain notation
"id": "com.tajo.brevo-integration"- ต้องไม่ซ้ำกับ Stripe App ใดในระบบทั้งหมด
- ใช้ได้เฉพาะตัวอักษรพิมพ์เล็ก ตัวเลข ยัติภังค์ และจุด
- เปลี่ยนไม่ได้หลังจากสร้างแอปแล้ว
- เป็นตัวกำหนด URL ของแอปบนมาร์เก็ตเพลส
version
ใช้รูปแบบ semantic versioning
"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 key แบบจำกัดสิทธิ์ (เหมาะกับแอปส่วนตัว) |
PermissionRequest
คำขอสิทธิ์แต่ละรายการประกาศสิทธิ์การเข้าถึง Stripe API ที่แอปของคุณต้องใช้
{ "permission": "customer_read", "purpose": "Read customer profiles to sync with Brevo contacts"}| ฟิลด์ | ชนิด | จำเป็น | คำอธิบาย |
|---|---|---|---|
permission | string | ใช่ | ตัวระบุสิทธิ์การเข้าถึง (ดู คู่มืออ้างอิงสิทธิ์การเข้าถึง) |
purpose | string | ใช่ | คำอธิบายที่มนุษย์อ่านเข้าใจได้ว่าเหตุใดจึงต้องใช้สิทธิ์นี้ |
แนวทางการเขียน purpose:
- เขียนคำอธิบายที่ชัดเจนและเฉพาะเจาะจงจนร้านค้าเข้าใจได้
- อธิบายว่าสิทธิ์นั้นถูกใช้ทำอะไร ไม่ใช่แค่บอกว่าสิทธิ์นั้นให้อะไร
- เขียนให้กระชับ ความยาวหนึ่งประโยค
- หลีกเลี่ยงศัพท์เทคนิค
UIExtensionManifest
กำหนดค่าคอมโพเนนต์ UI ของแอปคุณ
{ "ui_extension": { "views": [...], "content_security_policy": {...} }}| ฟิลด์ | ชนิด | จำเป็น | คำอธิบาย |
|---|---|---|---|
views | ViewManifest[] | ใช่ | อาร์เรย์ของการประกาศมุมมอง |
content_security_policy | CSPRequest | ไม่ | Content Security Policy สำหรับทรัพยากรภายนอก |
ViewManifest
มุมมองแต่ละรายการจับคู่คอมโพเนนต์ React เข้ากับ viewport ของ Stripe Dashboard
{ "viewport": "stripe.dashboard.customer.detail", "component": "CustomerDetailView"}| ฟิลด์ | ชนิด | จำเป็น | คำอธิบาย |
|---|---|---|---|
viewport | string | ใช่ | ตำแหน่งใน Dashboard ที่มุมมองนี้จะแสดงผล (ดู คู่มืออ้างอิง Viewport) |
component | string | ใช่ | ชื่อคอมโพเนนต์ React ที่จะแสดงผล (ต้องตรงกับชื่อคอมโพเนนต์ที่ export ไว้) |
แอปหนึ่งตัวประกาศได้หลายมุมมองสำหรับ viewport ที่ต่างกัน
"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": { "API_BASE_URL": "https://api.tajo.io/v1", "SYNC_INTERVAL_SECONDS": "300", "MAX_BATCH_SIZE": "100" }}- ค่าทั้งหมดต้องเป็นสตริง
- ค่าคงที่จะถูกฝังลงในแอปตอนบิลด์
- ใช้ค่าคงที่กับการกำหนดค่าที่ต่างกันไปในแต่ละสภาพแวดล้อม
- ห้าม เก็บข้อมูลลับหรือ API key ไว้เป็นค่าคงที่ ให้ใช้ Secret Store API แทน
เข้าถึงค่าคงที่ในโค้ดแอปของคุณ
import { constants } from '@stripe/ui-extension-sdk/constants';
const apiUrl = constants.API_BASE_URL;Manifest เพิ่มเติมสำหรับการพัฒนา
ระหว่างการพัฒนาในเครื่อง จะมีฟิลด์เพิ่มเติมให้ใช้งาน
{ "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 จะถูกตัดออกตอนบิลด์สำหรับใช้งานจริงและตอนอัปโหลดแอป ใช้ส่วนนี้กับการตั้งค่าเพื่อความสะดวกในการพัฒนาบนเครื่องเท่านั้น
การตรวจสอบความถูกต้อง
ตรวจสอบความถูกต้องของ manifest ก่อนอัปโหลด
# Validate manifest syntax and schemastripe apps validate
# Check for common issuesstripe apps checkข้อผิดพลาดที่พบบ่อยจากการตรวจสอบ
| ข้อผิดพลาด | สาเหตุ | วิธีแก้ |
|---|---|---|
Invalid permission | ตัวระบุสิทธิ์ที่ไม่รู้จัก | ตรวจสอบ คู่มืออ้างอิงสิทธิ์การเข้าถึง |
Invalid viewport | ตัวระบุ viewport ที่ไม่รู้จัก | ตรวจสอบ คู่มืออ้างอิง Viewport |
Missing purpose | สิทธิ์ที่ไม่มีฟิลด์ purpose | เพิ่มสตริง purpose ให้กับสิทธิ์ทุกรายการ |
Invalid version | สตริงเวอร์ชันที่ไม่ใช่รูปแบบ semver | ใช้รูปแบบ MAJOR.MINOR.PATCH |
Icon not found | พาธของไอคอนหาไฟล์ไม่พบ | ตรวจสอบว่ามีไฟล์ไอคอนอยู่ที่พาธที่ระบุ |