# ユースケース ## ケース: 小売業支援SaaSにおける埋め込みダッシュボードの活用 ### シナリオ 小売業の店舗運営を支援するSaaSプラットフォームにおいて、店舗ごとの売上状況やKPIを把握するためのダッシュボードをSaaS内に埋め込むニーズを想定します。 この機能により、店舗マネージャーやエリアマネージャーがログインした際、自分の店舗に関連する情報だけを表示することができます。 ### ノートブックのパラメータ 署名付き埋め込みのソースとなるノートブックには、以下のパラメータが設定されているものとします。 * `tenant_id`: * ログインしているユーザーが所属するテナントID * 「テキスト入力」型パラメータ * `store_id`: * データの表示対象となる店舗ID * 「テキスト選択」型パラメータで、 選択肢は `tenant_id` で指定されたテナント内の店舗IDを選択可能 * `date_range`: * データの集計期間 * 「日付範囲」型パラメータで、デフォルト値は相対日付で前日から7日間が指定されている * `product_category`: * データの集計対象を絞り込むための商品カテゴリ * 「テキスト複数選択」型パラメータで、未選択の場合は全ての商品カテゴリを表示するようにSQL上で条件指定している ### 設定例A: 署名付き埋め込みのフォームを利用する場合 #### 前提となるノートブックの設計 * `tenant_id` を固定することで、ユーザーがアクセス可能なデータのセキュリティを担保できている * データを抽出する際のSQLには、 `tenant_id` がフィルタ条件として必ず指定されている * 例えば、店舗データを抽出する際も、 `store_id` だけでなく `tenant_id` もフィルタ条件に指定され、テナントが異なる店舗のデータは抽出できないようになっている * `date_range` と `product_category` については、任意の値が指定可能という設計である #### パラメータの設定 * `tenant_id`: **サーバーサイドパラメータの固定値** * `store_id`: サーバサイドパラメータの初期値 * `date_range`: クライアントサイドパラメータ * `product_category`: クライアントサイドパラメータ #### 表示までの流れ 1. サーバーサイドでトークンを発行 * ユーザーの所属する `tenant_id` をサーバーサイドパラメータの固定値として指定 * `tenant_id` に紐づく `store_id` の中で、初期状態として表示する `store_id` をサーバーサイドパラメータの初期値として指定 2. フロントエンドでの初期描画処理 * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドパラメータを一緒に送信します * `date_range` は相対日付の再計算を行うため、デフォルト値にリセットするように指定 * `product_category` は空配列を初期値として指定 3. ユーザーによるダッシュボードの操作 * ユーザーは `store_id`, `date_range`, `product_category` をダッシュボードのフォーム上から変更することができます ### 設定例B: SaaS側のフロントエンドでパラメータを管理する場合 #### 前提となるノートブックの設計 「設定例A」と同様の設計とします #### パラメータの設定 * `tenant_id`: **サーバーサイドパラメータの固定値** * `store_id`: クライアントサイドパラメータ * `date_range`: クライアントサイドパラメータ * `product_category`: クライアントサイドパラメータ #### 表示までの流れ 1. サーバーサイドでトークンを発行 * ユーザーの所属する `tenant_id` をサーバーサイドパラメータの固定値として指定 2. フロントエンドでの初期描画処理 * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドオプションを一緒に送信します * パラメータはSaaS側で管理するため、パラメータフォームを非表示にするオプション(`displayOptions.hideParamsForm = true`)を指定 * `store_id`, `date_range`, `product_category` には、SaaS側で管理している値を指定します 3. ユーザーによるダッシュボードの操作 * SaaS側で管理している条件の変更等により、ダッシュボードの表示条件を変更する場合、次の手順を踏みます * 初期描画処理で利用したトークンを**再利用して**、更新されたクライアントサイドオプションと一緒に `SET_TOKEN` メッセージを再送信します * `SET_TOKEN` メッセージを再送信することで、新しく送信されたクライアントサイドオプションにより、ダッシュボードの再描画が行われます * この時に送信するクライアントサイドパラメータは、差分ではなく、全件（`store_id`, `date_range`, `product_category`）を送信する必要があります * 同一のユーザーが、同一のサーバーサイドパラメータの固定値を利用する場合、トークンの再利用が可能です（有効期限には注意してください） ### 設定例C: サーバーサイドパラメータの固定値を更新する場合 #### 前提となるノートブックの設計 * `tenant_id` と `store_id` の両方を固定することで、ユーザーがアクセス可能なデータのセキュリティを担保できている * 「設定例A」の場合と異なり、 `store_id` をサーバーサイドで固定する必要がある場合を想定します * `date_range` と `product_category` については、「設定例A」と同様に、任意の値が指定可能という設計である #### パラメータの設定 * `tenant_id`: **サーバーサイドパラメータの固定値** * `store_id`: **サーバーサイドパラメータの固定値** * `date_range`: クライアントサイドパラメータ * `product_category`: クライアントサイドパラメータ #### 表示までの流れ 1. サーバーサイドでトークンを発行 * ユーザーの所属する `tenant_id` と、初期状態として表示する `store_id` をサーバーサイドパラメータの固定値として指定 2. フロントエンドでの初期描画処理 * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドパラメータを一緒に送信します * `date_range` は相対日付の再計算を行うため、デフォルト値にリセットするように指定 * `product_category` は空配列を初期値として指定 3. ユーザーによるダッシュボードの操作 * `store_id` はサーバーサイドパラメータの固定値のため、ダッシュボード上のフォームからは変更できず、SaaS側で `store_id` を管理し、対象店舗の変更フォームを用意する必要があります * ユーザーからの操作により、 `store_id` を変更してダッシュボードを再描画する場合、次の手順を踏みます * サーバーサイドに対して、新しい `store_id` を指定して**トークンを新しく発行**し、新しいトークンとクライアントサイドパラメータを一緒に `SET_TOKEN` メッセージを送信します * サーバーサイドパラメータの固定値を変更するためには、トークンの再発行が必要となります * クライアントサイドパラメータは、差分ではなく、全件（`date_range`, `product_category`）を送信する必要があります * ユーザーの操作により変更された `date_range` や `product_category` を保持したい場合、 iframe から送信される `PARAM_CHANGED` メッセージを記録しておき、再描画時に送信するようにします * `date_range` と `product_category` については、ユーザーがダッシュボード上のフォームから表示内容を変更することができます --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.codatum.jp/sharing/signed-embed/use-case.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.