โš™๏ธ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

parametertypemandatoryDescription

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

parametertypemandatoryDescription

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

parametertypemandatoryDescription

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

parametertypemandatoryDescription

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

parametertypemandatoryDescription

smallAppId

string

โœ…

PDF Report's Small App Id

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

parametertypemandatoryDescription

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

parametertypemandatoryDescription

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

subscribe

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

parametertypemandatoryDescription

eventName

TcEvent

โœ…

Toucan Event's name

callback

function

โœ…

Token that authenticates user

Callback function returns

Signature
function callback(eventData: EventData, context: Context)

EventData

parametertypeDescription

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

parametertypeDescription

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.

parametertypemandatoryDescription

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

parametertypemandatoryDescription

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