4.2. After reviewing your preview, you can add a unique name to your app instance and select “Save” to add the Playgrounds app into your managed apps in ScreenCloud.

Frequently Asked Question: Once you “Put” JSON data to ScreenCloud’s Application Data, how can you retrieve / request it back from ScreenCloud?

Generally, you’ll reference the JSON field you need with {data.FIELD} references in the JavaScript code of your Playgrounds application, replacing FIELD with your field’s name.

For example, in the "Big Number" Playgrounds template , the Javascript contains the following line:

/**  
Replacing getData(), this method retrieves the data associated with the app
*/

ScreenCloud.getAppData().then((data) => {
//passes retrieved data to render method
   render(data);
}).catch((error) => {
   console.log(`Failed to load application data - ${error}`);
});

ScreenCloud.getAppData is an asynchronous method that we provide in the static javascript, which is downloaded with the Playgrounds app, and it fetches any data associated with the app. In the code above, the data retrieved is then being passed into a render method which was defined in the app's JS. 

Playgrounds has always provided a function to load JSON-formatted data associated with the app instance. Previously this function was called getData and whilst that function is still supported, it should now be considered deprecated and Playgrounds apps should migrate to using ScreenCloud.getAppData instead.

Then, to reference the number in the app, that template includes a {data ? data.number : "123,456"} line that fetches the number field from Application Data, and includes a default number to display if that fields happens to not include data.

In order to provide a consistent interface and allow existing Playgrounds instances to be updated quickly, ScreenCloud.getAppData, like getData, is an asynchronous method that the calling code can call either with await or handle the Promise that is returned.

Use the Big Number template to experiment, and check our ScreenCloud Webhooks guide for more details.

Or, to build something more complex with your own tools and APIs, check out ScreenCloud’s Developer SDKs and GraphQL API.

5. Add the Playgrounds app to your digital screens

You can add the Playgrounds app to your screen directly by casting it, adding it into a playlist, scheduling into a channel, and more. Check our deep-dive on adding content to your ScreenCloud digital signage for more info.

To learn more about how to use ScreenCloud Playgrounds, book a ScreenCloud demo. Please let us know if you have any questions by emailing support@screencloud.com.

6. Playgrounds app limits and layout compatibility

Limits to the Playgrounds app

• Advanced app ability requires HTML, CSS and/or JavaScript knowledge
• App instances can not be shared across spaces

Channel and zone layout support for the Playgrounds app

• Main Zone: Yes
• Ticker Tape: Yes, though may not be ideal
• Side Bar: Yes
• Theme: Not directly. See our guides on CSS and the FAQ below

Frequently asked questions:

Q. What are some examples of things I could build with ScreenCloud Playgrounds?

Here’s a few examples we’ve seen Playgrounds used for:

• Custom branded dashboards - If you have a particular design you want to use on screens that is not covered by ScreenCloud templates or apps, using the Playgrounds app, you could build out the style you want.
• Custom weather app - Code a weather app that displays more in depth weather information than ScreenCloud’s dedicated weather app allows.
• Live video or photos - Connect to a live video stream for security monitoring, or upload images to your signage with a right-click.
• Bespoke metrics dashboards - Connect an internal database and turn it into a Dashboard on your screens. Check our guide to building a Chart.js-powered dashboard for an example.
• Siri and Google Assistant powered signage - Build a Playgrounds sign that shows text from webhooks, then build an Apple Shortcuts or Zapier-powered workflow so you can say anything to Siri or Google Assistant and have it show up on your signage.

Q. Can I connect to my own data source?

Yes, using ScreenCloud’s Application Data feature in the top right corner of the app and its Webhooks URL, you can connect ScreenCloud to any in-house database or external software.

Q. I'm having trouble getting my content on screen, what can I do?

Please ensure that you have saved your app instance by clicking 'Save' in the top right corner. You must do this before you can display your app on screens.

Q. How can you check the app is ready

Application Readiness

Due to the asynchronous nature in which the configuration, screen and theme information is loaded, it is best to check that the App is fully ready before performing any other operations.

We have provided two ways to accomplish this.

isAppReady

A one-time check on the status of the app, i.e. whether or not the necessary configuration, screen and theme information is available

if (ScreenCloud.isAppReady()) {
// Action
}

In this example, the action will only be performed if the necessary information has already been loaded at that specific point in time. Otherwise, the action will not be performed

onAppReady

Accepts a callback function that will be executed when the necessary configuration, screen and theme information is available

ScreenCloud.onAppReady(() => {
   //Action
});

In this example, the action will be performed once the necessary information becomes available, even if that means waiting for this condition to be met.

We recommend using onAppReady during the initialization of Playgrounds apps, which require configuration, screen and/or theme data.

Example

/**
 * Waits for the Playgrounds app to be initialized,
 * then executes the callback method supplied.
 */
ScreenCloud.onAppReady(() => {
  /**
   * Load the channel theme and use it to update the CSS variables
   */
  ScreenCloud.applyTheme();

  /**
   * Replacing getData(), this method retrieves the data associated with the app
   */
  ScreenCloud.getAppData()
    .then((data) => {
      // passes retrieved data to render method
      render(data);
    })
    .catch((error) => {
      console.log(`Failed to load application data - ${error}`);
    });
});

Q. How can you check the application is on screen?

Applications which are placed within Playlists or Channels are pre-loaded, off-screen, to ensure that they are ready, before being shown on screen. However, sometimes it is useful to know when the application is actually on screen, for example: when the app contains initial animations that will not be seen, if they are started when the app is pre-loaded.

Again there are 2 different methods available to help here.

isAppOnScreen

A one-time check on the status of the app, i.e. whether or not the app is currently on screen

if (ScreenCloud.isAppOnScreen()) {
// Action
}

In this example, the action will only be performed if the app is on screen at that specific point in time. Otherwise, the action will not be performed

onAppShown

Accepts a callback function that will be executed when the app is displayed on screen

if (ScreenCloud.isAppShown()) {
// Action
}

In this example, the action will be performed once the app is displayed on screen, even if that means waiting for this condition to be met.

We recommend using onAppShown for Playgrounds apps, which contain initial/loading animations

Example

/**
 * Allows functionality to be invoked when the app is displayed on screen
 * Use this method to start animations etc
 */

ScreenCloud.onAppShown(() => {
  // Start slideshow
  setInterval(() => {
    next = showSlide(next);
  }, duration * 1000);
});

Important

It is strongly recommended that all of the functions below only be called once the Playgrounds app has been confirmed to be ready, using either isAppReady or on AppReady as shown above.

Q. How can you retrieve / request Screen Data & the Screen Location?

getScreenData

This method allows accessing to all of the information that is available about the screen, including its location. Any custom key:value data pairs, which have been defined for the screen, will be available through this object.

This will return `undefined` if no screen data is available, which will happen in app preview.
If you want to see the Screen Data please preview on Screen and add a key:value to the Screen.

Example

const data = ScreenCloud.getScreenData();
if (data && data.myKey) {
// Custom Data Action
}

getScreenLocation

This method returns a reduced set of the screen data containing only the values relevant to the screen’s location

This will return `undefined` if no screen data is available, which will happen in app preview.
You will only be able to preview the Screen Location in Studio Screen Preview or on the Screen itself.

// If screen data is available, this will return an object
// in the following format:
// {
//  address: string || undefined,
//  country: string || undefined,
//  locality: string || undefined,
//  longitude: string || undefined,
//  latitude: string || undefined,
// }
const location = ScreenCloud.getScreenLocation();
if (location && 
    location.longitude && 
    location.latitude) {
	// Location Specific Action
}

Q. How can you use the Channel theme within the app code?

There are many different aspects to a channel theme and, in some cases, it may be useful to be able to access the individual property values, so we have provided an accessor method for each of those. However, we also provide a convenient method for loading the entire theme into the Playgrounds app, called applyTheme

The individually property methods will return undefined if no theme is available, which will happen if the app is viewed or preview outside of a Channel

getPrimaryColor

Returns the hex code for the configured Primary Color of the current theme

const primaryColor = ScreenCloud.getPrimaryColor();

getSecondaryColor

Returns the hex code for the configured Secondary Color of the current theme

const secondaryColor = ScreenCloud.getSecondaryColor();

getTitleFontColor

Returns the hex code for the configured Title Font Color of the current theme

const titleFontColor = ScreenCloud.getTitleFontColor();

getBodyFontColor

Returns the hex code for the configured Body Font Color of the current theme

const bodyFontColor = ScreenCloud.getBodyFontColor();

getTitleFontFamily

Returns the font family configured for the Title Font of the current theme

const titleFontFamily = ScreenCloud.getTitleFontFamily();

getBodyFontFamily

Returns the font family configured for the Body Font of the current theme

const bodyFontFamily = ScreenCloud.getBodyFontFamily();

getTitleFontURL

Returns the URL for the font file that corresponds to the font selected for the Title Font. An example of loading the font file is provided, but this can also be achieved by calling

const titleFontURL = ScreenCloud.getTitleFontURL();

// Use the URL to load the font file
if (titleFontURL) {
  const link = document.createElement("link");
  link.setAttribute("rel", "stylesheet");
  link.setAttribute("href", titleFontURL);
  document.head.appendChild(link);
} else {
  console.log("No Title font url available to load");
}

getBodyFontURL

Returns the URL for the font file that corresponds to the font selected for the Body Font. An example of loading the font file is provided, but this can also be achieved by calling loadThemeFonts

const bodyFontURL = ScreenCloud.getBodyFontURL();

// Use the URL to load the font file
if (bodyFontURL) {
  const link = document.createElement("link");
  link.setAttribute("rel", "stylesheet");
  link.setAttribute("href", bodyFontURL);
  document.head.appendChild(link);
} else {
  console.log("No Body font url available to load");
}

getLogoURL

Returns the URL configured as the Logo for the current theme

const logoURL = ScreenCloud.getLogoURL();

loadThemeFonts

If you wish to use the channel theme fonts, within your Playgrounds application, but don’t require any of the other theme properties, then you can use loadThemeFonts. This will dynamically add link elements into the HTML that load the font files. The font family can be referenced, via CSS, as required.

ScreenCloud.loadThemeFonts();

applyTheme

This is a single, convenient method for loading all of the theme information in one go and applying it to your Playgrounds app. In order for the method to take full effect, some bootstrapping CSS code is required.

This code creates CSS variables for each of the theme properties and then sets some initial styles using those variables.

/**
 * Setup for applying Theme to this App
 */
:root {
    /* Default values used if no theme available */
    --primaryColor: #222222;
    --secondaryColor: #444444;
    --bodyFontColor: #eeeeee;
    --bodyFontFamily: "serif";
    --titleFontColor: #eeeeee;
    --titleFontFamily: "sans-serif";
    --logoURL: "none";
}

body {
    color: var(--bodyFontColor);
    font-family: var(--bodyFontFamily);
}

h1, h2, h3, h4, h5, h6 {
    color: var(--titleFontColor);
    font-family: var(--titleFontFamily);
}

.primary {
    background-color: var(--primaryColor);
}

.secondary {
    background-color: var(--secondaryColor);
}

.logo {
    background-repeat: no-repeat;
    background-size: contain;
    background-image: var(--logoURL);
}

/* End of Theme setup */

When applyTheme is called, it checks for these same CSS variables and, if found, updates their values to those of the current channel’s theme.
NB: applyTheme will also invoke loadThemeFonts

/**
 * Replacing getData(), this method retrieves the data associated with the app
 */
ScreenCloud.getAppData()
  .then((data) => {
    // passes retrieved data to render method
    render(data);
  })
  .catch((error) => {
    console.log(`Failed to load application data - ${error}`);
  });

After the theme has been applied, if you would like, for example, to display the theme’s logo, you can add an empty HTML div element, with the logo class, and style it with appropriate dimensions

.logo {
  height: 200px;
}

When added to a channel with a theme that has a logo, the app will add the logo image as the background for the div, with a height of 200 pixels and scaled appropriately