Embed SDK

What is it for ?

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 on what is displayed in your embeds.

Embed SDK interface

Embed SDK interface

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

Glossary

Ids

embedId: It is the unique id used in embed script.

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

Example:

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

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

Filters & Requesters

We will also talk about Filters and Requesters.

Doesn’t ring any bell ? You should go right here to get more information.

API

Instance

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

const instance = new TcTcEmbed();

// With linting, you may need to do so
const instance = new window.TcTcEmbed();

getAll()

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

  • Arguments:
  • N/A
  • Returns: Array<HTMLElement>
  • Usage:
const instance = new TcTcEmbed();

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

embedDOMIds()

Returns an array of DOMIds.

Warning

Good to know: embedId !== DOMId to avoid issues when integrate multiples times the same embed on a same page

  • Arguments:
  • N/A
  • Returns: Array<string>
  • Usage:
const instance = new TcTcEmbed();

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

setRequestersValue()

Set the value of one requester for all embeds

  • Arguments:
  • {string} - requesterId mandatory
  • {any} - value mandatory
  • Returns: void
  • Usage:
const instance = new TcTcEmbed();

instance.setRequestersValues('APP_REPORT_REQUESTER_ID', 'Customer A', 'Customer B', 'Customer C', 'Customer D@');

get()

Return an Embed instance. Returns undefined if DOMId doesnt exist

  • Arguments:
  • {string} - DOMId mandatory
  • Returns: Embed | undefined
  • Usage:
const instance = new TcTcEmbed();

const embedDOMIds = instance.embedDOMIds();

const embed = instance.get(embedDOMIds[0]);

Embed

requesterIds()

Return all the requester ids for a given Embed

  • Arguments:
  • N/A
  • Returns: Array<string>
  • Usage:
const requesterIds = embed.requesterIds();
// ['requesterA', 'requesterB', ...]

getRequester()

Return a Requester for a given Embed

  • Arguments:
  • {string - requesterId} mandatory
  • Returns: Requester
  • Usage:
const requesterIds = embed.requesterIds();
// ['requesterA', 'requesterB', ...]

const myRequesterA = embed.getRequester(requesterIds[0]);

getFilter()

Return a Filter for a given Embed On a Story, there’s only 3 differentions positions for a Filter

  • Arguments:
  • {string - position} -> bottom-right, upper-middle or upper-right mandatory
  • Returns: Filter
  • Usage:
const myBottomRightFilter = embed.getFilter('bottom-right');

Requester

A Requester is like a variable linked to a button, a dropdown or a slider, which is used to filter the data query. By default, two are available and global in the application: view (APP_REPORT_REQUESTER_ID) and date (APP_DATE_REQUESTER_ID).

values()

Return all values for a given Requester

  • Arguments:
  • N/A
  • Returns: Array<any>
  • Usage:
const myViewRequester = embed.getRequester('APP_REPORT_REQUESTER_ID');

const values = myViewRequester.values();
// ['Customer A', 'Customer B', 'Customer C', 'Customer D']

currentValue()

Return the current value for a given Requester

  • Arguments:
  • N/A
  • Returns: any
  • Usage:
const myViewRequester = embed.getRequester('APP_REPORT_REQUESTER_ID');

const values = myViewRequester.currentValue();
// 'Customer A'

setValue()

Set the current value for a given Requester

  • Arguments:
  • { any - value } -> A value that is available in the requester’s values
  • Returns: void
  • Usage:
const myViewRequester = embed.getRequester('APP_REPORT_REQUESTER_ID');

myViewRequester.setValue('Customer B');

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. That’s the main difference with a Requester that possesses its own dataset.

currentValue()

Return the current value for a given Filter

  • Arguments:
  • N/A
  • Returns: string
  • Usage:
const myBottomRightFilter = embed.getFilter('bottom-right');

const values = myBottomRightFilter.currentValue();
// 'Segment A'

setValue()

Set the current value for a given Filter

  • Arguments:
  • { string - value } -> A value that is avaialbe in Filter’s values
  • Returns: void
  • Usage:
const myBottomRightFilter = embed.getFilter('bottom-right');

myBottomRightFilter.setValue('Segment B');