Custom App を開発・パッケージ化して公開する

開発前に接続先の提供範囲を確認する

このガイドは、Custom Apps の利用が認められたチーム向けです。まず導入担当者と、対象のワークスペース、利用者、接続するデータ、アップロード・公開の担当を決めます。管理入口が見えることだけで、すべての実行機能が利用可能とは判断しないでください。

バックエンドを持つアプリには、接続先の App Runtime 対応が必要です。ローカル開発が動くことは、接続先でアップロード・公開できる証明ではありません。以下は現行の公式スターターを使う手順です。既存アプリでは、採用中のタグ、SDK とプラットフォームの組み合わせを確認してから変更してください。

公式スターターから開発を始める

1. 公式スターターで提供タグと README を確認し、導入担当者と合意したタグを取得します。日々更新されるブランチを、そのまま本番の基準にしないでください。
2. 依存関係を導入し、プロジェクトルートで npm run dev を実行します。
3. 目的の画面、権限がない場合、データがない場合、リクエストが失敗した場合を実装・確認します。
4. npm run doctor、npm run build、npm run package の順に実行し、アップロード用 ZIP を作ります。

doctor が指摘した設定を直してから再構築します。ビルド成功と、実際のユーザー権限で正しく使えることは別の確認です。

manifest とアプリの版を区別する

manifest.json は ZIP のルート直下に置きます。entry はパッケージ内に実在する HTML の相対パスです。ZIP の外側に余分な親フォルダを作らず、スターターの package コマンドで出力してください。

バックエンドを使う場合は、処理、リソース、接続先などを使用する版の規約に沿って宣言します。完全な項目は公式 manifest の例で確認し、不要な能力をそのまま残さないでください。

PtApp の準備を待ってから利用する

アプリはプラットフォームの画面から分離された iframe 内で動作し、window.PtApp を通じてコンテキストや UI、ナビゲーションなどを利用します。親画面の DOM や非公開グローバル変数を直接操作する設計にしないでください。

オブジェクトが存在しても、橋の初期通信が終わるまで context が空の場合があります。sid や言語が必要な処理は、スターターの読み取り関数と on('context', ...) の更新を使います。初回レンダーで一度だけ空値を保存しないでください。開発用の await installDevHost() も残します。

アプリ内移動は hash ルートを用い、位置をホストに伝える場合は nav.syncRoute を使います。直接ページを更新しても、同じ詳細画面が復元されることを確認します。契約の詳細は公式の開発契約を参照してください。

データ取得と実行権限を確認する

対応する SDK とプラットフォームでは、フロントエンドから PtApp.data.query() で分析データを取得できます。context を読むだけでは分析データは得られません。使用する SDK に同梱された node_modules/@ptengine/app-sdk/data-query.llms.txt で queryType、期間、フィールドを確認してください。参照先は公式スターターの案内でも確認できます。

アセットや外部システムも、必要な能力と利用者の権限を別々に確認します。通常メンバーで実行し、権限外のデータが返らないことを確かめます。データが空なら、まず対象プロファイル、期間、実在するイベント・属性名を確認し、空をゼロの成果と断定しないでください。

バックエンドの認証を独自に省略したり、秘密情報をフロントエンドへ入れたりせず、採用したスターターの API ラッパーと認証処理を使います。必要な scope と初回認可はアクセスとデータ権限のガイドも確認してください。

ローカル確認とプラットフォーム内確認を分ける

ローカルでは npm run dev から起動します。バックエンドを使う構成で vite だけを直接起動すると、認証用の処理が揃わず、画面は表示されても API 呼び出しが失敗することがあります。

対象環境に「ローカル開発アドレス」がある場合、管理ページの対象アプリで dev server の URL を設定してからプラットフォーム内で開きます。実際のプロファイル切り替え、言語、権限、ルート復元を確認してください。設定中は本番公開版と見ている内容が異なるため、確認後は開発モードを終了します。

同僚と表示が違う場合、最初にローカル開発設定と公開中の版を照合します。別のブラウザや通常メンバーでも公開版を確認し、個人の開発画面を配布済みと報告しないでください。

アップロード前に ZIP を点検する

1. 使用していない依存や素材を整理し、秘密情報が公開産物に入っていないことを確認します。
2. フロントエンドの base: './'、manifest の場所、入口ファイルを確認します。
3. doctor と build を通し、package で ZIP を出力します。
4. ZIP を展開して構造を見直し、参照している CSS・画像・フォントが揃っているか確認します。
5. 容量・ファイル形式の制約は採用版の規約とアップロード画面で確認します。バージョンをまたいで以前の数値を固定値として使わないでください。

同じ名前の ZIP を作り直した場合も、どのソースから生成したものか、アプリ版、確認日を記録します。package 成功は公開の完了ではありません。

初めてのアプリを作成する

1. 対象プロファイルを選び、「アプリを探す → カスタムアプリ管理」を開きます。「新規」が表示されない場合は、作成権限と限定提供の対象環境を導入担当者へ確認します。
2. 「新規」を押し、利用者が識別できるアプリ名を入力します。
3. 準備済みの ZIP があれば選択します。ZIP は後からでも追加でき、名前だけで先にアプリの記録を作成できます。
4. 「アプリを作成」を押し、作成結果を確認します。ZIP を付けた場合は、下記の schema 別の処理へ続きます。
5. アプリは作成されたがアップロードに失敗した場合、一覧で既存の記録を探して再度アップロードします。同じ目的のアプリを重複作成しないでください。

記録の作成だけでは実行可能な公開版は完成しません。利用者へ案内する前に、有効な版、公開状態、共有を確認します。

対象アプリにアップロードし、公開結果を確認する

アップロードを無影響の事前検査として扱わないでください。現在の schema 1 のアップロード経路では、完了時に有効な版が切り替わります。schema 2 はバックエンドを含む専用のデプロイ画面で処理します。既存アプリの更新は、影響と確認担当を決めて進めてください。

1. 「カスタムアプリ管理」で対象アプリの詳細を開き、プロファイル、アプリ名、現在の版と公開状態を確認します。
2. 「バージョンをアップロード」から、doctor・build・package を終えた ZIP を選びます。初回作成時に ZIP を添付済みなら、そのまま表示された処理へ進みます。
3. schema 1：アップロード完了と有効な版を確認します。別の公開ボタンを押すまで無影響だとは考えないでください。
4. schema 2：「新しいバージョンをデプロイ」で、要求された設定とシークレットの確認結果を読みます。不足があれば「設定を入力」「シークレットを設定」から必要な項目を保存し、戻って再確認します。秘密情報を通常の設定欄へ入れないでください。
5. 確認が通ったら「デプロイ」を実行します。処理結果を確認し、アプリ詳細のバージョン一覧・公開状態を見直します。デプロイとアプリの公開状態は別なので、下書きや一時停止のままなら、内容確認後に画面の「公開」または「再開」を実行します。
6. 通常メンバーのアカウントで「アプリを探す」から開き、データ取得や主な操作を確認します。必要ならナビゲーションに固定します。

処理が中断され結果が不明な場合は、再実行の前に現在の版を確認します。ファイルの転送、デプロイ、公開状態、ナビゲーションへの固定は別々に確認してください。CLI の --publish も公開を伴うため、検査だけに使いません。CI は公式スターターと対象環境の手順に従います。

パッケージの検証エラーを切り分ける

エラー名は実行環境により異なる場合があります。検証を外して通すのではなく、対象フィールドを修正してください。解決しない場合はアプリ版、エラー、再現手順を添えて相談します。

白い画面・スタイル・権限の問題を切り分ける

白い画面なら、まずコンソールとリソースの 404 を確認し、相対 base と entry を照合します。構造だけ表示される場合は、Tailwind がコンポーネントライブラリの配布物を検索できるか確認します。ポップアップだけ崩れる場合は、テーマのクラスが #root ではなく html に適用されているかを確認します。

PtApp が空なら正しい起動方法と初期化待ちを確認します。API の 401/403 は認証・承認・scope を切り分けます。Runtime が未対応の環境もあるため、同じ要求の再送だけで直そうとしないでください。構築手順を変えずに、公式トラブルシューティングと doctor の指摘を照合します。

配布後の更新と引き継ぎを決める

引き継ぐものは ZIP だけではありません。ソース、依存の固定情報、使用したスターターの版、manifest、公開版、設定名と管理者、動作確認結果を記録します。秘密情報そのものは管理された設定先に保管し、手順書やチャットに書かないでください。

更新後は通常メンバーの表示、対象プロファイル、データ取得、主要操作を再確認します。アプリの一時停止、削除、外部システムの認可取消は別の操作です。公開先の復旧手順と影響範囲は、実際の提供機能を導入担当者と確認してから運用を始めます。