ユースケース

小売業支援 SaaS を想定した、署名付き埋め込みの設計例です。パラメータの役割の要約は マルチテナント を、公開・設定は 署名付き埋め込み を、組み込み手順は 組み込み手順 を参照してください。

コード例は Codatum Embed SDK の README も参照してください。

シナリオ

小売業の店舗運営を支援する SaaS に、店舗ごとの売上や KPI のダッシュボードを埋め込むケースを想定します。店舗マネージャーやエリアマネージャーがログインしたとき、自分の店舗に関連する情報だけを表示します。

ノートブックのパラメータ

ソースとなるノートブックには、次のパラメータがあるものとします。パラメータ名は例です。必須の名前ではありません。

• 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 を初期値として指定します
2. フロントエンドで初期描画します
   • Embed SDK の tokenProvider の戻り値で、次のクライアントサイドパラメータを params に含める
     • date_range は相対日付の再計算のため、デフォルト値を初期値として利用する設定にする（相対日付）
     • product_category は空配列を初期値として指定します
3. ユーザーがダッシュボードを操作します
   • ユーザーは入力フォームから store_id、date_range、product_category を変更できます

設定例B: 埋め込み先アプリ側でパラメータを管理する場合

前提となるノートブックの設計

設定例A と同様です。

パラメータの設定

• tenant_id: サーバーサイドパラメータの固定値
• store_id: クライアントサイドパラメータ
• date_range: クライアントサイドパラメータ
• product_category: クライアントサイドパラメータ

表示までの流れ

1. サーバー側でトークンを発行します
   • ユーザーの所属する tenant_id を固定値として指定します
2. フロントエンドで初期描画します
   • displayOptions.hideParamsForm を有効にし、パラメータフォームを非表示にします
   • tokenProvider の戻り値で、埋め込み先アプリが管理する store_id、date_range、product_category を params に含める
3. ユーザーがダッシュボードを操作します
   • 埋め込み先アプリ側の条件変更で表示を更新する場合は、次の手順とします
   • 初期描画で使ったトークンを再利用し、更新したクライアントサイドパラメータ全件を params に含めて埋め込みを再読み込みする（reload など）
     • 差分ではなく、全件（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. フロントエンドで初期描画します
   • tokenProvider の戻り値で、次のクライアントサイドパラメータを params に含める
     • date_range は相対日付の再計算のため、デフォルト値を初期値として利用する設定にする（相対日付）
     • product_category は空配列を初期値として指定します
3. ユーザーがダッシュボードを操作します
   • store_id は固定値のため、入力フォームからは変更できません。埋め込み先アプリ側で店舗変更 UI を用意します
   • 店舗を変えて再描画する場合は、新しい store_id でトークンを再発行し、新しいトークンとクライアントサイドパラメータ全件を送る
     • 固定値の変更にはトークンの再発行が必要
     • クライアントサイドパラメータは差分ではなく全件（date_range、product_category）を送る
     • 再描画前にユーザーが変更した値を保持したい場合は、Embed SDK の paramChanged イベント（React / Vue では onParamChanged）で記録し、再送時に含める
   • date_range と product_category は、入力フォームから変更できます