ขอสิทธิ์ใช้งานล่วงหน้า

กรอกชื่อพร้อมอีเมลหรือหมายเลขโทรศัพท์ แล้วเราจะติดต่อกลับพร้อมรายละเอียดการเข้าใช้งาน Tajo

คู่มืออ้างอิง 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"
}
}

คู่มืออ้างอิงสคีมา

ฟิลด์ระดับบนสุด

ฟิลด์ชนิดจำเป็นคำอธิบาย
idstringใช่ตัวระบุแอปที่ไม่ซ้ำกัน ในรูปแบบ reverse domain notation (รูปแบบ slug)
versionstringใช่สตริงเวอร์ชันแบบ semantic version เช่น "1.2.0"
namestringใช่ชื่อที่แสดงในมาร์เก็ตเพลส (สูงสุด 35 ตัวอักษร)
iconstringใช่พาธแบบสัมพัทธ์ไปยังไฟล์ไอคอนของแอป (PNG หรือ SVG ขนาด 300x300)
distribution_typestringใช่"public" สำหรับมาร์เก็ตเพลส หรือ "private" สำหรับใช้ภายใน
sandbox_install_compatiblebooleanไม่ระบุว่าติดตั้งแอปในโหมด sandbox หรือโหมดทดสอบได้หรือไม่
stripe_api_access_typestringไม่วิธีเข้าถึง API: "oauth" หรือ "api_key"
allowed_redirect_urisstring[]ไม่OAuth redirect URI ที่อนุญาตสำหรับขั้นตอนการติดตั้ง
permissionsPermissionRequest[]ใช่อาร์เรย์ของคำขอสิทธิ์การเข้าถึง
ui_extensionUIExtensionManifestไม่การกำหนดค่าส่วนขยาย UI
post_install_actionPostInstallActionไม่การกระทำที่จะเกิดขึ้นหลังติดตั้งแอป
constantsobjectไม่คู่คีย์และค่าที่แอปเข้าถึงได้ขณะทำงาน

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"
}
ฟิลด์ชนิดจำเป็นคำอธิบาย
permissionstringใช่ตัวระบุสิทธิ์การเข้าถึง (ดู คู่มืออ้างอิงสิทธิ์การเข้าถึง)
purposestringใช่คำอธิบายที่มนุษย์อ่านเข้าใจได้ว่าเหตุใดจึงต้องใช้สิทธิ์นี้

แนวทางการเขียน purpose:

  • เขียนคำอธิบายที่ชัดเจนและเฉพาะเจาะจงจนร้านค้าเข้าใจได้
  • อธิบายว่าสิทธิ์นั้นถูกใช้ทำอะไร ไม่ใช่แค่บอกว่าสิทธิ์นั้นให้อะไร
  • เขียนให้กระชับ ความยาวหนึ่งประโยค
  • หลีกเลี่ยงศัพท์เทคนิค

UIExtensionManifest

กำหนดค่าคอมโพเนนต์ UI ของแอปคุณ

{
"ui_extension": {
"views": [...],
"content_security_policy": {...}
}
}
ฟิลด์ชนิดจำเป็นคำอธิบาย
viewsViewManifest[]ใช่อาร์เรย์ของการประกาศมุมมอง
content_security_policyCSPRequestไม่Content Security Policy สำหรับทรัพยากรภายนอก

ViewManifest

มุมมองแต่ละรายการจับคู่คอมโพเนนต์ React เข้ากับ viewport ของ Stripe Dashboard

{
"viewport": "stripe.dashboard.customer.detail",
"component": "CustomerDetailView"
}
ฟิลด์ชนิดจำเป็นคำอธิบาย
viewportstringใช่ตำแหน่งใน Dashboard ที่มุมมองนี้จะแสดงผล (ดู คู่มืออ้างอิง Viewport)
componentstringใช่ชื่อคอมโพเนนต์ 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-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": {
"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 ก่อนอัปโหลด

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

ข้อผิดพลาดที่พบบ่อยจากการตรวจสอบ

ข้อผิดพลาดสาเหตุวิธีแก้
Invalid permissionตัวระบุสิทธิ์ที่ไม่รู้จักตรวจสอบ คู่มืออ้างอิงสิทธิ์การเข้าถึง
Invalid viewportตัวระบุ viewport ที่ไม่รู้จักตรวจสอบ คู่มืออ้างอิง Viewport
Missing purposeสิทธิ์ที่ไม่มีฟิลด์ purposeเพิ่มสตริง purpose ให้กับสิทธิ์ทุกรายการ
Invalid versionสตริงเวอร์ชันที่ไม่ใช่รูปแบบ semverใช้รูปแบบ MAJOR.MINOR.PATCH
Icon not foundพาธของไอคอนหาไฟล์ไม่พบตรวจสอบว่ามีไฟล์ไอคอนอยู่ที่พาธที่ระบุ

ขอสิทธิ์ใช้งานล่วงหน้า

กรอกชื่อพร้อมอีเมลหรือหมายเลขโทรศัพท์ แล้วเราจะติดต่อกลับพร้อมรายละเอียดการเข้าใช้งาน Tajo

ตรวจจับอัตโนมัติ
ผู้ช่วย AI

สวัสดี! ถามฉันเกี่ยวกับเอกสารได้เลย