Using Sendables

In some interactive videos, your viewers’ decisions may culminate into some final, tangible “take-away”, like a recipe or a shopping list they’ve compiled throughout playback. The sendables plugin can be used to dynamically generate content that your viewers can then email to themselves or download as a pdf.

Getting Started with Sendables

Imagine we are creating an interactive video where the viewer can select the background music of different scenes. At the end of the video, we would like our users to be able to email themselves the playlist they’ve created.

There are 3 parts to using the sendables plugin:

  1. Creating HTML Templates and JSON Schemas
  2. Defining Targets
  3. Using the API (populating the HTML templates with data)

Folder Structure and Naming Conventions

Firstly, checkout a local copy of your Eko Studio project, if you haven’t done so already. Once the project is checked out, create a src/sendables/ folder that will hold all of the HTML templates. Sendables leverages handlebars to hydrate and render HTML templates. Every HTML page has a corresponding json schema. Sendables will validate the context against this schema, and then render the template. Any assets used in the template should be placed under an assets/ folder inside of src/sendables/.

Your folder structure should look like this:

|-- src
    |-- _eko_
    |-- sendables
        |-- config.json
        |-- myPlaylist.html
        |-- myPlaylist.json
        |-- partials
            |-- songInfo.html
        |-- assets
            |-- logo.png

(Note that partials are supported and encouraged!)

Creating the HTML Templates

These templates will determine the layout and style of the information the viewer will see. You may have multiple templates in your project for different layouts, or for different emails/pdfs the user may want to generate.

If you are including images in your partials, please use our provided helper - {{#image "relative_path_to_image" }} {{/image}} - instead of the standard html <img> tag.

Continuing with the playlist example, we have a partial songInfo.html, that looks like:

<div class="songInfo">
    <h2>{{songTitle}}</h2>
    <p class="artist">{{artistName}}</div>
    <p class="albumLink"><a href="{{albumLink}}">Album Link</a></p>
    <p class="price">Album price: {{albumPrice}}</p>
</div>

and myPlaylist.html:

<!-- myPlaylist.html -->
<div class="songList">
    {{#each songs}}
        {{> songInfo this}}
    {{/each}}
</div>

Creating the JSON Schemas

When the above template is populated, we know it should have an array of song information objects, and each song info object should have a string for the title, artist, and link, and a number for the album price. This type checking will be defined in myPlaylist.json, and will look like this:

// myPlaylist.json
{
  "type": "object",
  "properties": {
      "songs" : {
          "type" : "array",
          "items" : {
                "type" : "object",
                "properties" : {
                    "songTitle": {
                        "type": "string"
                    },
                    "artistName": {
                        "type": "string"
                    },
                    "albumLink": {
                        "type": "string"
                    },
                    "albumPrice": {
                        "type": "number"
                    }
                },
                "required": [
                    "songTitle",
                    "artistName",
                    "albumLink",
                    "albumPrice"
                ]

          }
      }
  }
}

If the data passed in does not match the json schema, the request to render the HTML template will fail. We encourage using a json schema generator to create the json schema.

Defining Targets

Targets must be defined within src/sendables/config.json. The target determines the format (html or pdf) and type (email or link). Each target should have a unique id, so that it can be referenced via the plugin. You may define multiple targets. Note that if defining an email target, you must also supply a subject title and from object.

// config.json
{
    "targets" : {
        "myMailTarget" : {
            "type" : "email",
            "format" : "html",
            "subject" : "You created a playlist of {{numSongs}} total songs!",
            "from" : {
                "name" : "Playlist Creators",
                "address" : "playlist@email.com"
            }
        },
        "myPdfTarget" : {
            "type" : "link", // default orientation is Letter/ portrait
            "format" : "pdf"
        },
        "myPdfTargetA4Landscape" : {
            "type" : "link",
            "format" : "pdf",
            "orientation": "landscape", // OR portrait
            "paperSize": "A4"           // allowed units: A3, A4, A5, Legal, Letter, Tabloid
        },
        "myPdfTargetSized" : {
            "type" : "link",
            "format" : "pdf",
            "height": "10.5in",        // allowed units: mm, cm, in, px
            "width": "8in",            // allowed units: mm, cm, in, px
        },
        "myLinkTarget" : {
            "type" : "link",
            "format" : "html"
        }
    }
}

Using the API

Once you have defined your HTML templates, corresponding json schemas, and targets, you can then proceed to use the sendables plugin to generate dynamic content. The following example shows how to generate an email with a playlist of songs. For an email, within the target object, you must supply a recipient for the email and provide any data required for the subject line (defined in config.json).

// Imagine in this project, there is some custom UI to enter an email
// address and a "send email button". When the button is clicked, 
// an event is fired, and we use the sendables plugin to send the
// email to the given address.
player.on('myProject.onSendEmailButtonClicked', (viewersEmailAddress) => {
    player.sendables.generate(
        'myPlaylist.html',                      // template
        { songs: [                              // context
            {
                songTitle: 'Imagine',
                artistName: 'John Lennon',
                albumLink: 'https://www.google.com/',
                albumPrice: 12.99
            },
            {
                songTitle: 'Yesterday',
                artistName: 'The Beatles',
                albumLink: 'https://www.google.com/',
                albumPrice: 9.99
            }
        ]},
        {                                       // target
            id: 'myMailTarget',                 // target id
            data: {                             // target data (recipient of the email, subject data)
                to: viewersEmailAddress,
                subject: { numSongs: 2 }
            }
        }
    );
});

Generating a downloadable PDF does not require any additional data passed to the target, and it can be opened automatically in a new tab.

// Alternatively, imagine there is some custom button 
// that simply allows you to download a PDF. When the button
// is clicked, an event is fired, and we use the sendables
// plugin to create and open the pdf.
player.on('myProject.onDownloadPdfButtonClicked', () => {
    player.sendables.generate(
        'myPlaylist.html',                      // template
        { songs: [                              // context
            {
                songTitle: 'Imagine',
                artistName: 'John Lennon',
                albumLink: 'https://www.google.com/',
                albumPrice: 12.99
            },
            {
                songTitle: 'Yesterday',
                artistName: 'The Beatles',
                albumLink: 'https://www.google.com/',
                albumPrice: 9.99
            }
        ]},
        {                                       // target
            id: 'myPdfTarget'                   // target id
        },
        {                                       // options
            open: true
        }
    );
});

Note: It’s likely that you will not be hardcoding the context. Check out how to use the variables plugin to save information throughout playback and access it at a later point.

Testing Sendables

During development, you will want to verify that your json schemas and templates are working as expected. Using the eko-cli, you will be able to preview what your templates look like with data. To test sendables, simply run the following command from the root of the project:

eko sendables test --template=your_template_file_name --context=relative_path_to_your_context_file

Note: The template argument is required. If the context argument is not provided, it will be taken from the context.json file at your sendable directory.

For the example above your context.json file should look like this:

{ 
    "songs": [
        {
            "songTitle": "Imagine",
            "artistName": "John Lennon",
            "albumLink": "https://www.google.com/",
            "albumPrice": 12.99
        },
        {
            "songTitle": "Yesterday",
            "artistName": "The Beatles",
            "albumLink": "https://www.google.com/",
            "albumPrice": 9.99
        }
    ]
}

If the supplied context is successfully validated against the schemas, this command will automatically open the compiled html file in your browser (served from a local server), any changes made in the context or template source files will trigger re-compilation of the template, you can see the changes by refreshing your browser.

Helpful Resources

Developing HTML for emails can sometimes be tricky. Here are a few helpful resources to get you started:

New to email coding? Here’s where to start
Mailchimp Email Best Practices
Build an HTML Email Template From Scratch
CSS Support Guide

Rate this page: X
Tell us more!