Toucan 3.0
YouPrep documentationHelp centerGet a demo
  • Welcome
    • ๐Ÿ‘‹Welcome to Toucan
    • โš™๏ธTechnical resources
      • โš™๏ธToucan stack
      • Setup mode
        • Toucan SaaS mode
      • โš™๏ธSecurity
        • Application Security
        • Source Code Quality
        • Global Security Practices
        • Security of Docker Images
  • TUTORIALS
    • ๐Ÿ“ŠGetting Started : Embedded Analytics
    • ๐Ÿค“Advanced tutorials
      • Embedding a story with user attributes
        • Dynamic filter with user attributes
        • Dynamic Tables
        • Dynamic Database
        • Dynamic Host
      • Using the HTTP API connector in advanced use cases
      • Using advanced syntax for SQL queries
      • Merging filters with our tool
      • Deep customization chart (CSS)
        • Homepage customization
        • Chart customization
        • Dashboard customization
  • Data Management
    • ๐ŸงฎOverview of Data In Toucan
    • ๐Ÿ“กDatasources in Toucan
      • ๐Ÿ”ŒManaging Connectors
        • ๐Ÿ”ŒCreating, editing and deleting a connector
        • ๐Ÿ”ŒSet up OAuth2 credentials for your platform
        • ๐Ÿ”ŒSetting up a connector
          • ๐Ÿ”ŒGeneric Connectors
            • ๐Ÿ”ŒSetting up an HTTP API connector
            • ๐Ÿ”ŒSetting up an ODBC Connector
          • ๐Ÿ”ŒDatabase and data warehouse Connectors
            • ๐Ÿ”ŒSetting up an AWS Redshift Connector
            • ๐Ÿ”ŒSetting up a Snowflake Connector
            • ๐Ÿ”ŒSetting up a PostgreSQL Connector
            • ๐Ÿ”ŒSetting up a Google Big Query Connector
            • ๐Ÿ”ŒSetting up an AWS Athena connector
            • ๐Ÿ”ŒSetting up a MySQL connector
            • ๐Ÿ”ŒSetting up a MongoDB connector
            • ๐Ÿ”ŒSetting up a Microsoft SQL Server connector
            • ๐Ÿ”ŒSetting up an Azure SQL connector
            • ๐Ÿ”ŒSetting a Databricks Connector
            • ๐Ÿ”ŒSetting up a ElasticSearch Connector
            • ๐Ÿ”ŒSetting up a Clickhouse Connector
          • ๐Ÿ”ŒOnline services connectors
            • ๐Ÿ”ŒSetting up a Sharepoint Connector
            • ๐Ÿ”ŒSetting up a Google Sheets Connector
            • ๐Ÿ”ŒSetting up a Salesforce Connector
            • ๐Ÿ”ŒSetting up a Hubspot Connector
          • ๐Ÿ”ŒSetting up an AWS S3 connector
      • ๐Ÿ“Managing Files
        • ๐Ÿ“Adding, editing and deleting local files
        • ๐Ÿ“‚Using advanced file settings
        • ๐Ÿ“Adding and combining remote files in Toucan
    • ๐Ÿ”ขDatasets in Toucan
      • ๐Ÿ”ขStored and Live Datasets
      • ๐Ÿ’ฟManaging datasets
        • ๐Ÿ”ขCreating datasets
        • ๐Ÿ”ขEditing, Duplicating and Deleting a dataset
        • ๐Ÿ”ขRefreshing and Publishing Datasets
        • ๐Ÿ“ˆOptimize data performance
        • ๐Ÿ—‚๏ธAdding indexes to stored datasets
        • ๐Ÿ‘ฉโ€๐Ÿ’ปCode mode and single mode
      • ๐Ÿ›‘Setting permissions on dataset
      • ๐Ÿ—ƒ๏ธMaintaining Data
        • ๐Ÿ—ƒ๏ธTagging datasets
        • ๐Ÿ—ƒ๏ธIdentifying datasets dependencies
        • ๐Ÿ—ƒ๏ธSet validation rules
    • ๐Ÿง‘โ€๐ŸณPreparing data
      • Overview of YouPrepโ„ข
        • ๐ŸŽนColumn header
          • Rename column
          • Duplicate column
          • Fill null values
          • Replace values
          • Sort values
          • Convert columns data types
        • Add
          • Add text column
          • Add formula column
          • Add conditional column
        • Filter
          • Delete columns
          • Keep columns
          • Filter rows
          • Top N rows
          • ArgMax
          • ArgMin
        • Aggregate
          • Group by
          • Add total rows
          • Hierarchical rollup
          • Get unique groups/values
        • Compute
          • Compute evolution
          • Cumulated sum
          • Percentage of total
          • Rank
          • Moving average
          • Compute statistics
          • Absolute value
        • Text
          • Concatenate
          • Split column
          • Extract substring
          • To lowercase
          • To uppercase
          • Compare text columns
          • Trim spaces
          • Replace text
        • Date
          • Convert text to date
          • Convert date to text
          • Extract date information
          • Add missing dates
          • Compute duration
        • Reshape
          • Pivot
          • Unpivot
          • Waterfall
        • Combine
          • Append datasets
          • Join datasets
        • Geo
          • Geographic dissolve
          • Geographic hierarchy
          • Geographic simplify
          • Prepare geo data (with basemap)
      • YouPrepโ„ข Native SQL
      • Hybrid pipeline
    • โžฟManaging variables in Toucan
      • โžฟVariables hub
      • โ™ˆUse variables in YouPrepโ„ข
      • โžฟEasy reference to variables
    • ๐ŸงžUsing advanced data concepts
      • ๐ŸงžData personnalisation with user attributes
        • Connector setup with a user attribute
        • Database selection with a user attribute
        • YouPrep data filtering with a user attribute
        • Filter data in SQL with a user attribute
      • ๐ŸงžAdvanced syntax for variables
      • ๐ŸงžData cache
  • Visualizations and Layouts
    • ๐Ÿ“บApps
      • ๐Ÿ“บManaging Apps
        • โž•Creating Apps
        • ๐Ÿ“„Duplicating Apps
        • ๐Ÿ–จ๏ธPublishing Apps
        • ๐ŸšฎDeleting Apps
        • โœ๏ธEditing within an App
      • ๐Ÿ–Œ๏ธCustomizing Apps
        • Customizing chart color elements
        • Customizing the app's font
        • Adding Assets
        • Adding Glossary
        • Setting up, Managing and testing custom visibilities
        • Customizing the "no data error" message
        • Creating a dynamic background based on an Filter's column
      • ๐Ÿ Home
        • Creating the Home
        • Creating Tiles
          • Tile Dynamic Value
          • Tile Leaderboard
          • Tile Line
          • Tile Scorecard
          • Tile Bullet
          • Tile Heatmap
          • Tile PDF
          • Tile Video
          • Tile Image
          • Tile Text
          • Tile HTML
          • Tile Separator
      • โœจStories
        • Creating a Story
        • KPIs
        • Narrative
        • Crossfilter
      • ๐Ÿ“ฝ๏ธFilters
        • Managing Filters
          • Creating, reusing and editing Filters
          • Applying Filters
          • Unpinning and deleting Filters
        • Type of Filters
          • Dropdown
          • Checkboxes
          • Buttons
          • Date Range
          • Hierarchical
          • Slider
        • Templating from Filters' values
        • Dependant Filters
      • ๐Ÿ“ˆPDF Report
      • ๐ŸŽกDatawall
      • ๐Ÿ—๏ธDashboard Builder
        • Create a Dashboard Builder
        • Embed a Dashboard Builder
        • Dashboard export options
      • ๐ŸŒŸMyFavorites
    • ๐Ÿ“ŠCreating Visualizations
      • ๐ŸคฉViz Gallery
        • Barchart
        • Barlinechart
        • Bubblechart
        • Bulletchart
        • Circularchart
        • Funnelchart
        • Gantt chart
        • Heatmap
        • HTML
        • Leaderboard
        • Leaderboard Centered Average
        • Linechart
        • Mapchart
          • Configure a drill
        • Mediachart
        • Radarchart
        • Tablechart
        • Timeline
        • Versuschart
        • Waterfallchart
        • Score Card
        • Stacked Barchart
      • ๐Ÿง Common Chart Configuration
      • ๐Ÿ’…Customizing chart colors
      • ๐Ÿงžโ€โ™‚๏ธAdvanced chart configuration
        • Templating from chart's dataset
        • Add units, precisions and sentiments
        • Adding Tutorials
        • Add sparklines
        • Navigate with stories
        • Group informations in your stories
        • Multiple charts in one story
        • Manage dates
        • Customize tiles' sources
        • Add stars to tiles' title
        • Manage data order in your tiles
        • Navigate with tiles
    • ๐Ÿ‘ฉโ€๐Ÿ’ปEmbedding
      • ๐Ÿ”Authentication
      • ๐Ÿ–‡๏ธIntegration
        • Generate and manage embeds
        • Customize embeds
        • Embedding a Toucan App Using iFrames
        • Passing Extra Variables to Your Toucan Embed
      • โš™๏ธEmbed SDK
        • Embed SDK Authentication
      • โ“FAQ
    • ๐Ÿ™‹Self-Service
      • Self-Service Dashboard
      • Self-service PDF Report
  • Collaboration
    • โฐCreating alerts
    • ๐Ÿ“งManaging notifications
    • โž•Enriching a story with descriptions
    • ๐Ÿ’ŒSharing content
    • ๐Ÿ’ฌAdding comments to stories
  • Administration
    • Page
    • โš™๏ธInstance Management
      • โš™๏ธManaging operations in SaaS
      • โš™๏ธCustomizing your instance (whitelabel)
    • ๐Ÿ‘ฅManaging Users
      • ๐Ÿ‘ฅUsers
      • ๐Ÿ‘ฅManaging user groups
      • ๐Ÿ‘ฅManaging user properties
      • ๐Ÿ‘ฅSetting up permissions and visibilities
    • ๐ŸŒManaging languages in Toucan (internationalisation)
    • ๐Ÿ“ˆMonitoring Engagement with User Analytics
      • ๐ŸŽ›๏ธHow to Filter your User Analytics?
      • ๐Ÿ–ฅ๏ธUnderstanding your User Analytics Dashboards
  • Additional Ressources
    • ๐Ÿ“šExternal documentation
    • ๐ŸšSupport for App-builders
    • ๐Ÿ†•Latest releases
      • ๐ŸŽ2025 Releases
      • ๐ŸŽ2024 Releases
      • ๐ŸŽ2023 Releases
    • ๐Ÿ”งTroubleshooting
      • Troubleshoot:: DataHub
      • Cross-Site Cookies
      • How to :: read the inspector error
      • How to :: troubleshoot the toucan way
Powered by GitBook
On this page
  • Introduction
  • SDK Key
  • Glossary
  • IDs
  • Filters
  • TcTcEmbed
  • getAll()
  • embedDOMIds()
  • setExtraVariablesForAllEmbeds()
  • setFilterValueForAllEmbeds()
  • insertEmbedById()
  • get()
  • sendPDFReport()
  • Embed
  • refreshDataQueries()
  • filterIds()
  • getFilterIdsAsync()
  • getFilter()
  • setExtraVariables()
  • Event Emitter System
  • subscribe
  • unsubscribe
  • Filter
  • values()
  • currentValue()
  • setValue()

Was this helpful?

  1. Visualizations and Layouts
  2. Embedding

Embed SDK

Last updated 25 days ago

Was this helpful?

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!

SDK Key

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

Example:

const instance = await TcTcEmbed.initialize();

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

insertEmbedById()

Description: Programmatically inserts an embed into the DOM.

Important

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.

Important

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

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' });

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

Requires an authentication token (see )

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

Requires an authentication token (see )

Only supported on Mapcharts

๐Ÿ‘ฉโ€๐Ÿ’ป
โš™๏ธ
Embed SDK Authentication
Embed SDK Authentication
here
Embed SDK Authentication
โš ๏ธ
Embed SDK - scripts