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

get()

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

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 script
    • {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.

Embed

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

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