Tham Chiếu Viewports

Viewports định nghĩa nơi các thành phần UI của Stripe App xuất hiện trong Stripe Dashboard. Mỗi viewport tương ứng với một trang Dashboard cụ thể hoặc vị trí nơi app của bạn có thể render một view.

Cách Viewports Hoạt Động

Khi bạn khai báo một view trong app manifest, bạn ánh xạ một React component đến một viewport:

{
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.customer.detail",
        "component": "CustomerDetailView"
      }
    ]
  }
}

Component render trong app drawer (panel bên) khi người dùng điều hướng đến trang Dashboard tương ứng và mở app của bạn.

Viewports Toàn Dashboard So Với Viewport Theo Trang

Viewports Toàn Dashboard

Các viewport này có sẵn trên mọi trang của Stripe Dashboard:

Viewport ID	Mô Tả
`stripe.dashboard.drawer.default`	View drawer mặc định, có thể truy cập từ bất kỳ trang Dashboard nào qua icon app
`stripe.dashboard.home.overview`	Trang tổng quan, hiển thị trên trang landing Dashboard
`stripe.dashboard.settings`	Trang cài đặt app, có thể truy cập từ menu cài đặt của app
`stripe.dashboard.onboarding`	Luồng onboarding, hiển thị sau khi cài đặt app

Tip

Viewport drawer.default hoạt động như một fallback. Nếu người dùng mở app của bạn trên một trang mà bạn chưa khai báo viewport cụ thể, view drawer.default sẽ render thay thế.

Viewports Theo Trang

Các viewport này chỉ render khi người dùng ở trang Dashboard tương ứng:

Thanh Toán

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.payment.list`	Danh sách thanh toán	`/payments`	,
`stripe.dashboard.payment.detail`	Chi tiết thanh toán	`/payments/:id`	PaymentIntent
`stripe.dashboard.charge.detail`	Chi tiết charge	`/payments/:id` (legacy)	Charge

Khách Hàng

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.customer.list`	Danh sách khách hàng	`/customers`	,
`stripe.dashboard.customer.detail`	Chi tiết khách hàng	`/customers/:id`	Customer

Sản Phẩm & Giá

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.product.list`	Danh sách sản phẩm	`/products`	,
`stripe.dashboard.product.detail`	Chi tiết sản phẩm	`/products/:id`	Product
`stripe.dashboard.price.detail`	Chi tiết giá	`/prices/:id`	Price

Hóa Đơn

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.invoice.list`	Danh sách hóa đơn	`/invoices`	,
`stripe.dashboard.invoice.detail`	Chi tiết hóa đơn	`/invoices/:id`	Invoice

Đăng Ký

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.subscription.list`	Danh sách đăng ký	`/subscriptions`	,
`stripe.dashboard.subscription.detail`	Chi tiết đăng ký	`/subscriptions/:id`	Subscription

Checkout

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.checkout.session.list`	Danh sách Checkout Sessions	`/checkout/sessions`	,
`stripe.dashboard.checkout.session.detail`	Chi tiết Checkout Session	`/checkout/sessions/:id`	CheckoutSession
`stripe.dashboard.payment-link.list`	Danh sách Payment Links	`/payment-links`	,
`stripe.dashboard.payment-link.detail`	Chi tiết Payment Link	`/payment-links/:id`	PaymentLink

Connect

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.connect.account.list`	Danh sách tài khoản connected	`/connect/accounts`	,
`stripe.dashboard.connect.account.detail`	Chi tiết tài khoản connected	`/connect/accounts/:id`	Account
`stripe.dashboard.transfer.list`	Danh sách transfers	`/connect/transfers`	,
`stripe.dashboard.transfer.detail`	Chi tiết transfer	`/connect/transfers/:id`	Transfer

Thanh Toán Định Kỳ

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.coupon.list`	Danh sách coupon	`/coupons`	,
`stripe.dashboard.coupon.detail`	Chi tiết coupon	`/coupons/:id`	Coupon
`stripe.dashboard.quote.list`	Danh sách quotes	`/quotes`	,
`stripe.dashboard.quote.detail`	Chi tiết quote	`/quotes/:id`	Quote
`stripe.dashboard.credit-note.detail`	Chi tiết credit note	`/credit-notes/:id`	CreditNote

Payouts

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.payout.list`	Danh sách payouts	`/payouts`	,
`stripe.dashboard.payout.detail`	Chi tiết payout	`/payouts/:id`	Payout

Tranh Chấp

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.dispute.list`	Danh sách tranh chấp	`/disputes`	,
`stripe.dashboard.dispute.detail`	Chi tiết tranh chấp	`/disputes/:id`	Dispute

Terminal

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.terminal.reader.list`	Danh sách readers	`/terminal/readers`	,
`stripe.dashboard.terminal.reader.detail`	Chi tiết reader	`/terminal/readers/:id`	TerminalReader
`stripe.dashboard.terminal.location.list`	Danh sách locations	`/terminal/locations`	,
`stripe.dashboard.terminal.location.detail`	Chi tiết location	`/terminal/locations/:id`	TerminalLocation

Issuing

Viewport ID	Trang	Mẫu URL	Loại Đối Tượng
`stripe.dashboard.issuing.card.list`	Danh sách thẻ	`/issuing/cards`	,
`stripe.dashboard.issuing.card.detail`	Chi tiết thẻ	`/issuing/cards/:id`	IssuingCard
`stripe.dashboard.issuing.cardholder.list`	Danh sách chủ thẻ	`/issuing/cardholders`	,
`stripe.dashboard.issuing.cardholder.detail`	Chi tiết chủ thẻ	`/issuing/cardholders/:id`	IssuingCardholder
`stripe.dashboard.issuing.transaction.list`	Danh sách giao dịch	`/issuing/transactions`	,
`stripe.dashboard.issuing.authorization.list`	Danh sách ủy quyền	`/issuing/authorizations`	,

Truy Cập Object Context

Khi app của bạn render trong detail viewport, nó nhận đối tượng Stripe liên quan như context:

import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';

const CustomerDetailView = ({ environment }: ExtensionContextValue) => {
  const { objectContext } = environment;

  // objectContext chứa Stripe object hiện tại
  const customerId = objectContext?.id; // "cus_xxxxx"
  const customerEmail = objectContext?.email;

  return (
    <Box>
      <Inline>Customer: {customerEmail}</Inline>
      <Inline>Brevo Sync Status: checking...</Inline>
    </Box>
  );
};

List So Với Detail Context

Loại Viewport	Object Context	Trường Hợp Sử Dụng
List (vd. `customer.list`)	Không có, không có đối tượng cụ thể được chọn	Hiển thị dữ liệu tổng hợp, view tóm tắt hoặc batch actions
Detail (vd. `customer.detail`)	Đối tượng Stripe đầy đủ cho trang hiện tại	Hiển thị dữ liệu, hành động và tích hợp cụ thể cho đối tượng

Viewports Được Khuyến Nghị Cho Tích Hợp Tajo Brevo

Đối với app tích hợp Tajo Brevo, các viewport này cung cấp giá trị cao nhất:

{
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.customer.detail",
        "component": "CustomerDetailView"
      },
      {
        "viewport": "stripe.dashboard.customer.list",
        "component": "CustomerListView"
      },
      {
        "viewport": "stripe.dashboard.payment.detail",
        "component": "PaymentDetailView"
      },
      {
        "viewport": "stripe.dashboard.subscription.detail",
        "component": "SubscriptionDetailView"
      },
      {
        "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"
      }
    ]
  }
}

Component	Mục Đích
CustomerDetailView	Hiển thị thông tin contact Brevo, trạng thái sync và dữ liệu tương tác cho khách hàng cụ thể
CustomerListView	Hiển thị batch sync controls và số liệu thống kê Brevo sync tổng hợp
PaymentDetailView	Hiển thị sự kiện Brevo nào được kích hoạt bởi thanh toán này
SubscriptionDetailView	Hiển thị trạng thái automation Brevo cho đăng ký này
OverviewView	Widget trang chủ Dashboard với tình trạng sync và các số liệu Brevo chính
DrawerView	App drawer chung với các quick actions và tổng quan trạng thái
SettingsView	Cấu hình Brevo API key, tùy chọn sync và field mappings
OnboardingView	Hướng dẫn người dùng mới kết nối tài khoản Brevo của họ

Tình Trạng Sẵn Có Của Viewport

Không phải tất cả viewports đều có sẵn trong tất cả các chế độ Stripe Dashboard:

Chế Độ	Viewports Có Sẵn
Live mode	Tất cả viewports
Test mode	Tất cả viewports (sử dụng dữ liệu test)
Sandbox	Tất cả viewports (nếu `sandbox_install_compatible: true`)

Caution

Nếu manifest của bạn khai báo một viewport không tồn tại, việc upload app sẽ không vượt qua validation. Luôn xác minh các viewport ID dựa trên tham chiếu này.