パラメータ仕様

サーバーサイドパラメータとクライアントサイドパラメータの詳細仕様

署名付き埋め込みにおけるパラメータの動作とその制御方法について詳しく説明します。

パラメータの種類と動作

Signed Embedでは、パラメータの制御方法により3つの種類に分類されます。埋め込みを行う実装者は、それぞれの特性を理解して適切に選択する必要があります。

サーバーサイド固定値 (FIXED)

• 設定場所: ノートブック公開時の「パラメータ外部化」設定で選択

• 制御: 完全にサーバーサイドで制御される

• 表示: エンドユーザーには入力欄が表示されない

• 変更: エンドユーザーおよび埋め込み実装側のフロントエンドからは変更不可。サーバーサイドからは新しいトークンを発行する際（issueToken API呼び出し）にパラメータを指定することで変更可能

• 用途: セキュリティが重要なパラメータ（顧客ID、権限レベルなど）

サーバーサイド初期値 (DEFAULT)

• 設定場所: ノートブック公開時の「パラメータ外部化」設定で選択

• 制御: サーバーサイドで初期値を設定、ユーザーが変更可能

• 表示: エンドユーザーに入力欄が表示される（初期値付き）

• 変更: エンドユーザーのフォーム入力で変更可能。埋め込み実装側から変更する場合は、サーバーサイドから issueToken 時にパラメータを指定することで変更可能

• 用途: デフォルト値を提供したいが、ユーザーに変更権限を与えたいパラメータ

クライアントサイドパラメータ

• 設定場所: パラメータを外部化設定しない

• 制御: 完全にクライアントサイドで制御

• 表示: 通常の入力欄として表示される

• 変更: PostMessage API経由で親アプリケーションから制御可能

• 用途: 動的に変更したいパラメータ（フィルタ条件、表示期間など）

パラメータの変更におけるトークン発行の必要性

Token発行が必要なケース

1. 初回Signed Embed表示

2. サーバーサイドパラメータ（FIXED/DEFAULT）の値を変更する場合

3. 新しいページに移動する場合

4. Token有効期限が切れた場合

Token発行が不要なケース

• クライアントサイドパラメータのみ変更する場合 → PostMessage APIで即座に変更可能

必須パラメータの指定

外部化設定されたパラメータはすべて必須です。

{
  "params": [
    {"param_id": "customer_id", "param_value": "12345"},
    {"param_id": "date_range", "param_value": "[\"2024-01-01\", \"2024-12-31\"]"}
  ]
}

• 一つでも漏れるとエラーになります

• 外部化されていないパラメータを送信してもエラーになります

パラメータ値の変更方法

PostMessage APIによる変更

クライアントサイドパラメータ（外部化されていないパラメータ）は、PostMessage APIでのみiframeの外から変更可能です。既存のTokenを使って変更できます：

iframe.contentWindow.postMessage({
  type: 'SET_TOKEN',
  token: '現在のToken', // 新しいToken発行不要
  parameters: [
    {
      param_id: 'date_range_param_id',
      param_value: '["2024-06-01", "2024-06-30"]'
    }
  ]
}, '*');

適用条件:

• ◯ クライアントサイドパラメータ（外部化されていない）

• × DEFAULT設定パラメータ（新しいToken発行が必要）

• × FIXED設定パラメータ（新しいToken発行が必要）

新しいToken発行による変更

サーバーサイドパラメータを変更する場合は、新しいTokenの発行が必要です。

よくある質問

"Missing param: xxx" エラーが出る

外部化設定されたパラメータがToken発行時に漏れています。すべての外部化パラメータを指定してください。

"The following parameters must be set by the server" エラーが出る

FIXEDまたはDEFAULT設定されたパラメータをPostMessageで変更しようとしています。該当パラメータは新しいToken発行が必要です。

PostMessageでパラメータが反映されない

1. パラメータが外部化設定されていないか確認

2. param_valueが正しいJSON文字列形式か確認

3. param_idがWidget IDと一致しているか確認