> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 應用市集

> 發佈應用，讓其他 Space 可以發現並安裝。

# 應用市集

將應用發佈到應用市集，其他 Kazzle Space 就能發現並安裝它。

## 發佈的作用

發佈讓應用可被其他 Space 安裝。使用者會看到應用的名稱、副標題、圖示、發佈者和可見性，然後將其安裝到自己的 Space。發佈需要在 `kazzle.config.ts` 中設定 `subtitle` — 應用名稱下方的單行標語。

已發佈版本使用 `main` 分支上的最新提交。已發佈應用沒有單獨的發行分支。

應用定義會明確選擇點擊已安裝應用時是開啟元件、開啟嵌入式或外部 URL，還是沒有啟動介面。應用也可以要求 Kazzle 身份驗證後才能開啟，或接收生命週期 Webhook。

請參閱[發佈應用](/apps/build-and-publish)了解如何發佈應用。

## 安裝

當使用者安裝已發佈應用時，Kazzle 會在其 Space 內建立安裝記錄。安裝 Space 擁有該安裝及其相關資料。

## 使用者身份

當已登入的 Kazzle 使用者開啟已安裝應用時，Kazzle 會向應用提供目前使用者的資訊。

Kazzle 會附加短期有效的 JWT 作為持有人令牌。應用可以根據 Kazzle 的公開 JWKS 驗證令牌，以讀取使用者、Space 和安裝資訊。

令牌包含以下聲明：

| 聲明        | 含義                       |
| --------- | ------------------------ |
| `aud`     | `kazzle:app`             |
| `iss`     | `https://api.kazzle.app` |
| `sub`     | Kazzle 使用者 ID            |
| `user`    | 使用者的 `{ id, email }`     |
| `space`   | 應用安裝所在 Space 的 ID        |
| `install` | 此特定安裝的 ID                |

驗證範例：

```ts theme={"theme":"material-theme-darker"}
import { jwtVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://api.kazzle.app/auth/.well-known/jwks.json'));

async function getUserFromToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    audience: 'kazzle:app',
    issuer: 'https://api.kazzle.app',
  });
  return payload;
}
```

應用定義控制已發佈應用的啟動行為：

* `launch`：選擇 `none`、具名應用元件或具有明確嵌入式或外部目標的 URL。
* `kazzleAuth`：`required` 表示只有已登入的 Kazzle 使用者可以開啟應用；`optional` 允許在沒有 Kazzle 身份的情況下開啟應用。

## Webhook

如果應用定義包含 `webhookUrl`，Kazzle 會在應用被安裝或卸載時向其發送 HTTP POST 請求。

`app.installed` 包含發佈者後端可用於向各安裝 API 進行身份驗證的安裝金鑰：

```json theme={"theme":"material-theme-darker"}
{
  "event": "app.installed",
  "installId": "...",
  "appId": "...",
  "spaceId": "...",
  "apiUrl": "https://api.kazzle.app",
  "installKey": "kzl_inst_...",
  "user": { "id": "...", "email": "..." }
}
```

`app.uninstalled` 包含事件、安裝 ID、應用 ID、Space ID 和 API URL。發佈者應在收到此事件後停止使用安裝金鑰。

## 各安裝 API

每個安裝都可以呼叫 `https://api.kazzle.app` 上的限定範圍 API。呼叫可使用安裝金鑰（來自發佈者後端）或使用者身份令牌（來自託管 UI）進行身份驗證。所有操作都會自動限定在該安裝範圍內。

可用端點：

完整的請求和回應架構已發佈在 Kazzle OpenAPI 規格中，位址為 `https://api.kazzle.app/openapi.json`，在以下路徑下。

| 方法     | 路徑                    | 說明            |
| ------ | --------------------- | ------------- |
| GET    | `/apps/secrets`       | 列出為安裝儲存的密鑰名稱  |
| GET    | `/apps/secrets/:name` | 讀取密鑰值         |
| PUT    | `/apps/secrets/:name` | 儲存密鑰值         |
| DELETE | `/apps/secrets/:name` | 刪除密鑰          |
| GET    | `/apps/metadata`      | 讀取安裝的非密鑰中繼資料  |
| PUT    | `/apps/metadata`      | 將更新合併到安裝的中繼資料 |

透過此 API 寫入的密鑰在靜止時加密，並隔離到特定安裝。它們與儲存在 Space 保管庫中的密鑰分開。

## 後續步驟

* [發佈應用](/apps/build-and-publish) — 如何發佈應用及之後會發生什麼。