How to :: pass external variables to my embeds


Sometimes you may want to pass variables to your embed without having to declare them inside Toucan Toco because it depends on a specific context on your application.

To do so, you can pass down your variables in embeds scripts:

<script async src="\"foo\"" type="text/javascript"></script>

As you can see, you can add any key to our variables parameter. If you have to pass 2 parameters for instance, you’ll have to write:

<script async src="\"foo\"&variables.my_var2="[\"foo\", \"bar\"]"" type="text/javascript"></script>


In order to support object and array type, we’re parsing each variables. Make sure you have encoded it well (ex: using JSON.stringify)

When it comes to passing down a lot of variables, including object and array, we’re suggesting encoding a complete variables object and declaring all those extra variables into the extra key as following:

var formattedVariables = JSON.stringify({
  extra: { // super important to put all you variables under the "extra" key
    varA: "simple_string",
    varB: 42,
    varC: {
      childrenKey: "str"
    varD: ["itemA", "itemB"]

// then used it programatically
var script = document.createElement('script');

script.src = `${formattedVariables}`

// append it to your body or you parent div/component

// or in template
<script async src=`${formattedVariables}` type="text/javascript"></script>


Setup in a story

After that, you can use your variables in the configuration of your story. Thanks to extraVariables you can template your variable inside the story. For example, you can set a contextual commentary.



Now you’ve got an error because the variables aren’t interpolated !



Note that you can display a default value to avoid that state.



You should now have default value interpolated.



Setup embed-side

Setting this:

<script async src="{EMBED_ID}&variables.commentary=\"I am here to describe that amazing story!\"" type="text/javascript"></script>

We’ve got this: extra-variables-result

Dynamic update

You can use our SDK to update extraVariables dynamically its values when you want to linked them to UI components from your own application.

const instance = new TcTcEmbed();

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

Link to API

You can also set it for a specifif embed script.

embed.setExtraVariables({ youVariable: 'yourValue' });

Link to API

You’ve got a Live Example right there: