App Manifest संदर्भ
stripe-app.json मैनिफ़ेस्ट फ़ाइल आपके Stripe App का केंद्रीय कॉन्फ़िगरेशन है. यह आपके ऐप की पहचान, अनुमतियां, UI व्यू, सुरक्षा नीतियां और इंस्टॉल के बाद का व्यवहार घोषित करती है.
पूरा मैनिफ़ेस्ट उदाहरण
{ "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 | हां | मार्केटप्लेस में दिखने वाला डिस्प्ले नाम (अधिकतम 35 वर्ण) |
icon | string | हां | ऐप आइकन फ़ाइल का सापेक्ष पाथ (300x300 PNG या SVG) |
distribution_type | string | हां | मार्केटप्लेस के लिए "public" या आंतरिक उपयोग के लिए "private" |
sandbox_install_compatible | boolean | नहीं | ऐप sandbox/test मोड में इंस्टॉल हो सकता है या नहीं |
stripe_api_access_type | string | नहीं | API एक्सेस का तरीका: "oauth" या "api_key" |
allowed_redirect_uris | string[] | नहीं | इंस्टॉल फ़्लो के लिए अनुमत OAuth रीडायरेक्ट URI |
permissions | PermissionRequest[] | हां | अनुमति अनुरोधों की सरणी |
ui_extension | UIExtensionManifest | नहीं | UI एक्सटेंशन कॉन्फ़िगरेशन |
post_install_action | PostInstallAction | नहीं | ऐप इंस्टॉल होने के बाद की जाने वाली कार्रवाई |
constants | object | नहीं | की-वैल्यू जोड़े जो रनटाइम पर ऐप में उपलब्ध रहते हैं |
id
ऐप पहचानकर्ता एक slug फ़ॉर्मेट की स्ट्रिंग है, आमतौर पर रिवर्स डोमेन नोटेशन में:
"id": "com.tajo.brevo-integration"- सभी Stripe Apps में विश्व स्तर पर यूनिक होना चाहिए
- केवल छोटे अक्षर, अंक, हाइफ़न और डॉट का उपयोग करें
- ऐप बनने के बाद इसे बदला नहीं जा सकता
- यह मार्केटप्लेस पर ऐप का URL तय करता है
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 कंपोनेंट कॉन्फ़िगर करता है:
{ "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 में वह जगह जहां यह व्यू रेंडर होता है (व्यूपोर्ट संदर्भ देखें) |
component | string | हां | रेंडर किए जाने वाले React कंपोनेंट का नाम (एक्सपोर्ट किए गए कंपोनेंट नाम से मेल खाना चाहिए) |
एक ही ऐप अलग-अलग व्यूपोर्ट के लिए कई व्यू घोषित कर सकता है:
"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 | शर्त पर निर्भर | external प्रकार की कार्रवाइयों के लिए URL |
कार्रवाई के प्रकार
| प्रकार | व्यवहार |
|---|---|
"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" }}- सभी वैल्यू स्ट्रिंग होनी चाहिए
- Constants बिल्ड के समय ऐप में एम्बेड हो जाते हैं
- ऐसे कॉन्फ़िगरेशन के लिए constants का उपयोग करें जो एनवायरनमेंट के अनुसार बदलता है
- सीक्रेट या API कुंजियां constants के रूप में कभी न रखें, इसके बजाय Secret Store API का उपयोग करें
अपने ऐप कोड में constants एक्सेस करें:
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 | अज्ञात व्यूपोर्ट पहचानकर्ता | व्यूपोर्ट संदर्भ देखें |
Missing purpose | purpose फ़ील्ड के बिना अनुमति | हर अनुमति में एक purpose स्ट्रिंग जोड़ें |
Invalid version | non-semver वर्ज़न स्ट्रिंग | MAJOR.MINOR.PATCH फ़ॉर्मेट का उपयोग करें |
Icon not found | आइकन पाथ हल नहीं होता | जांचें कि आइकन फ़ाइल बताए गए पाथ पर मौजूद है |