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.

SDK Key

Some of the SDK’s methods will need that you instantiate it with a developer key. You can find it under the URL of your SDK. It allows you to programmatically interact with your platform’s backend. You can renew it as well if you have to change it for security reasons for instance.

SDK Key

SDK Key

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.

TcTcEmbed

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', ...]

setExtraVariablesForAllEmbeds()

Set variables from external context for all embeds

  • Arguments:
    • {object} - externalVariables mandatory - variables that can be used in the embed content config
  • Returns: void
  • Usage:
const instance = new TcTcEmbed();

instance.setExtraVariablesForAllEmbeds({ youVariable: 'yourValue' });

setRequesterValueForAllEmbeds()

Set the value of one requester for all embeds

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

instance.setRequesterValueForAllEmbeds('APP_REPORT_REQUESTER_ID', 'Customer A');

insertEmbedById()

Important

This methods needs your SDK Key

Insert an Embed programmatically in the DOM. Returns a Promise of an Embed instance. Throws an Error if targetElement isn’t an HTMLElement.

  • Arguments:
    • {string} - embedId mandatory
    • {HTMLElement} - targetEl mandatory - targeted element to insert embed in
    • {Record<string, any>} - parameters
      • {string} - token - authenticate user for the embed
      • {string | Record<string, any>} - view
      • {string | Record<string, any>} - date
      • {boolean} - panel - display or not the additional panel
      • {boolean} - title - display or not the story’s title
      • {boolean} - compact - force display in compact mode when set to true
      • {string} - stage - get staging version when set to “staging”
      • {Record<string, any>} - variables
        • {Record<string, any} - extra
const instance = new TcTcEmbed('MY_DEVELOPER_KEY');

await instance.insertEmbedById(
    'MY_EMBED_ID',
    document.getElementById('parent-container'),
    {
        token: 'USER_TOKEN',
        variables: {
            extra: {
                foo: 'bar'
            }
        }
    }
);

get()

Returns a Promise of an Embed instance. Using DOMId rather than EmbedId could be useful if you’re using multiple times the same embed in a single page.

  • Arguments:
    • {string} - EmbedId or DOMId mandatory
    • {number} - max wait time in milliseconds default: 2000ms
  • Returns: Promise<Embed>
  • Usage:
const instance = new TcTcEmbed();

// 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);

createLayout()

Important

This methods needs your SDK Key

Allows to create an Embedded Dashboard programmatically Returns a Promise. Throws an Error if targetElement isn’t an HTMLElement.

  • Arguments:
    • {string} - layoutType mandatory - dashboard only for now
    • {string} - userToken - to authenticate the embed script
    • {string} - smallAppId mandatory - small app id to which we want to link the embed
    • {HTMLElement} - targetEl mandatory - targeted element to insert embed in
    • {Object} - extraParams
      • {string} - author - to specify when we want to linked the embeds to a specific user
      • {string} -  from - embedId to copy content from
  • Returns: Promise
  • Usage:
const instance = new TcTcEmbed('MY_DEVELOPER_KEY');
const userToken = localStore.getItem('toucanTocoToken');

instance.createLayout(
  'dashboard',
  userToken,
  'my_small_app',
  document.getElementById('embed-parent'),
  {
    author: 'jon@acme.com',
    from: 'EXISTING_DASHBOARD_EMBED_ID'
  }
)

retrieveAndInsertLayoutByAuthor()

Important

This methods needs your SDK Key

Allows to retrieve embed by author and insert it in a target element. Returns a Promise. Throws an Error if:

  • targetElement isn’t an HTMLElement
  • there are no embeds for specified author
  • Arguments:
    • {string} - author mandatory - username that owns the embed
    • {string} - userToken mandatory - to authenticate the embed script
    • {string} - smallAppId mandatory - small app id to which we want to link the embed
    • {HTMLElement} - tagetEl mandatory - targeted element to insert embed script
  • Returns: Promise
  • Usage:
const instance = new TcTcEmbed('MY_DEVELOPER_KEY');
const userToken = localStore.getItem('toucanTocoToken');
const username = 'user@self.com'

instance.retrieveAndInsertLayoutByAuthor(
  username,
  userToken,
  'my_small_app',
  document.getElementById('embed-parent'),
)

sendPDFReport()

Important

This methods needs your SDK Key

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 reciptients. Each list’s item is an object of token and variables. We’re using the tokens in order 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. Returns a Promise. Will throw an Error if at least one email didn’t reach its user.

  • Arguments:
    • {string} - smallAppId mandatory - PDF report’s small app id
    • {object[]} - users - list of recipient’s authentication token (and variables)
      • {string} - token mandatory - authentication token (in order to have user’s rights)
      • {object} - variables - to override global variables for specific users
    • {object} - variables - view or date app requesters or extraVariables used into the PDF report
  • Returns: Promise
  • Usage:
const instance = new TcTcEmbed('MY_DEVELOPER_KEY');
const my_users = [
  { token: 'AUTH_TOKEN_A' },
  { token: 'AUTH_TOKEN_B' },
  { token: 'AUTH_TOKEN_C', variables: { view: 'shop B' } },
]

instance.sendPDFReport(
  'my_small_app_id',
  my_users,
  { view: 'shop A' },
)

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

Event Emitter System

What’s for?

This module allow you to listen to Toucan Events in order to interact deeply with your embedded stories!

Important

Supported Charts:

  • Circularchart
  • Leaderboard
  • Linechart
  • Barchart
  • Barlinechart
  • Heatmap
  • Mapchart
  • Bulletchart
  • Stackedbarchart

Future

In a near future, we want to support more charts, more user interactions and give the possibility to set selection directly to unlock bi-directionality!

subscribe

Allow to listen to Toucan Events. Following events are available:

  • chart:selection: whenever the user select an element in a visualization (bar, bubble, zone, …)
  • chart:drill: whenever the user interact with a drillable element in a visualization (bar, bubble, zone, …)

Model

  • Arguments:
    • {TcEvent - eventName} mandatory - Toucan Events name
    • {function - callback} mandatory
  • Returns: Callback function
    • Payload:
      • {EventData - eventData}
        • {string - clickType} - The corresponding user interaction with the chart. Possible values are: “click” and “dblclick”. Only supported on Mapcharts.
        • {string - dataLabel} - The corresponding value in the column used for the label
        • {Record<string, any> - dataRow} - The corresponding data row to the user selection
        • {string - type} - Chart type selection (e.g: ‘zone’ for a Mapchart, ‘bar’ for a Leaderboard, …)
      • {Object - context}
        • {string - chartType} - Chart’s name
        • {string - embedId} - Embed Id
        • {number - storyId} - Embedded story id
        • {number - chartIndex} - Chart’s index position inside the embedded story
        • {object - drillInfo}
          • {Record<string, any> - children} - Children’s data
          • {string - type } - “drill”

chart:selection

const instance = new TcTcEmbed();

const embed = await instance.get('my_embed');

embed.subscribe('chart:selection', (payload) => {
    // do amazing stuff in your application!
});

chart:drill

const instance = new TcTcEmbed();

const embed = await instance.get('my_embed');

embed.subscribe('chart:drill', (payload) => {
    // do amazing stuff in your application!
});

unsubscribe

Destroy listeners to Toucan events.

  • Arguments:
    • {TcEvent - eventName} mandatory
  • Returns: void
  • Usage:
embed.unsubscribe('chart:selection');

Embed

refreshDataQueries()

Rerun queries for a given Embed.

  • Arguments:
    • N/A
  • Returns: void
  • Usage:
// My user perform an action that changes the data
// As developer, I want to refresh the data in the displayed story
const instance = new TcTcEmbed();
const embedDOMIds = instance.embedDOMIds();
const embed = await instance.get(embedDOMIds[0]);

embed.refreshDataQueries();

requesterIds()

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

setExtraVariables()

Set variables from external context for the embed.

  • Arguments:
    • {object} - externalVariables mandatory - variables that can be used in the embed content config
  • Returns: void
  • Usage:
embed.setExtraVariables({ youVariable: 'yourValue' });

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

// For hierarchical requesters, you have to describe all the hierarchy using ">>"
myViewRequester.setValue('Europe>>France>>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');