Parameter Specifications

Detailed specifications for server-side and client-side parameters

This page provides detailed information about parameter behavior and control methods in Signed Embed.

Parameter Types and Behavior

In Signed Embed, parameters are classified into three types based on their control methods. Embedding implementers need to understand each characteristic and choose appropriately.

Server-side Fixed Value (FIXED)

• Configuration: Selected in "Parameter Externalization" settings when publishing notebook

• Control: Completely controlled by server-side

• Display: No input field shown to end users

• Modification: Cannot be changed by end users or embedding implementation's frontend. Can be changed from server-side by specifying parameters when issuing new tokens (via issueToken API call)

• Use Case: Security-critical parameters (customer ID, permission level, etc.)

Server-side Default Value (DEFAULT)

• Configuration: Selected in "Parameter Externalization" settings when publishing notebook

• Control: Initial value set by server-side, user can modify

• Display: Input field shown to end users (with initial value)

• Modification: Can be changed through end user's form input. Changes from embedding implementation require server-side parameter specification during issueToken

• Use Case: Parameters where you want to provide default values but allow users to change them

Client-side Parameters

• Configuration: Do not externalize the parameter

• Control: Completely controlled by client-side

• Display: Shown as regular input field

• Modification: Can be controlled from parent application via PostMessage API

• Use Case: Parameters you want to change dynamically (filter conditions, display periods, etc.)

Token Issuance Requirements

Cases Requiring Token Issuance

1. Initial Signed Embed display

2. Changing server-side parameter (FIXED/DEFAULT) values

3. Moving to a new page

4. Token expiration

Cases Not Requiring Token Issuance

• Changing only client-side parameters → Can be changed immediately via PostMessage API

Required Parameter Specification

All externalized parameters are mandatory.

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

• Missing any parameter will result in an error

• Sending non-externalized parameters will also result in an error

Parameter Value Modification Methods

PostMessage API Modification

Client-side parameters (non-externalized parameters) can only be changed from outside the iframe via PostMessage API. You can modify them using existing tokens:

iframe.contentWindow.postMessage({
  type: 'SET_TOKEN',
  token: 'current_token', // No need to issue new token
  parameters: [
    {
      param_id: 'date_range_param_id',
      param_value: '["2024-06-01", "2024-06-30"]'
    }
  ]
}, '*');

Applicable to:

• ◯ Client-side parameters (not externalized)

• × DEFAULT setting parameters (requires new token issuance)

• × FIXED setting parameters (requires new token issuance)

New Token Issuance for Modification

To change server-side parameters, you need to issue a new token.

Frequently Asked Questions

Getting "Missing param: xxx" error

Externalized parameters are missing during token issuance. Please specify all externalized parameters.

Getting "The following parameters must be set by the server" error

You're trying to modify FIXED or DEFAULT configured parameters via PostMessage. These parameters require new token issuance.

PostMessage parameter changes not reflected

1. Check if parameter is not externalized

2. Verify param_value is in correct JSON string format

3. Confirm param_id matches Widget ID