> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/gaidopage/page-navigation-and-deep-links.md).

# Pageの画面遷移・ディープリンク

Pageは、Page用ホスト上の `/app/{組織ID}/{Project ID}/{Page ID}` を起点として表示されます。Page内の画面遷移は、この起点より後ろのパス、クエリ文字列、フラグメントをアプリ側で扱う設計にします。たとえば詳細画面を直接開くURLを案内したい場合、Pageの起点に続けて `/orders/42?tab=history#notes` のような画面状態を表す部分を付けます。

登録したZIPを深いパスで開いたときに、Page用ホストが常に起点ファイルを返すかは、利用条件として定められていません。クライアントルーティングだけで成立すると決めつけず、登録済みPageで直接アクセス、再読み込み、サインイン後の復帰を確認してください。

## 関連記事

* [Pageのソース構成とランタイム](/gaidopage/page-source-structure-and-runtime.md)
* [Pageのビルド・起動・表示に失敗する](/toraburushtingu/page-build-start-display-failures.md)
* [画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)
* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)

## 始める前に

* 対象の組織、Project、Page、アクセスモード、最初に案内する画面を確認します。PageのIDは表示名ではなく、Pageごとの識別子です。
* 直接開きたい画面ごとに、パス、クエリ文字列、フラグメントのどれへ状態を置くかを決めます。検索条件、編集対象、復帰先などの機密情報をURLへ含めないでください。URLは履歴、共有、アクセスログ、Refererなどに残り得ます。
* Page内のリンク、JavaScript・CSS・画像などのアセットで、ローカルの `/` 固定パスを使っていないかを見直します。Page起点のサブパスを失うと、登録後に読み込めない場合があります。

> `/app/` の後ろに置かれる組織ID、Project ID、Page IDをソースへ固定値として書き込まないでください。別のProjectへの登録、Pageの作り直し、配布先の変更で一致しなくなります。

## URLの構成とパスの決め方

通常のPage起点は次の形です。Page用ホスト名は組織・環境の設定で決まるため、例のホスト名を固定しません。

```
https://{Page用ホスト}/app/{組織ID}/{Project ID}/{Page ID}
```

Page内の画面は、起点の後ろをアプリ固有のルートとして使います。

| 用途       | URLの例                                | 扱い                                         |
| -------- | ------------------------------------ | ------------------------------------------ |
| Pageの起点  | `/app/{組織ID}/{Project ID}/{Page ID}` | 初期画面を表示します。                                |
| 詳細画面     | `…/{Page ID}/orders/42`              | `orders/42` をアプリの相対ルートとして扱います。             |
| 検索・表示条件  | `…/orders?status=open&sort=created`  | クエリ文字列を読み、値の形式と権限を検証します。                   |
| 同一画面内の位置 | `…/orders/42#notes`                  | フラグメントはブラウザ内の位置・状態に使います。サーバーへ送られる前提にはしません。 |

アセットと画面遷移の参照は、可能な限り現在のPage起点からの相対URLにします。`/assets/app.js` のようにホスト直下を指す絶対パスは、Pageの起点を失うため避けます。ビルドツールがベースパスの指定を必要とする場合は、そのツールの設定値を、登録後の実URLで確認してください。

## 1. 深い画面を開く設計にする

1. 起点を基準に、画面名と必要な識別子を相対パスで設計します。例：`orders/42`。
2. Pageの内部リンクでは、Pageの実行時起点を外さない方法を選びます。ルーターを使う場合も、開発サーバーのルートではなく、登録済みPageのURLで確認します。
3. 検索条件などをクエリ文字列へ入れる前に、URLエンコードと入力値の検証を行います。IDだけでアクセス可否を決めず、Pageが呼び出すAPIや処理側でも権限を確認します。
4. ZIPを登録後、Pageの起点から画面遷移し、同じ深いURLを別タブで直接開きます。続けてブラウザを再読み込みします。

> 存在しないパスへの応答、起点ファイルの必須性、フレームワーク別の推奨ルーターは利用条件として定められていません。直接アクセスまたは再読み込みで404、白い画面、アセット読込失敗になる場合、推測で公開せず、利用したビルドツールのサブパス設定と成果物の参照パスを確認してください。

## 2. 「サインイン必須」で復帰を確認する

「アクセス設定」の「サインイン必須」は、サインイン済みで、かつPageへのアクセス権を持つ利用者向けです。未サインインの利用者がPage用ホストの正しい `/app/{組織ID}/{Project ID}/{Page ID}/…` URLへ到達した場合、認証処理はそのURLを復帰先として扱います。復帰先はPage用ホストと同じオリジンであり、同じ組織・Project・Pageのパスであることが検証されます。

認証後は、復帰先に既にあるクエリ文字列を保ったまま認証用の情報を付けて戻ります。したがって、深いパス、クエリ文字列、フラグメントを含むURLについて、少なくとも次を受入試験に含めます。

1. サインアウト状態のブラウザで、深い画面URLを直接開きます。
2. 通常のサインインを完了します。途中で組織別のサインイン画面へ移る場合も、復帰先が失われないことを確認します。
3. 元の深い画面、クエリ文字列、フラグメントへ戻ることを確認します。
4. 対象組織・Project・Pageへの権限がない利用者では、画面が開けないことを確認します。

認証に使う値そのものをURL、画面、ログ、問い合わせに残してはいけません。Page用ホスト以外、別のPage、制御文字を含む復帰先は受け付けられません。これを理由に、Page側で任意の外部URLへ遷移させる設計にしてはいけません。

## 3. 認証期限切れ時の復帰とSDKの利用

Studio内で表示しているPageから認証更新が要求された場合、Studioは新しい認証用の情報を取得してPageを読み直します。同じPageの同一オリジン内であれば、Pageが渡したパス、クエリ文字列、フラグメントへ復帰します。外部共有URL、直接アクセス、独自の認証方式でも同じ更新方法を使えるとは限りません。

PageのブラウザコードからStudioのタスクを開くには、公開済みSDK 0.11.0のベータ`platform`モジュールを使えます。SDKを導入・ビルドする開発環境はNode.js 22以降にします。これはPRS内のブラウザ専用で、Page外では利用できないため、利用可否を確認してから呼び出します。

```ts
import { createClient } from "@japan-ai-inc/studio-sdk";

const studio = createClient({ baseUrl: "" });
const context = await studio.platform.waitForReady();

if (context) {
  const result = await studio.platform.openTask(
    [{ orderId: "42" }],
    "この注文を確認してください"
  );
  console.log(result.roomId);
}
```

`openTask()`は任意URLへの画面遷移用APIではありません。Page内の画面遷移、外部サイトへの移動、認証復帰先の指定には使いません。`platform`はベータで、Page実行環境との互換性に依存します。`@japan-ai-inc/studio-sdk@0.11.0`のように正確なバージョンを固定し、登録済みPageで確認してください。

## チェックリスト

* [ ] Page起点の `/app/{組織ID}/{Project ID}/{Page ID}` より後ろに画面ルートを設計した
* [ ] 組織ID、Project ID、Page ID、Page用ホストを成果物へ固定していない
* [ ] アセットと内部リンクを、登録後のサブパスで読み込めるようにした
* [ ] 深いURLの直接アクセスと再読み込みを、登録済みPageで確認した
* [ ] 「サインイン必須」で、サインイン後にパス・クエリ文字列・フラグメントが戻ることを確認した
* [ ] URL、ログ、問い合わせにトークン、個人情報、機密情報を残していない
* [ ] SDKの`platform`を使う場合、PRS内での利用可否と固定バージョンを確認した

## 確認できない場合

利用できるルーター、ビルドツールごとのベースパス設定、任意の深いURLに対するPage用ホストの応答は利用条件として定められていません。また、「サインイン任意」「匿名アクセス」「外部顧客認証」で「サインイン必須」と同じ認証復帰経路になるとは限りません。

直接アクセス・再読み込み・認証復帰に失敗した場合は、対象ProjectとPage名、アクセスモード、SDKバージョン、失敗したパス（認証用の値を除く）、クエリのキー名、発生日時、再現手順、ブラウザのネットワーク上の失敗を記録します。認証情報、Cookieなどの値は共有しないでください。ビルド・起動・表示の切り分けは[Pageのビルド・起動・表示に失敗する](/toraburushtingu/page-build-start-display-failures.md)を参照します。

## 次に読む記事

* [Pageのソース構成とランタイム](/gaidopage/page-source-structure-and-runtime.md)
* [Pageのビルド・起動・表示に失敗する](/toraburushtingu/page-build-start-display-failures.md)
* [画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)
* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)
