⚙️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

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 1 month ago