Ajukan akses awal

Masukkan nama depan serta email atau nomor telepon Anda. Kami akan menghubungi Anda dengan detail akses Tajo.

Di halaman ini

Referensi App Manifest

Berkas manifest stripe-app.json adalah konfigurasi utama untuk Stripe App Anda. Berkas ini mendeklarasikan identitas aplikasi, izin, tampilan UI, kebijakan keamanan, dan perilaku setelah pemasangan.

Contoh manifest lengkap

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

Referensi skema

Field tingkat atas

Field	Tipe	Wajib	Deskripsi
`id`	string	Ya	Identifier aplikasi yang unik dalam notasi domain terbalik (format slug)
`version`	string	Ya	String versi semantik (misalnya, `"1.2.0"`)
`name`	string	Ya	Nama tampilan yang muncul di marketplace (maksimal 35 karakter)
`icon`	string	Ya	Path relatif ke berkas ikon aplikasi (PNG atau SVG 300x300)
`distribution_type`	string	Ya	`"public"` untuk marketplace atau `"private"` untuk penggunaan internal
`sandbox_install_compatible`	boolean	Tidak	Apakah aplikasi dapat dipasang dalam mode sandbox/uji
`stripe_api_access_type`	string	Tidak	Metode akses API: `"oauth"` atau `"api_key"`
`allowed_redirect_uris`	string[]	Tidak	URI pengalihan OAuth yang diizinkan untuk alur pemasangan
`permissions`	PermissionRequest[]	Ya	Array berisi permintaan izin
`ui_extension`	UIExtensionManifest	Tidak	Konfigurasi ekstensi UI
`post_install_action`	PostInstallAction	Tidak	Tindakan yang dilakukan setelah aplikasi dipasang
`constants`	object	Tidak	Pasangan kunci-nilai yang dapat diakses aplikasi saat runtime

id

Identifier aplikasi adalah string berformat slug, biasanya dalam notasi domain terbalik:

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

Harus unik secara global di seluruh Stripe Apps
Gunakan hanya huruf kecil, angka, tanda hubung, dan titik
Tidak dapat diubah setelah aplikasi dibuat
Menentukan URL aplikasi di marketplace

version

Mengikuti versi semantik:

"version": "1.2.0"

MAJOR: Perubahan yang merusak kompatibilitas atau penambahan fitur besar
MINOR: Fitur baru, tetap kompatibel dengan versi sebelumnya
PATCH: Perbaikan bug dan peningkatan kecil
Harus dinaikkan pada setiap unggahan

distribution_type

Mengontrol siapa yang dapat memasang aplikasi Anda:

Nilai	Deskripsi
`"public"`	Tersedia di Stripe App Marketplace untuk semua pengguna
`"private"`	Hanya dapat dipasang oleh akun Stripe Anda sendiri

stripe_api_access_type

Menentukan cara aplikasi Anda melakukan autentikasi dengan Stripe API:

Nilai	Deskripsi
`"oauth"`	Menggunakan alur OAuth 2.0 untuk autentikasi (disarankan untuk aplikasi publik)
`"api_key"`	Menggunakan API key terbatas (cocok untuk aplikasi privat)

PermissionRequest

Setiap permintaan izin mendeklarasikan satu izin Stripe API tertentu yang dibutuhkan aplikasi Anda:

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

Field	Tipe	Wajib	Deskripsi
`permission`	string	Ya	Identifier izin (lihat Referensi Izin)
`purpose`	string	Ya	Penjelasan yang dapat dibaca manusia tentang mengapa izin ini dibutuhkan

Panduan penulisan purpose:

Tulis penjelasan yang jelas dan spesifik agar dapat dipahami merchant
Jelaskan untuk apa izin tersebut digunakan, bukan sekadar apa yang diberikannya
Buat deskripsi tetap ringkas (satu kalimat)
Hindari jargon teknis

UIExtensionManifest

Mengonfigurasi komponen UI aplikasi Anda:

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

Field	Tipe	Wajib	Deskripsi
`views`	ViewManifest[]	Ya	Array berisi deklarasi tampilan
`content_security_policy`	CSPRequest	Tidak	Content Security Policy untuk sumber daya eksternal

ViewManifest

Setiap tampilan memetakan sebuah komponen React ke viewport Stripe Dashboard:

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

Field	Tipe	Wajib	Deskripsi
`viewport`	string	Ya	Lokasi di Dashboard tempat tampilan ini dirender (lihat Referensi Viewport)
`component`	string	Ya	Nama komponen React yang akan dirender (harus sama dengan nama komponen yang diekspor)

Satu aplikasi dapat mendeklarasikan beberapa tampilan untuk viewport yang berbeda:

"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 mengontrol domain eksternal mana yang dapat dihubungi aplikasi Anda:

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

Field	Tipe	Wajib	Deskripsi
`connect-src`	string[]	Tidak	Domain yang boleh menerima permintaan jaringan dari aplikasi
`image-src`	string[]	Tidak	Domain tempat aplikasi boleh memuat gambar
`purpose`	string	Ya	Penjelasan mengapa koneksi eksternal ini dibutuhkan

Caution

Sertakan hanya domain yang benar-benar perlu dihubungi aplikasi Anda. Entri CSP yang berlebihan dapat memicu peninjauan tambahan yang lebih ketat.

PostInstallAction

Mengonfigurasi apa yang terjadi segera setelah pengguna memasang aplikasi Anda:

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

Field	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tipe tindakan (lihat di bawah)
`url`	string	Kondisional	URL untuk tindakan bertipe `external`

Tipe tindakan

Tipe	Perilaku
`"onboarding"`	Membuka tampilan onboarding aplikasi di Dashboard
`"settings"`	Membuka tampilan pengaturan aplikasi di Dashboard
`"external"`	Mengalihkan pengguna ke URL eksternal (membutuhkan field `url`)

Contoh:

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

Lihat panduan Post-Install Action untuk pola implementasi yang lebih rinci.

Constants

Definisikan pasangan kunci-nilai statis yang dapat diakses saat runtime di aplikasi Anda:

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

Semua nilai harus berupa string
Constant disematkan ke dalam aplikasi saat proses build
Gunakan constant untuk konfigurasi yang berbeda antar-lingkungan
Jangan pernah menyimpan secret atau API key sebagai constant, gunakan Secret Store API sebagai gantinya

Mengakses constant di dalam kode aplikasi Anda:

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

const apiUrl = constants.API_BASE_URL;

Manifest tambahan untuk pengembangan

Selama pengembangan lokal, tersedia field tambahan:

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

Bagian dev dihapus saat build produksi dan saat aplikasi diunggah. Gunakan bagian ini hanya untuk pengaturan kenyamanan pengembangan lokal.

Validasi

Validasi manifest Anda sebelum mengunggahnya:

# Validate manifest syntax and schema
stripe apps validate

# Check for common issues
stripe apps check

Galat validasi yang umum:

Galat	Penyebab	Perbaikan
`Invalid permission`	Identifier izin tidak dikenal	Periksa Referensi Izin
`Invalid viewport`	Identifier viewport tidak dikenal	Periksa Referensi Viewport
`Missing purpose`	Izin tanpa field purpose	Tambahkan string purpose pada setiap izin
`Invalid version`	String versi bukan semver	Gunakan format `MAJOR.MINOR.PATCH`
`Icon not found`	Path ikon tidak dapat ditemukan	Pastikan berkas ikon ada di path yang ditentukan