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

Returns

  • void

Example

const instance = await TcTcEmbed.initialize();

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

setFilterValueForAllEmbeds()

Set the value of one requester for all embeds.

Parameters

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

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

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

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

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

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

Callback function returns

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

EventData

Context

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.

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

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