On this page

App Manifest حوالہ

stripe-app.json manifest فائل آپ کی Stripe App کے لیے مرکزی کنفیگریشن ہے۔ یہ آپ کی app کی شناخت، اجازتیں، UI views، سیکیورٹی پالیسیاں اور post-install رویہ بیان کرتی ہے۔

مکمل 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"
  }
}

Schema حوالہ

اعلی سطحی Fields

فیلڈ	قسم	ضروری	تفصیل
`id`	string	ہاں	reverse domain notation میں منفرد app شناخت کنندہ (slug فارمیٹ)
`version`	string	ہاں	Semantic version string (مثلاً `"1.2.0"`)
`name`	string	ہاں	marketplace پر دکھایا جانے والا نام (زیادہ سے زیادہ 35 حروف)
`icon`	string	ہاں	app icon فائل کا relative path (300x300 PNG یا SVG)
`distribution_type`	string	ہاں	marketplace کے لیے `"public"` یا اندرونی استعمال کے لیے `"private"`
`sandbox_install_compatible`	boolean	نہیں	آیا app sandbox/test موڈ میں انسٹال ہو سکتی ہے
`stripe_api_access_type`	string	نہیں	API access طریقہ: `"oauth"` یا `"api_key"`
`allowed_redirect_uris`	string[]	نہیں	install فلو کے لیے اجازت یافتہ OAuth redirect URIs
`permissions`	PermissionRequest[]	ہاں	اجازت درخواستوں کی صف
`ui_extension`	UIExtensionManifest	نہیں	UI extension کنفیگریشن
`post_install_action`	PostInstallAction	نہیں	app انسٹالیشن کے بعد اٹھایا جانے والا عمل
`constants`	object	نہیں	runtime پر app میں قابل رسائی key-value جوڑے

id

App شناخت کنندہ ایک slug-format string ہے، عموماً reverse domain notation میں:

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

تمام Stripe Apps میں عالمی سطح پر منفرد ہونا چاہیے
صرف چھوٹے حروف، اعداد، hyphens اور dots استعمال کریں
app بننے کے بعد تبدیل نہیں کیا جا سکتا
marketplace پر app کا URL طے کرتا ہے

version

Semantic versioning کی پیروی کرتا ہے:

"version": "1.2.0"

MAJOR: Breaking تبدیلیاں یا اہم feature اضافے
MINOR: نئی خصوصیات، backward compatible
PATCH: Bug fixes اور معمولی بہتری
ہر upload کے لیے بڑھانا ضروری ہے

distribution_type

کنٹرول کرتا ہے کون آپ کی app انسٹال کر سکتا ہے:

قدر	تفصیل
`"public"`	تمام صارفین کے لیے Stripe App Marketplace پر دستیاب
`"private"`	صرف آپ کے اپنے Stripe اکاؤنٹ سے انسٹال قابل

stripe_api_access_type

تعین کرتا ہے کہ آپ کی app Stripe API سے کیسے توثیق کرتی ہے:

قدر	تفصیل
`"oauth"`	توثیق کے لیے OAuth 2.0 فلو استعمال کرتا ہے (عوامی apps کے لیے تجویز شدہ)
`"api_key"`	restricted API keys استعمال کرتا ہے (نجی apps کے لیے موزوں)

PermissionRequest

ہر اجازت درخواست ایک مخصوص Stripe API اجازت بیان کرتی ہے جو app کو چاہیے:

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

فیلڈ	قسم	ضروری	تفصیل
`permission`	string	ہاں	اجازت شناخت کنندہ (اجازتوں کا حوالہ دیکھیں)
`purpose`	string	ہاں	انسانی پڑھنے کے قابل وضاحت کہ یہ اجازت کیوں ضروری ہے

مقصد کی ہدایات:

واضح، مخصوص وضاحتیں لکھیں جو merchants سمجھ سکیں
بتائیں اجازت کس لیے استعمال کی جاتی ہے، نہ صرف یہ کیا دیتی ہے
وضاحتیں جامع رکھیں (ایک جملہ)
تکنیکی جرگن سے بچیں

UIExtensionManifest

آپ کی app کے UI اجزاء کنفیگر کرتا ہے:

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

فیلڈ	قسم	ضروری	تفصیل
`views`	ViewManifest[]	ہاں	view declarations کی صف
`content_security_policy`	CSPRequest	نہیں	بیرونی وسائل کے لیے Content Security Policy

ViewManifest

ہر view ایک React component کو ایک Stripe Dashboard viewport سے ملاتا ہے:

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

فیلڈ	قسم	ضروری	تفصیل
`viewport`	string	ہاں	Dashboard کا وہ مقام جہاں یہ view render ہوگا (Viewports حوالہ دیکھیں)
`component`	string	ہاں	render کرنے کے لیے React component کا نام (exported component نام سے مطابقت ضروری)

ایک app مختلف viewports کے لیے متعدد views بیان کر سکتی ہے:

"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 کنٹرول کرتی ہے کہ آپ کی app کون سے بیرونی domains سے connect کر سکتی ہے:

{
  "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[]	نہیں	وہ domains جن پر app network requests بھیج سکتی ہے
`image-src`	string[]	نہیں	وہ domains جن سے app تصاویر load کر سکتی ہے
`purpose`	string	ہاں	وضاحت کہ ان بیرونی connections کی ضرورت کیوں ہے

Caution

صرف وہ domains شامل کریں جن سے آپ کی app کو واقعی connect کرنے کی ضرورت ہے۔ ضرورت سے زیادہ CSP entries اضافی جائزہ جانچ پڑتال کو متحرک کر سکتی ہیں۔

PostInstallAction

کنفیگر کرتا ہے کہ صارف کے app انسٹال کرنے کے فوری بعد کیا ہوتا ہے:

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

فیلڈ	قسم	ضروری	تفصیل
`type`	string	ہاں	عمل کی قسم (نیچے دیکھیں)
`url`	string	مشروط	`external` قسم کے اعمال کے لیے URL

عمل کی اقسام

قسم	رویہ
`"onboarding"`	Dashboard میں app کا onboarding view کھولتا ہے
`"settings"`	Dashboard میں app کا settings view کھولتا ہے
`"external"`	صارف کو بیرونی URL پر redirect کرتا ہے (`url` فیلڈ ضروری)

مثالیں:

// onboarding فلو کھولیں
{
  "post_install_action": {
    "type": "onboarding"
  }
}

// settings صفحہ کھولیں
{
  "post_install_action": {
    "type": "settings"
  }
}

// بیرونی سیٹ اپ پر redirect کریں
{
  "post_install_action": {
    "type": "external",
    "url": "https://app.tajo.io/stripe/setup"
  }
}

تفصیلی نفاذ patterns کے لیے Post-Install Actions گائیڈ دیکھیں۔

Constants

runtime پر app میں قابل رسائی static key-value جوڑے تعریف کریں:

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

تمام اقدار strings ہونی چاہئیں
Constants build time پر app میں embedded ہوتے ہیں
ماحول کے درمیان مختلف ہونے والی کنفیگریشن کے لیے constants استعمال کریں
کبھی secrets یا API keys کو constants کے طور پر محفوظ نہ کریں, اس کے بجائے Secret Store API استعمال کریں

اپنے app code میں constants تک رسائی:

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

const apiUrl = constants.API_BASE_URL;

ترقی کے لیے توسیعی Manifest

لوکل ترقی کے دوران، اضافی fields دستیاب ہیں:

{
  "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 حصہ production builds اور app uploads کے دوران ہٹا دیا جاتا ہے۔ صرف لوکل ترقی کی سہولت کی ترتیبات کے لیے استعمال کریں۔

تصدیق

اپلوڈ سے پہلے manifest کی تصدیق کریں:

# manifest syntax اور schema کی تصدیق کریں
stripe apps validate

# عام مسائل چیک کریں
stripe apps check

عام تصدیق errors:

Error	وجہ	حل
`Invalid permission`	نامعلوم اجازت شناخت کنندہ	اجازتوں کا حوالہ چیک کریں
`Invalid viewport`	نامعلوم viewport شناخت کنندہ	Viewports حوالہ چیک کریں
`Missing purpose`	purpose فیلڈ کے بغیر اجازت	ہر اجازت میں purpose string شامل کریں
`Invalid version`	non-semver version string	`MAJOR.MINOR.PATCH` فارمیٹ استعمال کریں
`Icon not found`	Icon path حل نہیں ہوتا	تصدیق کریں کہ icon فائل مخصوص path پر موجود ہے