โ๏ธ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 betweenembedId
+ a random hash. It allows you to integrate the same embed on the same page several times.
Example:
Filters
We will also talk about Filters.
TcTcEmbed
The script will attach to window
our TcTcEmbed
object, ready to be created.
getAll()
Returns an array of HTMLElement
for each embed on the page.
Parameters
N/A
Returns
HTMLElement
Example
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
Example
setExtraVariablesForAllEmbeds()
Set variables from external context for all embeds
Parameters
parameter | type | mandatory | Description |
---|---|---|---|
| object | โ | Variables that can be used in the embed content config |
Returns
void
Example
setFilterValueForAllEmbeds()
Set the value of one requester for all embeds.
Parameters
parameter | type | mandatory | Description |
---|---|---|---|
| string | โ | Id of the Filter you want to change value |
| object | โ | The new value for the filter |
Returns
void
Example
insertEmbedById()
Insert an Embed programmatically in the DOM.
Important
This method needs an authentication token (cf. Embed SDK Authentication)
Parameters
parameter | type | mandatory | Description |
---|---|---|---|
| string | โ | Id of the embed you want to insert |
| HTMLElement | โ | Container on which will insert the embed id |
| string | โ | Token used to authenticate user |
| Record<string, any> | โ | Initial values for Filters. |
| boolean | โ | Display or not the additional panel |
| boolean | โ | Display or not a storyโs header |
| boolean | โ | Force display in compact mode when set to |
| string | โ | Get staging version when set to "staging" |
| Record<string, any> | โ | Arbitrary variables that you can use inside Toucan embeds |
Returns
Success:
Promise<Embed>
Error
when
targetEl
isn't anHTMLElement
Example
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
parameter | type | mandatory | Description |
---|---|---|---|
| string | โ | Id or DOMId of the embed |
| number | โ | Max wait time in milliseconds before stopping to search for an embed in the DOM (default: 2000ms) |
Returns
Promise<Embed>
Example
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
parameter | type | mandatory | Description |
---|---|---|---|
| string | โ | PDF Report's Small App URL
Example: if your small app is accessible with the URL |
| string | โ | Token that authenticates user |
| Record<string, any> | โ | Override global variables for specific users |
reportId | string | โ | Report ID. Can be find in the URL of a given PDF report |
| Record<string, any> | โ | Filters or extraVariables used into the PDF Report |
Returns
Success:
Promise
.Error:
if at least one email didnโt reach its user.
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
filterIds()
Returns all the requester ids for a given Embed
Parameters
N/A
Returns
string[]
Example
getFilter()
Return a Filter
for a given Embed
Parameters
parameter | type | mandatory | Description |
---|---|---|---|
| string | โ | Filter's id |
Returns
Filter
Example
setExtraVariables()
Set variables from external context for a given Embed
Parameters
parameter | type | mandatory | Description |
---|---|---|---|
| object | โ | Variables that can be used in the embed content config |
Returns
void
Example
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
parameter | type | mandatory | Description |
---|---|---|---|
| TcEvent | โ | Toucan Event's name |
| function | โ | Token that authenticates user |
Callback function returns
EventData
parameter | type | Description |
---|---|---|
| string | The corresponding user interaction with the chart. Possible values are: โclickโ and โdblclickโ. |
| Record<string, any> | The corresponding data row to the user selection |
| string | The corresponding value in the column used for the label |
| string | Chart type selection (e.g: โzoneโ for a Mapchart, โbarโ for a Leaderboard, โฆ) |
Context
parameter | type | Description |
---|---|---|
| string | Chart's name |
| string | Embed Id |
| string | Story / Tile / Dashboard id |
| number | Chartโs index position inside an embedded story |
| Object | |
| Record<string, any> | Childrenโs data |
| string | Always equals "drill". |
chart:selection
chart:drill
unsubscribe
Destroy listeners to Toucan events.
parameter | type | mandatory | Description |
---|---|---|---|
| TcEvent | โ | Toucan Event's name |
Returns
void
Example
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
currentValue()
Return the current value for a given Filter
Parameters
N/A
Returns
Record<string, any>
setValue()
Set the current value for a given Filter
Parameters
parameter | type | mandatory | Description |
---|---|---|---|
| any | โ | A value that is available in the Filter values |
Returns
void
Example
Last updated