⚙️Embed SDK

Introduction

The Embed SDK enables deeper interaction between your application and Toucan embeds, providing a seamless user experience with complete control over what appears in your embedded content.

To get started, simply navigate to Admin Area > Embed Manager > Embed Settings and copy the provided embed SDK script into your application. You’re all set to begin customizing!

Embed SDK - scripts

SDK Key

Create a dedicated token for authentication by following the steps in our Embed SDK Authentication documentation.

Glossary

IDs

• embedId: This unique identifier is used in each embed script.

• DOMId: A combination of embedId and a random hash, allowing you to integrate the same embed multiple times on a single page.

Example:

// Given
embedId = '62156d3a-8c9c-412b-946c-ddcd59db8da7'

// Then
DOMId = '62156d3a-8c9c-412b-946c-ddcd59db8da7-daderck'

Filters

The SDK provides access to Filters, enabling targeted data customization within embeds.

TcTcEmbed

When you include the embed script, it automatically attaches the TcTcEmbed object to window, ready for instantiation. Use the following code to initialize:

const instance = await TcTcEmbed.initialize();

getAll()

Description: Returns an array of all embedded HTML elements on the page. Parameters: None Returns: HTMLElement[]

Example:

const instance = await TcTcEmbed.initialize();
const embeds = instance.getAll(); 
// Output: [HTMLElement, HTMLElement...]

embedDOMIds()

Description: Returns an array of DOMIds for all embeds. Hint: embedId is not the same as DOMId and helps avoid integration issues when using the same embed multiple times on the same page. Parameters: None Returns: string[]

Example:

const embedDOMIds = instance.embedDOMIds();
// Output: ['62156d3a-8c9c-412b-946c-ddcd59db8da7', 'e88b8884-1ce2-45c6-9b84-0b609680989f', ...]

setExtraVariablesForAllEmbeds()

Description: Sets external context variables for all embeds.

Parameters:

Parameter	Type	Mandatory	Description
variables	object	✅	Variables that can be used in the embed content config

Returns: void

Example:

const instance = await TcTcEmbed.initialize();

instance.setExtraVariablesForAllEmbeds({ youVariable: 'your value' });

setFilterValueForAllEmbeds()

Description: Sets a specific filter value for all embeds.

Parameters:

Parameter	Type	Mandatory	Description
filterId	string	✅	The ID of the filter whose value you wish to change
value	object	✅	The new filter value

Returns: void

When using a filter with multiple selectable values (Checkbox filter), to select all values in this filter, you need to send:

[
    {
        anyKey: '__VOID__'
    }
]

anyKey can be anything.

Example:

const instance = await TcTcEmbed.}();

instance.setFilterValueForAllEmbeds('FILTER_ID', { columnName: 'Customer A' });

insertEmbedById()

Description: Programmatically inserts an embed into the DOM.

Important

Requires an authentication token (see Embed SDK Authentication)

Parameters:

Parameter	Type	Mandatory	Description
embedId	string	✅	The ID of the embed you want to insert
targetEl	HTMLElement	✅	The container in which you want to insert your embed
parameters.token	string	❌	The token used to identify your user
parameters.filters	Record<string, any>	❌	The initial values of your filters
parameters.panel	boolean	❌	To display or hide the additional panel
parameters.header	boolean	❌	To display or hide the story’s header
parameters.compact	boolean	❌	To force display of compact mode if value is true
parameters.stage	string	❌	To get the staging version of the application if the value is staging
parameters.variables.extra	Record<string, any>	❌	The extra variables you can use in your Toucan embeds

Returns:

• Success: Promise<Embed>

• Error:

  • when targetEl isn't an HTMLElement

Example:

const instance = await TcTcEmbed.initialize('SDK_AUTH_TOKEN');

await instance.insertEmbedById(
    'MY_EMBED_ID',
    document.getElementById('parent-container'),
    {
        token: 'USER_TOKEN',
        lang: 'en',
        filters: {
            'FILTER_ID': {
                column: 'value'
            }
        },
        panel: false,
        header: true,
        variables: {
            extra: {
                var1: 'valueA'
            }
        }
    }
);

Example with a checkbox filter with multiple values set:

const instance = await TcTcEmbed.initialize('SDK_AUTH_TOKEN');
                
await instance.insertEmbedById(
    'MY_EMBED_ID',
    document.getElementById('parent-container'),
    {
        token: 'USER_TOKEN',
        lang: 'en',
        filters: {
            'FILTER_ID': {
                column: ['value1', 'value2']
            }
        },
        panel: false,
        header: true
    }
);

get()

Description: Gets an embed instance using either DOMId or embedId.

Using DOMId instead of embedId can be useful if you use the same embed several times on the same page.

Parameters:

Parameter	Type	mandatory	Description
embedId or DOMId	string	✅	The ID or DOMId of the embed you want to insert
maxWait	number	❌	The maximum waiting time in milliseconds before stopping the search for an embed in the DOM (default: 2000ms)

Returns: Promise<Embed>

Example:

const instance = await TcTcEmbed.initialize();

// With EmbedId
const embed = await instance.get('MY_EMBED_ID');
// With custom max wait time of 5 seconds
const embed = await instance.get('MY_EMBED_ID', 5000);

// With DOMId
const embedDOMIds = instance.embedDOMIds();

const embed = await instance.get(embedDOMIds[0]);
// With custom max wait time of 5 seconds
const embed = await instance.get(embedDOMIds[0], 5000);

sendPDFReport()

Description: Sends a PDF report synchronously for a targeted application to a list of users. Enables synchronous sending of a PDF report for a specific application to a list of recipients. Each recipient is represented as an object containing a token and optional variables. Tokens are used to directly access user context and permissions, including their email (in the username field), groups, and any other attributes needed to ensure the correct PDF report is sent.

If you don't know what it is, click here for more information.

Important

Requires an authentication token (see Embed SDK Authentication)

Parameters:

Parameter	Type	mandatory	Description
smallAppUrlPart	string	✅	PDF Report's Small App URL Example: if your small app is accessible with the URL https://acme.toucantoco.com/my-app, then use my-app
users[].token	string	✅	The token used to identify your user
users[].variables	Record<string, any>	❌	Override global variables for specific users
reportId	string	✅	Report ID. Can be find in the URL of a given PDF report
variables	Record<string, any>	❌	Filters or extraVariables used into the PDF Report

Returns:

• Success: Promise

• Error:

  • if any email failed to reach its user.

const instance = await TcTcEmbed.initialize('SDK_AUTH_TOKEN');

const my_users = [
  { token: 'AUTH_TOKEN_A' },
  { token: 'AUTH_TOKEN_B' },
  { token: 'AUTH_TOKEN_C', variables: { shop: 'shop B' } },
]

instance.sendPDFReport(
  'my_small_app_id',
  my_users,
  'report_id',
  { shop: 'shop A' },
)

All recipients will receive a PDF report for shop A, except the third user, who will receive a report customized for shop B.

Embed

refreshDataQueries()

Description: Refreshes the data in a given embed.

Parameters: None

Returns: void

Example:

// My user performs an action that changes the data
// As a developer, I want to refresh the data in the displayed story
const instance = await TcTcEmbed.initialize();
const embedDOMIds = instance.embedDOMIds();
const embed = await instance.get(embedDOMIds[0]);

embed.refreshDataQueries();

filterIds()

Description: Retrieves all filter IDs for a given embed. Parameters: None Returns: string[]

Avoid calling this method during initialization, as the filters could not be loaded yet.

Prefer using getFilterIdsAsync() instead as it is guaranteed to resolve when the filters have loaded, unlike filterIds().

Use filterIds for scenarios like binding it to a button click or user interaction.

Example:

const filterIds = embed.filterIds();
// ['filterA', 'filterB', ...]

getFilterIdsAsync()

Description: Retrieves the filter IDs asynchronously. This method guarantees that the filters configuration is fully loaded before resolving. Parameters: None Returns: Promise<string[]>

Use this method when you need to ensure that the filters configuration is fully loaded, such as during the initialization phase.

This method is particularly useful for embedding scenarios where the timing of the filters configuration load is uncertain.

Example:

const filterIds = await embed.getFilterIdsAsync(); 
// ['filterA', 'filterB', ...]

getFilter()

Description: Retrieves a specific filter by ID.

Parameters:

Parameter	Type	Mandatory	Description
filterId	string	✅	The ID of the filter

Returns: Filter

Example:

const filterIds = embed.filterIds();
// ['filterA', 'filterB', ...]

const filterA = embed.getFilter(filterIds[0]);

setExtraVariables()

Description: Sets additional variables from external context for a given embed.

Parameters:

Parameter	Type	mandatory	Description
variables	object	✅	The extra variables you can use in your Toucan embeds

Returns: void

Example:

embed.setExtraVariables({ youVariable: 'your value' });

Event Emitter System

Description: Listens to Toucan events for enhanced interaction within embeds. Supported charts include:

Important

• Circularchart

• Leaderboard

• Linechart

• Barchart

• Barlinechart

• Heatmap

• Mapchart

• Bulletchart

• Stackedbarchart

subscribe

Description: Allows you to listen to Toucan Events. The following events are available:

Events:

• chart:selection: Triggered when a user selects an element.

• chart:drill: Triggered when a user interacts with a drillable element.

Parameters:

Parameter	Type	Mandatory	Description
eventName	TcEvent	✅	Toucan Event's name
callback	function	✅	The token used to identify your user

Callback function returns: EventData

function callback(eventData: EventData, context: Context)

Parameters:

Parameter	Type	Description
clickType	string	The corresponding user interaction with the chart. Possible values are: click and dblclick ⚠️ Only supported on Mapcharts
dataRow	Record<string, any>	The corresponding data row to the user selection
dataLabel	string	The corresponding value in the column used for the label
type	string	Chart type selection (e.g: ‘zone’ for a Mapchart, ‘bar’ for a Leaderboard, …)

Context:

Parameter	Type	Description
chartType	string	Chart's name
embedId	string	Embed Id
storyId	string	Story / Tile / Dashboard id
chartIndex	number	Chart’s index position inside an embedded story
drillInfo	Object
children	Record<string, any>	Children’s data
type	string	Always equals "drill".

chart:selection

const instance = await TcTcEmbed.initialize();

const embed = await instance.get('my_embed_id');

embed.subscribe('chart:selection', (payload) => {
    // do amazing stuff in your application!
});

chart:drill

const instance = await TcTcEmbed.initialize();

const embed = await instance.get('my_embed_id');

embed.subscribe('chart:selection', (payload) => {
    // do amazing stuff in your application!
});

unsubscribe

Description: Destroy listeners to Toucan events.

Parameters:

Parameter	Type	Mandatory	Description
eventName	TcEvent	✅	Toucan Event's name

Returns: void

Example:

embed.unsubscribe('chart:selection');

Filter

Description: A Filter is an interface element used to adjust the data in visualizations, with values based on a specific column in the dataset.

values()

Description: Return all data row values for a given Filter

Parameters: None

Returns: Record<string, any>[]

Example:

const myFilter = embed.getFilter('FILTER_ID');

const values = myFilter.values();
// [{ customer: 'Customer A', country: 'USA'}, { customer: 'Customer B', country: 'France }, { customer: 'Customer C', country: 'Spain' }]

currentValue()

Description: Return the current value for a given Filter

Parameters: None

Returns: Record<string, any>[]

Example:

const myFilter = embed.getFilter('FILTER_ID');

const currentValue = myFilter.currentValue();
// '{ customer: 'Customer A', country: 'USA'}'

setValue()

Description: Set the current value for a given Filter

Parameters:

Parameter	Type	Mandatory	Description
value	any	✅	A value that is available in the Filter values

Returns: void

Example:

const myFilter = embed.getFilter('FILTER_ID');

myFilter.setValue({ customer: 'Customer B'});

// For hierarchical requesters, you have to specify columns for all level
// Example level 0 = USA
myFilter.setValue({ level0: 'USA' });

// Example level O = USA and level 1 = Minnesota
myFilter.setValue({ level0: 'USA', level1: 'Minnesota' });