TVS IFrame API

Starting with Television Simulator 5.6.0, developers can access options from the TVS config file to use in their web applications. This allows TVS users to have an easy way to pass JSON data from TVS to your web application.

We use Window.postMessage() and IFrames to enable two-way communication between TVS and your application.

Handshake Process

Since: TVS 5.6.0

Your application is in control of when to start the handshake process with TVS; this is so you can ensure your app is fully loaded and ready before attempting to communicate with TVS.

To perform the handshake, your application should send a TVS.Ready message to the parent window (TVS) using the following code:

window.parent.postMessage({'type': 'TVS.Ready'}, '*');

Once TVS receives this message, it will respond with a TVS.Options message containing the configuration data.

window.addEventListener('message', (event) => {
    if (event.data.type === 'TVS.Options') {
        const options = JSON.parse(event.data.options);
        // Use the options as needed
    }
});

event.data.options will contain a JSON string of the IFrame options defined in the TVS config file.

Caution

To ensure consistency, TVS will always send the options even if no options were defined. In such cases, the options will be an empty JSON object: {}.

Options Format

Since: TVS 5.6.0

The options JSON string should resolve to a dictionary of key-value pairs. The keys will be strings.

The values can be of various types, including:

• Strings
• Numbers
• Booleans
• Arrays
• Nested objects

Note

TVS does not perform any type validation on the options; it’s up to your application to handle and validate the data as needed.

Caution

Remember that you define the structure and types of the options in your application. Users will need to follow your documentation on how to set up the options correctly in the TVS config file.

Example Usage

Imagine you’re building a weather application that can display information for different cities and you’d like to allow users to set their preferred locations via TVS. You might decide to accept a list of city names as an IFrame option.

Suppose you wanted to accept a list of cities like this:

{
    "cities": ["New York", "Los Angeles", "Chicago"]
}

You’ll instruct your users to add this YAML to their TVS config file:

channels:
- number: 1
  name: "My Cool Weather App"
  iframe:
    src: "https://mycoolweatherapp.example.com"
    options:
      cities:
        - "New York"
        - "Los Angeles"
        - "Chicago"

Upon handshaking, your application will receive an event like this:

{
    type: 'TVS.Options',
    options: '"cities":["New York","Los Angeles","Chicago"]'
}

Integration with TV State

Since: TVS 5.7.0

In addition to TVS.Options, your application can also listen for other status messages from TVS:

• TVS.Volume: Reports the current volume level (from 0 to 100).
• TVS.Mute: Indicates whether the TV is muted.
• TVS.Power: Indicates whether the TV is on or off.

These messages will be sent automatically during the initial handshake and whenever the state changes in TVS.

Example that listens for these messages:

if (window.parent && window.parent !== window) {
    // Only attempt to handshake with TVS if we're in an IFrame.
    // Set up an event listener before attempting a handshake so that you're ready to receive the reply.
    addEventListener('message', function(event) {
        // These are the expected events from TVS when sending `TVS.Ready`

        switch(event?.data?.type) {
            case 'TVS.Options':
                console.log('Received options string:', event.data.options);
                const parsedOptions = JSON.parse(event.data.options);
                console.log('Parsed options object:', parsedOptions);
                // Use the options as needed
                break;

            case 'TVS.Volume': // Sent when volume changes and during handshake
                const volume = parseFloat(event.data.volume);
                // Update your app's volume accordingly; event.data.volume is between 0 and 100
                break;

            case 'TVS.Muting': // Sent when mute state changes and during handshake
                if (typeof event.data.isMuting === 'boolean') {
                    const isMuting = event.data.isMuting;
                    // Update your app's mute state accordingly
                }
                break;

            case 'TVS.Power': // Sent when power state changes and during handshake
                if (typeof event.data.isOn === 'boolean') {
                    const isOn = event.data.isOn;
                    // Update your app's power state accordingly
                }
                break;

            // As the API evolves, more message types may be added here.

            default:
                // Ignore other messages
                break;
        }
    });

    // To attempt the handshake, post `TVS.Ready` event:
    window.parent.postMessage({'type': 'TVS.Ready'}, '*');
}

Security Considerations

When implementing the IFrame API, it’s crucial to consider security implications:

• Always validate and sanitize the data received from TVS to prevent potential security vulnerabilities.
• Be cautious when using the wildcard '*' in the postMessage method; consider specifying the exact origin of TVS if known. (If you are hosting TVS yourself and know where it will be accessed from, you can specify that URL instead of '*'. If you’d like anyone to be able to use your app with any TVS instance, you can leave it as '*'.)
• Implement proper error handling to manage unexpected messages or data formats.

Test Application

To help you get started with the TVS IFrame API, we’ve created a simple test application that demonstrates how to use the API to receive options from TVS.

It’s a single-file HTML file to make it easy to read. View the source code to see how it works and use it as a reference for building your own applications.