Test an embed URL in the embed sandbox

You can test your embed with the embed sandbox environment before integrating the content into a host application. View the content from the embed user’s perspective to verify security settings and other configurations.

This document explains how to access and use the embed sandbox to develop and test your secure embed.

System and user requirements

• Secure embedding must be enabled for your organization.
• You must be assigned the Admin account type or have been granted embed credentials by an admin. See Generate embed client credentials for more information.

Access the embed sandbox

1. Open a workbook that contains the content you want to embed.
2. In the workbook header, click the down arrow () to open the workbook menu.
3. In the workbook menu, select Share and export, then select Embedding.
4. In the Embed workbook modal, select the JSON Web Tokens tab.
5. Select the content you want to embed, then click Preview to test it in the embed sandbox, which opens in a new tab.

Configure the embed in the embed sandbox

1. In the Embed sandbox page, configure the embed details in the Configure embed panel:

   • The Workbook path field is auto-populated based on the path selected in Access the embed sandbox. To test a different embed URL, enter the preferred URL.

   • In the Client credentials field, select the name of the applicable client credentials. See Generate embed client credentials.

2. Set the parameters in the Configuration section of the Configure embed panel:

   • (Optional) In the Controls field, enter all control ID and value pairs to pass through to the embed. For example, to set a compass directional control with the control ID compass-control to the value North, enter the control ID and value pair compass-control=North. See Set control values in a URL using query string parameters.

   • (Optional) In the Theme field, select any default or custom workbook theme saved to your organization.

   • (Optional) In the Menu position field, select the position of the embed menu.

3. In the Options section, set additional options as JWT claims:

   These options only appear if you have the Admin account type. If you don’t have the Admin account type, you can only test the embed as yourself.

   • (Optional) Email: Enter the email of the user that you want to use to log in to the embed. By default, this field is set to the email address you use to log in to Sigma.

   • (Optional) Assign new teams: Select the checkbox if you want to assign the user to a team that has access to see this workbook. This option is only relevant for users that do not have an account in Sigma.

   • (Optional) Assign new account type: Select the checkbox if you want to assign the user to an account type. This option is only applicable to users that do not have an account in Sigma.

   • (Optional) Assign new user attributes: Select the checkbox to assign user attributes and values to a user. This option is only applicable to users that do not have an account in Sigma.

   Optional JWT claims, such as eval_connection_id, are not supported in the embed sandbox.

4. In the Advanced options section of the Configure embed panel, set additional parameters:

   • (Optional) In the Other parameters field, enter additional key-value pairs for additional parameters you want to configure in the embed. See Embed URL parameters for options.

   • In the Session length field, enter the duration (in seconds) of the embed URL’s browser session validity.

   • (Optional) In the Version tag field, enter the name of the version tag to use when rendering the embedded content.

   • (Optional) For Hide tooltips, select the checkbox to hide chart mark tooltips.

   • (Optional) For Hide saved views, select the checkbox to hide saved views for embed users.

   • (Optional) For Hide save as, select the checkbox to hide the option to save the workbook as a new document. The option only appears for users with permission.

   • (Optional, entire workbook only) For Show Assistant, select the checkbox to show Assistant in the embedded workbook.

   • (Optional) For Disable mobile view, select the checkbox to disable mobile view.

5. Click Load embed to test the configured embed.

   If necessary, adjust the configurations, then click Load embed again to render the changes.

   If the sandbox displays a message indicating you don’t have permission to access the page, and you assigned new teams to the user, ensure the workbook is shared with the team selected in the Assign new teams section.

Test the embed outside of Sigma

You can use the URL generated by the embed sandbox for inspection and additional testing outside of Sigma.

1. After you load the embed, the Configure embed panel footer displays a View URL option. To display the embed URL with the configured parameters, click View URL.

2. To generate a one-time-use URL to test in a browser or application code, click Usable URL. The URL is automatically copied to your clipboard.