⚙️Embed SDK

Introduction

Its goal is to allow you to interact deeper between your application and Toucan embeds. You’ll be able to give a truly seamless user experience and have full control over what is displayed in your embeds.

You can find the embed SDK script in "Admin Area > Embed Manager > Embed Settings".

All you need to do is copy/paste that script into your application and you’re good to start playing with it.

SDK Key

Create a dedicated token following our documentation Embed SDK Authentication.

Glossary

Ids

embedId: It is the unique id used in the embed script.
DOMId: It is the combination between embedId + a random hash. It allows you to integrate the same embed on the same page several times.

Example:

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

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

Filters

We will also talk about Filters.

TcTcEmbed

The script will attach to window our TcTcEmbed object, ready to be created.

const instance = await TcTcEmbed.initialize();

getAll()

Returns an array of HTMLElement for each embed on the page.

Parameters

N/A

Returns

HTMLElement

Example

const instance = await TcTcEmbed.initialize();

const embeds = instance.getAll();
// [HTMLElement, HTMLElement...]

embedDOMIds()

Returns an array of DOMIds.

Hint

embedId !== DOMId to avoid issues when integrating multiples times the same embed on the same page

Parameters

N/A

Returns

string[]

`Example`

const instance = await TcTcEmbed.initialize();

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

setExtraVariablesForAllEmbeds()

Set variables from external context for all embeds

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`variabes`	object	✅	Variables that can be used in the embed content config

variabes

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()

Set the value of one requester for all embeds.

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`filterId`	string	✅	Id of the Filter you want to change value
`value`	object	✅	The new value for the filter

filterId

string

✅

Id of the Filter you want to change value

value

object

✅

The new value for the filter

Returns

void

Example

const instance = await TcTcEmbed.initialize();

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

insertEmbedById()

Insert an Embed programmatically in the DOM.

Important

This method needs an authentication token (cf. Embed SDK Authentication)

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`embedId`	string	✅	Id of the embed you want to insert
`targetEl`	HTMLElement	✅	Container on which will insert the embed id
`parameters.token`	string	❌	Token used to authenticate user
`parameters.filters`	Record<string, any>	❌	Initial values for Filters.
`parameters.panel`	boolean	❌	Display or not the additional panel
`parameters.header`	boolean	❌	Display or not a story’s header
`parameters.compact`	boolean	❌	Force display in compact mode when set to `true`
`parameters.stage`	string	❌	Get staging version when set to "staging"
`parameters.variables.extra`	Record<string, any>	❌	Arbitrary variables that you can use inside Toucan embeds

embedId

string

✅

Id of the embed you want to insert

targetEl

HTMLElement

✅

Container on which will insert the embed id

parameters.token

string

❌

Token used to authenticate user

parameters.filters

Record<string, any>

❌

Initial values for Filters.

parameters.panel

boolean

❌

Display or not the additional panel

parameters.header

boolean

❌

Display or not a story’s header

parameters.compact

boolean

❌

Force display in compact mode when set to true

parameters.stage

string

❌

Get staging version when set to "staging"

parameters.variables.extra

Record<string, any>

❌

Arbitrary variables that you can use inside Toucan embeds

Returns

Success: Promise<Embed>
Error
- when targetEl isn't an HTMLElement

Example

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

get()

Get the instance of an Embed

Using DOMId rather than EmbedId can be useful if you’re using multiple times the same embed on a single page.

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`embedId` or `DOMId`	string	✅	Id or DOMId of the embed
`maxWait`	number	❌	Max wait time in milliseconds before stopping to search for an embed in the DOM (default: 2000ms)

embedId or DOMId

string

✅

Id or DOMId of the embed

maxWait

number

❌

Max wait time in milliseconds before stopping to search for an embed in the DOM (default: 2000ms)

Returns

Promise<Embed>

Example

const instance = 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()

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

Allows to send synchronously the PDF report of a targeted small application for a list of recipients. Each list’s item is an object of token and variables. We’re using the tokens to get directly all the user context and permissions, such as her email (in the field username) and her groups, and/or attributes that will be important to send the right PDF report.

Important

This method needs an authentication token (cf. Embed SDK Authentication)

Parameters

parameter type mandatory Description

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	✅	Token that authenticates 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

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

✅

Token that authenticates 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 at least one email didn’t 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' },
)

Everyone will receive a PDF report for shop A, except the 3rd user on which we precise to use shop B value.

Embed

refreshDataQueries()

Rerun queries for a given Embed.

Parameters

N/A

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()

Returns all the requester ids for a given Embed

Parameters

N/A

Returns

string[]

Example

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

getFilter()

Return a Filter for a given Embed

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`filterId`	string	✅	Filter's id

filterId

string

✅

Filter's id

Returns

Filter

Example

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

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

setExtraVariables()

Set variables from external context for a given Embed

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`variables`	object	✅	Variables that can be used in the embed content config

variables

object

✅

Variables that can be used in the embed content config

Returns

void

Example

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

Event Emitter System

What’s for?

This module allows you to listen to Toucan Events to interact deeply with your embedded stories!

Important

The following Charts are supported:

Circularchart
Leaderboard
Linechart
Barchart
Barlinechart
Heatmap
Mapchart
Bulletchart
Stackedbarchart

Allow to listen to Toucan Events. The following events are available:

chart:selection: whenever the user selects an element in a visualization (bar, bubble, zone, etc.)
chart:drill: whenever the user interacts with a drillable element in a visualization (bar, bubble, zone, etc.)

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`eventName`	TcEvent	✅	Toucan Event's name
`callback`	function	✅	Token that authenticates user

eventName

TcEvent

✅

Toucan Event's name

callback

function

✅

Token that authenticates user

Callback function returns

Signature

function callback(eventData: EventData, context: Context)

EventData

parameter type Description

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, …)

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

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".

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

Destroy listeners to Toucan events.

parameter type mandatory Description

parameter	type	mandatory	Description
`eventName`	TcEvent	✅	Toucan Event's name

eventName

TcEvent

✅

Toucan Event's name

Returns

void

Example

embed.unsubscribe('chart:selection');

Filter

A Filter is an interface element to change the data in our visualization. Its values are based on a column present in the used dataset.

values()

Return all data row values for a given Filter

Parameters

N/A

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()

Return the current value for a given Filter

Parameters

N/A

Returns

Record<string, any>

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

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

setValue()

Set the current value for a given Filter

Parameters

parameter type mandatory Description

parameter	type	mandatory	Description
`value`	any	✅	A value that is available in the Filter values

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

Last updated 2 days ago