API Documentation

English
- English
- German

IXM Webhelp
11.18 11.17 11.16 11.15 11.14
DOOH Webhelp
11.18 11.17 11.16 11.15 11.14

GFSpotBase

18 Dec 2023
13 Minutes to read

GFSpotBase

Updated on 18 Dec 2023
13 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback

The GFSpotBase is a basic class for locally played HTML spots and offers a variety of methods by means of which you can communicate with the Grassfish Player. This is a JavaScript Lib, which must be integrated into the local website. It can be used both by HTML Wizard spots and by HTML Basic spots.

Note

As of GFSpotBase version 2, it is necessary for the spot to independently invoke sendInitComplete when it is ready to be displayed. Otherwise, the player doesn't bring it to the foreground.

Use

The file gfSpotBase.js is allowed to be nested in subdirectories but should not be edited. Insert the file by means of a script tag into the website:

<script src="gfSpotBase.js"></script>

Make sure that you insert this script before any other scripts that relate to the player functionalities. Furthermore, you are not allowed to access the GFSpotBase methods until the JavaScript file has actually been initialized. To do so, use the body onload method:

<body onload="init()">
function init()
{
alert(GFSpotBase.getVersion());
}

Functions for player interaction

The GFSpotBase offers a multitude of methods by means of which you can communicate with the Grassfish Player. The individual functions are explained in this subsection.

The GFSpotBase class reserves two variables within the global scope of JavaScript:

var GFSpotBase is the class itself. All methods to be used are invoked statically via this category.
var grassfishGlobalPlayerToJSCallbackFunction is a central method that serves as a call-back for communication with the player. This method is not allowed to be directly manipulated or used by the HTML developer. For each supported call-back, there is a respective wrapper method that can be used here.

Only two parameters are ever transferred to the player: the method key and the remaining arguments. The remaining arguments are joined by means of a separator prior to being transferred to the player. On no account is this separator allowed to be used in the parameter values. It reads: | + _-* |

Reporting to the player that the spot is ready

Function	Gives players from version 10 the signal that the spot is ready to be played. This method invocation has no influence on the players of earlier versions; in the latter cases, the spot continues to be played immediately.
Parameters	None
Examples	GFSpotBase.sendInitComplete();
Players	Windows/Linux from global version 10.0 Android from player version 8.1.0.2

Terminating the spot

Function	Closes the current spot.
Parameters	None
Examples	GFSpotBase.quit();
Players	Windows from global version 7.7 Linux from global version 8.0 Android from player version 8.1.0.0

Jump to the next spot with the name X

Function	Jumps to another spot within the current playlist (if it is present). If several spots with the same name are present in the playlist, a jump is made to the first spot that follows the current spot.
Parameters	function (spotName, jumpBack) spotName is the name of the spot to which a jump is made.
Examples	GFSpotBase.jumpToSpot("Spot ABC"); GFSpotBase.jumpToSpot("News", true);
Players	Windows from global version 7.7 Linux from global version 8.0 Android from player version 8.1.0.0 jumpBack parameter support: Windows from global version 10.0.10 Linux from global version 10.1.3 Android from player version 10.1.0

Jump to a specific spot

Function	Jumps to another spot within the current playlist (provided that it is present). This method requires the spot instance ID, which is unique, so that you can jump to this actual spot even if a spot occurs several times in the playlist. With the second parameter (jumpBack) you return to the invoker spot after completion of the spot that has been jumped to. The spot instance IDs can be polled by the player by way of the getAllSpots method.
Parameters	function(siId, jumpBack) siId is the unique spot instance ID of the spot to which the jump is being made. jumpBack specifies whether one would like to return to the invoker spot again after playing the target spot.
Examples	GFSpotBase. jumpToSpotBySiId("3242", true);
Players	Android from player version 8.1.0.0

Triggering a player event

Function	Starts an event playlist on the player.
Parameters	function(eventType, value) value is the Event ID of the playlist eventType can have the following values: Start: Starts an event playlist that is played once. StartLoop: Starts an event playlist that continues to play in a loop. StopLoop: Terminates a loop event playlist.
Examples	GFSpotBase.sendEventCommand("Start","EventA"); GFSpotBase.sendEventCommand("StartLoop","EventB");
Players	Windows from global version 7.7

Communication between spots

Spot-to-spot communication enables spots in different splits on different players to communicate with one another; for example, in order to synchronize their contents.

Sending a message to another spot:

Function	Sends a spot-to-spot message to another player or split:
Parameters	function(ip, uniqueID, value) ip is the IP of the player to which the message is to be sent. uniqueID is for the purpose of differentiating between various messages value is the actual message itself in the form of a string. The string can also contain XML or JSON data; the important thing is that the sender spot and the receiver spot agree to the same structure.
Examples	`GFSpotBase.sendSpotToSpotMessage("127.0.0.1","ProductSelectedEvent","<product><id>243</id><name>Some Product Name</name></product>"); GFSpotBase.sendSpotToSpotMessage("192.168.0.50","NewsDisplayCurrentPageEvent","3");`
Players	Windows from global version 7.7 Windows/Linux from player version 10.1

Receiving a message from another spot

In order that spot-to-spot messages can be received in the HTML application, the reception method must be overwritten first and the player must then be advised that the spot is interested in spot-to-spot messages. This takes place best of all by way of the init() method after the <body onload="init()">.

function init()
{
//Override the receiver function
GFSpotBase.receiveSpotToSpotMessage = function(uniqueID, value)
{
	//do something
};

//Tell the player that you are ready to receive spot to spot messages
GFSpotBase.readyForSpotToSpotMessage();
}

Function

Is invoked by the player, when a spot-to-spot message is sent to the spot.

Parameters

function(paramId, paramValue)

uniqueID is for the purpose of differentiating various messages from one another.

value is the actual message itself in the form of a string. The string can also contain XML or JSON data; the important thing is that the sender spot and the receiver spot agree to the same structure.

Players

Windows from Global Version 7.7

Windows/Linux from player version 10.1

Sending an email via the player

Function	Sends an email via the player.
Parameters	function(headerText, bodyTextLines, email) headerText is the subject of the email. bodyTextLines is an array of lines for the body. email If '@' is included, the email is sent to this address. Otherwise the value is written in the body and the email is sent to the email address that is defined in the config file on the player.
Examples	GFSpotBase.sendEmail("Some subject", ["Some body"], "example@domain.com");
Warning	This function must be configured and activated on the player. All values are transferred to the player separated by a separator ('_\|_') This separator must therefore not be used in the values of the parameters.
Player	Windows from global Version 7.7 Windows/Linux from player version 10.1

Statistics

Recording statistics (on the player)

Function	With this function, it is possible for the spot to collect statistical information. A CSV file with the data is created on the player; this is transferred once daily to the server. Multiple values can be separated by a semicolon ';' . On the Qt Linux Player, the data is stored in the fs_select table in the statistics database. Path: /opt/grassfish/data/db/stats.db On the server, the information is stored in a monthly CSV file named 'yyyymm.csv' (e.g. '201705.csv'). Path: \data\CustomerId\export\select, e.g. \\dev1\GVServer2.dev4\data\1\export\select
Parameters	function(value) value is either a value or several values separated by a semicolon, which are recorded in the CVS file.
Examples	The app name, a product ID 547 and a timestamp are transferred in this case: GFSpotBase.writeStatistic("ProductSelector;547" + ";"+new Date().getTime());
Players	Windows from global version 7.7 Linux from global version 8.0 Android from player version 8.1.0.0

Sending statistics reports

Function	This function allows the spot to send statistical information to the server. The server collects this data which can then be displayed graphically with a report plugin and a Dashboard addon.
Parameters	function(action, value, dynamicValues, spotIdentifier, sessionIdentifier, pluginGuid) action is the name for the statistics entry (string) value is the value to be stored (string) dynamicValues allows you to store additional information (optional, key-value object) spotIdentifier allows you to assign recorded data to a certain spot. (optional, string). sessionIdentifier allows you to assign recorded data to a certain user who owns a session assigned to him (optional, string). pluginGuid allows you to store reports in a dedicated area on the server. However, the area must be created beforehand and the assigned pluginGuid must be known.
Examples	The number of clicks on a product should be logged for later evaluation. For this purpose, the type of action and a value e.g., a product ID must be transferred: GFSpotBase.writeSpotReport("Clicked", "547"); Optionally, additional files can be attached. In this case, the area from where the product was clicked is also included: `GFSpotBase.writeSpotReport("Clicked", "547", { area: "ProductList" });` Entries can be assigned to a specific spot by defining a spotIdentifer: GFSpotBase.writeSpotReport("Clicked", "547", null, "ProductSelector"); When spots have their own session that allows e.g., authorizing users, then the session ID can be transferred as well. This allows assigning information to users and to thus deduce e.g., the purchasing behavior: GFSpotBase.writeSpotReport("Clicked", "547", null, "ProductSelector", "ddc5d323-9447-41f0-8898-266c486bdddc");
Player	Windows & Linux Player from 11.2.0

Sending a heartbeat

Function	By means of this function, the spot can send a heartbeat impulse to the player to monitor whether the spot is functioning properly. The heartbeat for a spot is 'activated' upon the initial transmission of the heartbeat to the player. Up to then the player assumes that the spot does not support a heartbeat and the player does not monitor the spot to that effect. When a heartbeat is sent, we recommend adding a small buffer. Set the interval, for example, to 10 seconds. You should send the heartbeat again after 4 seconds so that the player does not mistakenly terminate the spot, if a request fails to arrive.
Parameters	function(interval) interval is the interval (in milliseconds) after which the player terminates the spot, if no repeat heartbeat has been sent by then.
Examples	The following call communicates to the player that the spot will be sending a repeat heartbeat in 10 seconds at the latest: GFSpotBase.sendHeartbeat(10000);
Players	Windows from global version 8.0 Linux from global version 8.0 Android from player version 8.1.0.0

Logging a message

Function	By means of this function it is possible for the spot to transfer log messages to the player.
Parameters	function(msg, level) msg is a string that is written to the player log files. We recommend specifying the name of the HTML application in order to facilitate debugging. severity is the degree of severity of the error and is optional. The degree of severity can have one of the following values: Error, Warning, Info, Debug.
Examples	GFSpotBase.sendLog("HTMLApp Error: " + message, GFSpotBase.logLevels.ERROR);
Players	Windows from global version 7.7 Linux from global version 8.0 Android from player version 8.1.0.0

Saving and reading files on the hard drive

The player enables the application to write data to the hard disk and to either read it from the application itself or from another application.

Writing a file to the player

Function	Writes a file to the player.
Parameters	function(directory, fileName, data) directory is the subdirectory in which the file is stored. fileName is the filename of the file. Depending on the desired content the file extension can be, among others, .json or .xml. data are the actual data themselves in the form of a string. The string can also contain XML or JSON data; the important thing is that all spots that want to use this file agree to the same structure.
Examples	GFSpotBase.writeFile("sampleData/","sample.xml","<product><id>243</id><name>Some Product Name</name></product>");
Players	Windows from global version 7.7 Linux from global version 8.0 Android from player version 8.1.0.0

Reading a file from the player

For the data of a previously saved file to be able to be loaded into the HTML application, the method GFSpotBase.receiveOnReadFile must first be overwritten. This takes place best of all by way of the init() method after the <body onload="init()">.

function init()
{

//Override the receiver function
GFSpotBase.receiveOnReadFile = function(fileName, data)
{
	//do something with the data
};

//Request the data
GFSpotBase.readFile("sampleData/","sample.xml");
}

Function	Requests a file from the player. This invocation takes place asynchronously:
Parameters	function(directory, fileName) directory is the subdirectory in which the file has been stored. fileName is the filename of the file. Depending on the desired content, the file extension can be, among others, .json or .xml.
Examples	GFSpotBase.readFile("sampleData/","sample.xml");
Players	Windows from global version 7.7 Linux from global version 8.0 Android from player version 8.1.0.0

Activating preloading for the spot

For the seamless cross fading of a spot, it is necessary for the spot to have already completed more cost-intensive loading processes when the spot is displayed on the player. As a result, you achieve seamless display of the spot after the previous spot—provided that you have configured the playlist in Grassfish IXM Platform accordingly. The spot already makes this known during the upload to the server by providing a variable in the file settings.xml. To archive this function, you must create a file with the name settings.xml in the zip archive.

If you activate preloading in the spot, the spot itself must ensure that its animations start when the player gives the command to do so. This takes place via receivePlayCommand(value); method. The animations must be started by this method only. Otherwise, they will start too early and will already be in the middle of playing when the spot is displayed. The player communicates to the HTML application via a URL parameter with the name usePreload=true whether the player supports preloading. If this parameter is not set, the animations must be started immediately after invocation of the site.

Using the init() method after the <body onload='init()'> is recommended here as well.

function init()
{
resetAnimations(); //your own implementation to reset all animations

	GFSpotBase.receivePlayCommand = function(value)
	{
		log("Got Play command: " + value);
		if(value == "Play")
			startAnimations(); //your own implementation to start all animations
	};

try
	{
		//use this to check if preloading is supported on the player
		if(GFSpotBase.getHasPreload())
{
			log("Preloading enabled, waiting for PlaySpot command...");
		}
		else
		{
			log("Preloading disabled, starting animations now...");
			startAnimations();
		}
	}
	catch (error)
	{
		if(error)
			log("Url parsing error " + error.message);
	}

}

Function

Is invoked by the player, if preloading has been activated in the spot and the player brings the spot to the foreground.

Parameters

function(value)

value can include the following values:

Play: Is executed, if the player brings the spot to the foreground.
Stop: Is currently not used.

Players

Windows from global version 7.7

Android from player version 8.1.0.0

Retrieving all spots from the playlist

For the playlist data to be able to be polled in the HTML application, the method GFSpotBase.receiveOnGetAllSpots must be overwritten first of all. This best takes place by using the init() method after the <body onload="init()">.

function init()
{
//Override the receiver function
GFSpotBase.receiveOnGetAllSpots = function(data)
{
	//do something with the data
};

//Request the data
GFSpotBase.getAllSpots();
}

Function

This way the spot can retrieve a list of all spots in the playlist. This function can be used, for example, to jump from a central control spot to other spots. The return takes place analogously to readFile() via a return function.

Parameters

None

Players

Android from player version 8.1.0.0

Windows/Linux from player version 10.1

Example response:

{
  "Spots":[
    {
      "BlockID":"4760",
      "BlockName":"Any default playlist",
      "Overlay":"false",
      "ScreenNr":"1",
      "SplitNr":"0",
      "SpotName":"SpotSelector Website",
      "SpotID":"32709",
      "SpotInstanceID":"69820",
      "ThumbFilePath":"http://localhost:9090/thumb/_32709-5191-Manual-DefaultIXM Platform80X60-1-1.png",
      "EventType":"null",
      "EventValue":"null",
      "FilePath":"http://localhost:9090/_32709_v.1_WebsiteSpot.xml"
    },
    {
      "BlockID":"4762",
      "BlockName":"Some Image Event Playlist",
      "Overlay":"false",
      "ScreenNr":"1",
      "SplitNr":"0",
      "SpotName":"Flowers A",
      "SpotID":"32150",
      "SpotInstanceID":"68697",
      "ThumbFilePath":"http://localhost:9090/thumb/_32150-4762-Automatic-DefaultIXM Platform80X60-1-1.png",
      "EventType":"Start",
      "EventValue":"123",
      "FilePath":"http://localhost:9090/newNum_02.jpg"
    },
    {
      "BlockID":"4630",
      "BlockName":"Idle Playlist Test",
      "Overlay":"false",
      "ScreenNr":"1",
      "SplitNr":"0",
      "SpotName":"Grassfish Website",
      "SpotID":"25298",
      "SpotInstanceID":"63863",
      "ThumbFilePath":"http://localhost:9090/thumb/_25298-3227-Manual-DefaultIXM Platform80X60-1-1.png",
      "EventType":"IdleSeconds",
      "EventValue":"10",
      "FilePath":"http://localhost:9090/_25298_v.10_WebsiteSpot.xml"
    },
    {
      "BlockID":"4626",
      "BlockName":"Time Playlist Test",
      "Overlay":"false",
      "ScreenNr":"1",
      "SplitNr":"0",
      "SpotName":"Pictures-36",
      "SpotID":"25491",
      "SpotInstanceID":"63854",
      "ThumbFilePath":"http://localhost:9090/thumb/_25491-1007-Automatic-DefaultIXM Platform80X60-1-1.png",
      "EventType":"Time",
      "EventValue":"12:00:00 18:00:00",
      "FilePath":"http://localhost:9090/_25491_v.1_Pictures_36.jpg"
    }
  ]
}

Helper functions

Integrating GFSpotBase log outputs

Function	Log entries that are written by the GFSpotBase can be intercepted and integrated into the log mechanism of your HTML application in this way.
Parameters	function(msg)  String msg is the log message
Examples	`function init() { GFSpotBase.spotBaseLog = function(msg) { yourOwnLogging(msg); }; }`
Players	Windows from global version 7.7 Linux from global version 8.0

Reading the GFSpotBase version

Function	Supplies the version of the current GFSpotBase in the form of a string.
Parameters	None
Examples	GFSpotBase.getVersion();
Players	Windows from global version 7.7 Linux from global version 8.0

Function

Supplies the version of the current GFSpotBase in the form of a string.

Parameters

None

Examples

GFSpotBase.getVersion();

Players

Windows from global version 7.7

Linux from global version 8.0

Searching for a URL parameter

Function	Searches the URL parameters for a certain parameter and returns the value of this parameter if it is present. Otherwise the method returns “null”.
Parameters	function(paramName)  String paramName is the parameter that is being searched for.
Examples	Var usePreload = GFSpotBase.findUrlParam("usePreload");
Players	Windows from global version 7.7

What's Next

Dashboard widgets

In this article

Use
Functions for player interaction
Helper functions