API Dokumentation

German
- 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
11 Minuten Lesezeit

Drucken
Teilen

GFSpotBase

Aktualisiert am 18 Dec 2023
11 Minuten Lesezeit

Drucken
Teilen

Artikel-Zusammenfassung

Fanden Sie diese Zusammenfassung hilfreich?

Vielen Dank für Ihr Feedback

Die GFSpotBase ist eine Basisklasse für lokal abgespielte HTML-Spots und bietet eine Vielfalt von Methoden an, mit denen Sie mit dem Grassfish Player kommunizieren können. Es handelt sich dabei um eine JavaScript Lib, die in die lokale Webseite integriert werden muss. Sie kann sowohl von HTML Wizard-Spots als auch von HTML-Basic Spots verwendet werden.

Hinweis

Ab der GFSpotBase Version 2 ist es notwendig, dass der Spot selbstständig sendInitComplete aufruft, wenn er bereit ist, angezeigt zu werden. Sonst bringt ihn der Player nicht in den Vordergrund.

Verwendung

Die Datei gfSpotBase.js darf in Unterordnern verschachtelt sein, sollte aber nicht editiert werden. Fügen Sie die Datei mittels Script-Tag in die Webseite ein:

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

Achten Sie darauf, dass Sie dieses Script vor anderen Scripts einfügen, die sich auf die Playerfunktionalitäten beziehen. Weiters dürfen Sie auf die Methoden von der GFSpotBase erst zugreifen, wenn die JavaScript-Datei auch wirklich initialisiert worden ist.

Verwenden Sie hierzu die body onload-Methode:

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

Funktionen für die Playerinteraktion

Die GFSpotBase bietet eine Vielzahl von Methoden an, mit denen Sie mit dem Grassfish Player kommunizieren können. In diesem Abschnitt werden die einzelnen Funktionen erklärt.

Die Klasse GFSpotBase reserviert zwei Variablen im globalen JavaScript-Scope:

var GFSpotBase ist die Klasse selbst. Alle Methoden, die genutzt werden sollen, werden statisch über diese Klasse aufgerufen.
var grassfishGlobalPlayerToJSCallbackFunction ist eine zentrale Methode, die als Callback für die Kommunikation mit dem Player dient. Diese Methode darf vom HTML-Entwickler nicht direkt manipuliert oder verwendet werden. Für jedes unterstützte Callback gibt es eine jeweilige Wrappermethode, die hier genutzt werden kann.

An den Player werden immer nur zwei Parameter übergeben: der Methoden-Key und die restlichen Argumente. Die restlichen Argumente werden vor dem Übergeben an den Player mit einem Trennzeichen zusammengefügt. Dieses Trennzeichen darf in den Werten der Parameter keinesfalls verwendet werden und lautet "|+_-*|" (ohne Anführungszeichen).

Dem Player melden, dass der Spot bereit ist

Funktion	Gibt Playern ab der Version 10 das Signal, dass der Spot bereit ist, abgespielt zu werden. Auf Playern früherer Versionen hat dieser Methodenaufruf keinen Einfluss, dort wird der Spot weiterhin sofort abgespielt.
Parameter	Keine
Beispiele	GFSpotBase.sendInitComplete();
Player	Windows/Linux ab Global Version 10.0 Android ab Playerversion 8.1.0.2

Den Spot beenden

Funktion	Schließt den aktuellen Spot.
Parameter	Keine
Beispiele	GFSpotBase.quit();
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0

Springe zum nächsten Spot mit Namen X

Funktion	Springt zu einem anderen Spot innerhalb der aktuellen Playliste (sofern dieser vorhanden ist). Sind mehrere Spots mit gleichem Namen in der Playliste vorhanden, so wird zum ersten Spot, der dem aktuellen Spot nachfolgt, gesprungen.
Parameter	function(spotName, jumpBack) spotName ist der Name des Spots, zu dem gesprungen wird. jumpBack entscheidet darüber ob nach abspielen des Zielspots wieder der Aufrufspot angespielt werden soll. Wichtig: Dieser Parameter wird nicht von allen Playern unterstützt. Bitte stellen Sie sicher, dass Ihr Player aktuell genug ist, bevor Sie ihn verwenden.
Beispiele	GFSpotBase.jumpToSpot("Spot ABC"); GFSpotBase.jumpToSpot("News", true);
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0 jumpBack Parameter Unterstützung: Windows ab Global Version 10.0.10 Linux ab Global Version 10.1.3 Android ab Playerversion 10.1.0

Springe zu einem spezifischen Spot

Funktion	Springt zu einem anderen Spot innerhalb der aktuellen Playliste (sofern dieser vorhanden ist). Die Methode erfordert die Spotinstanz-ID, die eindeutig ist, sodass Sie, auch wenn ein Spot mehrfach in der Playliste vorkommt, zu diesem springen können. Mit dem zweiten Parameter (jumpBack) kehren Sie nach Beenden des angesprungenen Spots zum Aufrufer-Spot zurück. Die Spotinstanz-IDs können über die Methode getAllSpots vom Player abgefragt werden.
Parameter	function(siId, jumpBack) siId ist die eindeutige Spotinstanz-ID des Spots, zu dem gesprungen wird. jumpBack gibt an, ob man nach Abspielen des Zielspots wieder zum Aufrufer-Spot zurückkehren möchte.
Beispiele	GFSpotBase. jumpToSpotBySiId("3242", true);
Player	Android ab Playerversion 8.1.0.0 Windows/Linux ab Playerversion 10.1

Ein Player-Event auslösen

Funktion	Startet eine Eventplayliste auf dem Player.
Parameter	function(eventType, value) value ist die Event ID der Playliste eventType kann folgende Werte haben: Start: Startet eine Eventplayliste, die einmal abgespielt wird. StartLoop: Startet eine Eventplayliste, die als Loop weiterspielt. StopLoop: Beendet eine Loop-Eventplayliste.
Beispiele	GFSpotBase.sendEventCommand("Start","EventA"); GFSpotBase.sendEventCommand("StartLoop","EventB");
Player	Windows ab Global Version 7.7 Windows/Linux ab Playerversion 10.1

Kommunikation zwischen Spots

Spot-zu-Spot-Kommunikation ermöglicht Spots, in unterschiedlichen Splits bzw. auf unterschiedlichen Playern miteinander zu kommunizieren, um z.B. deren Inhalte zu synchronisieren. Eine Message an einen anderen Spot senden:

Funktion	Sendet eine Spot-zu-Spot-Nachricht an einen anderen Player oder Split.
Parameter	function(ip, uniqueID, value) ip ist die IP des Players, zu dem die Nachricht gesendet werden soll. uniqueID dient dazu, verschiedene Nachrichten voneinander zu unterscheiden. value ist die eigentliche Nachricht selbst als String. Der String kann auch XML oder JSON Daten beinhalten; wichtig ist, dass sich der Absenderspot und der Empfängerspot auf die gleiche Struktur einigen.
Beispiele	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");
Player	Windows ab Global Version 7.7 Windows/Linux ab Playerversion 10.1

Eine Message von einem anderen Spot empfangen

Damit Spot-zu-Spot-Nachrichten in der HTML-Applikation empfangen werden können, muss zunächst die Empfangsmethode überschrieben und dem Player anschließend mitgeteilt werden, dass der Spot sich für Spot-zu-Spot-Nachrichten interessiert. Dies geschieht am besten in der init()-Methode nach dem <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();
}

Funktion

Wird vom Player aufgerufen, wenn eine Spot-zu-Spot-Nachricht an den Spot gesendet wird.

Parameter

function(uniqueID, value)

uniqueID dient dazu, verschiedene Nachrichten voneinander zu unterscheiden.

value ist die eigentliche Nachricht selbst als String. Der String kann auch XML oder JSON Daten beinhalten; wichtig ist, dass sich der Absenderspot und der Empfängerspot auf die gleiche Struktur einigen.

Player

Windows ab Global Version 7.7

Windows/Linux ab Playerversion 10.1

Ein E-Mail über den Player senden

Funktion	Versendet ein E-Mail über den Player.
Parameter	function(headerText, bodyTextLines, email) headerText ist der Betreff des E-Mails. bodyTextLines ist ein Array an Zeilen für den Body. email Wenn "@" enthalten ist, dann wird das E-Mail an diese Adresse verschickt. Andernfalls wird der Wert in den Body geschrieben und die E-Mail an die E-Mail-Adresse gesendet, die in der Config-Datei auf dem Player definiert ist.
Beispiele	GFSpotBase.sendEmail("Some subject", ["Some body"], "Beispiel@domain.com");
Hinweise	Diese Funktion muss auf dem Player konfiguriert und aktiviert werden. Alle Werte werden durch ein Trennzeichen ("_\|_") getrennt an den Player übergeben. Dieses Trennzeichen darf daher in den Werten der Parameter nicht verwendet werden.
Player	Windows ab Global Version 7.7 Windows/Linux ab Playerversion 10.1

Statistiken

Statistiken schreiben (lokal auf Player)

Funktion	Mit dieser Funktion ist es dem Spot möglich, Statistikinformationen zu sammeln. Auf dem Player wird eine CSV-Datei mit den Daten erstellt; diese wird einmal täglich auf den Server übertragen wird. Multiple Werte können mit Strichpunkt ";" separiert werden. Auf dem Qt Linux-Player befinden sich die Daten in der Tabelle fs_select in der Statistikdatenbank. Pfad zur Datenbank: /opt/grassfish/data/db/stats.db Auf dem Server werden diese Informationen in einer monatlichen CSV-Datei mit der Bezeichnung 'yyyymm.csv' (z.B. '201705.csv') gespeichert. Pfad: \data\CustomerId\export\select, z.B. \\dev1\GVServer2.dev4\data\1\export\select.
Parameter	function(value) value ist entweder ein Wert oder mehrere durch Strichpunkt getrennte Werte, die in die CVS-Datei geschrieben werden.
Beispiele	Hier werden der App-Name, eine Produkt ID 547 und ein Zeitstempel übergeben: GFSpotBase.writeStatistic("ProductSelector;547" + ";"+new Date().getTime());
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0

Statistikreport versenden

Funktion	Mit dieser Funktion ist es dem Spot möglich Statistikinformationen an den Server zu schicken. Dieser sammelt diese Daten, welche in weiterer Folge über ein Report-Plugin und ein Dashboard-Addon grafisch dargestellt werden können.
Parameter	function(action, value, dynamicValues, spotIdentifier, sessionIdentifier, pluginGuid) action Eine Kennzeichnung für den Statistikeintrag (string). value Der Wert, welcher gespeichert werden soll (string). dynamicValues Hiermit lassen sich zusätzliche Informationen abspeichern (optional, Key-Value-Objekt). spotIdentifier Erfasste Daten können hiermit einem bestimmten Spot zugeordnet werden. (optional, string). sessionIdentifier Erfasste Daten können hiermit einem bestimmten User, welcher eine ihm zugewiesene Session besitzt, zugeordnet werden. (optional, string). pluginGuid Mit der PluginGuid lassen sich Reports in einem abgegrenzten Bereich am Server ablegen. Dieser muss dafür allerdings zuvor angelegt worden und die ihm zugeordnete pluginGuid bekannt sein.
Beispiele	Es sollen die Klicks auf angezeigte Produkte für die spätere Auswertung mitgeschrieben werden. Daher müssen der Funktion die Aktion und ein Wert, z.B. eine Produkt ID, übergeben werden: GFSpotBase.writeSpotReport("Clicked", "547"); Optional lassen sich noch zusätzliche Daten anhängen. Hier wird noch zusätzlich der Bereich, aus dem das Produkt geklickt wurde, mitgeschickt: `GFSpotBase.writeSpotReport("Clicked", "547", { area: "ProductList" });` Optional lassen sich Einträge einem bestimmten Spot zuordnen, indem man einen spotIdentifier festgelgt: GFSpotBase.writeSpotReport("Clicked", "547", null, "ProductSelector"); Besitzen Spots eigene Session um z.B. User zu autorisieren, lässt sich optional die Session ID übergeben. Dadurch lassen sich die Informationen einem User zuordnen und somit z.B. ein Verkaufsverhalten ableiten: GFSpotBase.writeSpotReport("Clicked", "547", null, "ProductSelector", "ddc5d323-9447-41f0-8898-266c486bdddc");
Player	QT Player ab 11.2.0

Einen Heartbeat senden

Funktion	Mit dieser Funktion kann der Spot einen Heartbeat-Pulse an den Player senden, damit überwacht werden kann, ob der Spot funktionstüchtig ist. Der Heartbeat für einen Spot wird mit dem erstmaligen Senden des Heartbeats an den Player "aktiviert". Bis dahin geht der Player davon aus, dass der Spot keinen Heartbeat unterstützt und überwacht den Spot dahingehend nicht. Wir empfehlen, beim Senden des Heartbeats einen kleinen Puffer hinzuzufügen. Setzen Sie das Intervall z.B. auf 10 Sekunden, sollten Sie den Heartbeat nach 4 Sekunden erneut senden, damit der Player den Spot nicht irrtümlich beendet, falls ein Request hängen bleibt.
Parameter	function(interval) interval ist das Intervall (in Millisekunden), nach dem der Player den Spot beendet, wenn bis dahin kein erneuter Heartbeat gesendet wurde.
Beispiele	Folgender Aufruf teilt dem Player mit, dass der Spot in spätestens 10 Sekunden erneut einen Heartbeat sendet: GFSpotBase.sendHeartbeat(10000);
Player	Windows ab Global Version 8.0 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0

Eine Nachricht loggen

Funktion	Mit dieser Funktion ist es dem Spot möglich, Log-Meldungen an den Player zu übergeben.
Parameter	function(msg, level) msg ist ein String, der in die Player-Logdateien geschrieben wird. Wir empfehlen, den Namen der HTML-Applikation mit anzugeben, um das Suchen nach Fehlern zu erleichtern. severity ist der Schweregrad des Fehlers und optional. Der Schweregrad kann einer der folgenden Werte haben: Error, Warning, Info, Debug.
Beispiele	GFSpotBase.sendLog("HTMLApp Error: " + message, GFSpotBase.logLevels.ERROR);
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0

Daten auf der Festplatte speichern bzw. lesen

Der Player ermöglicht es der Applikation, Daten auf die Festplatte zu schreiben und diese entweder von der Applikation selbst oder einer anderen Applikation zu lesen.

Eine Datei auf den Player schreiben

Funktion	Schreibt eine Datei auf den Player.
Parameter	function(directory, fileName, data) directory ist das Unterverzeichnis, in dem die Datei gespeichert wird. fileName ist der Dateiname der Datei. Abhängig vom gewünschten Inhalt kann die Dateiendung unter anderem .json oder .xml sein. data sind die eigentlichen Daten selbst als String. Der String kann auch XML- oder JSON-Daten beinhalten; wichtig ist, dass sich alle Spots, die diese Datei nutzen möchten, auf die gleiche Struktur einigen.
Beispiele	GFSpotBase.writeFile("sampleData/","sample.xml","<product><id>243</id><name>Some Product Name</name></product>");
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0

Eine Datei auf dem Player auslesen

Damit die Daten einer zuvor abgespeicherten Datei in der HTML-Applikation geladen werden können, muss zunächst die Methode GFSpotBase.receiveOnReadFile überschrieben werden. Dies geschieht am besten in der init()-Methode nach dem <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");
}

Funktion	Fragt beim Player nach einer Datei an. Dieser Aufruf passiert asynchron.
Parameter	function(directory, fileName) directory ist das Unterverzeichnis, in dem die Datei gespeichert wurde. fileName ist der Dateiname der Datei. Abhängig vom gewünschten Inhalt kann die Dateiendung unter anderem .json oder .xml sein.
Beispiele	GFSpotBase.readFile("sampleData/","sample.xml");
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0 Android ab Playerversion 8.1.0.0

Vorladen (Preloading) für den Spot aktivieren

Für eine nahtlose Überblendung eines Spots ist es erforderlich, dass der Spot rechenintensivere Ladevorgänge bereits abgeschlossen hat, wenn der Spot auf dem Player angezeigt wird. Dadurch erreichen Sie, dass der Spot nahtlos nach dem vorherigen Spot angezeigt wird – sofern Sie die Playliste im Grassfish CMS entsprechend konfiguriert haben. Der Spot gibt dies bereits beim Upload zum Server durch das Bereitstellen einer Variable in der Datei settings.xml bekannt. Zum Aktivieren dieser Funktion müssen Sie im ZIP-Archiv eine Datei namens settings.xml anlegen.

Wenn Sie Preloading im Spot aktivieren, muss der Spot selbst dafür sorgen, seine Animationen zu starten, wenn der Player den Befehl dazu gibt. Das geschieht über die receivePlayCommand(value);-Methode. Die Animationen dürfen erst in dieser Methode gestartet werden, da sie sonst zu früh beginnen und bereits mitten im Abspielen sind, wenn der Spot angezeigt wird. Ob der Player Preloading unterstützt, teilt er der HTML-Applikation über einen URL-Parameter namens usePreload=true mit. Ist dieser Parameter nicht gesetzt, müssen die Animationen sofort nach Aufrufen der Seite gestartet werden.

Auch hier empfiehlt es sich, die init()-Methode nach dem <body onload="init()"> zu verwenden.

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);
	}

}

Funktion

Wird vom Player aufgerufen, wenn im Spot Preloading aktiviert wurde und der Player den Spot in den Vordergrund holt.

Parameter

function(value)

value kann folgende Werte beinhalten:

Play: Wird ausgeführt, wenn der Player den Spot in den Vordergrund holt.
Stop: Wird derzeit nicht verwendet.

Player

Windows ab Global Version 7.7

Android ab Playerversion 8.1.0.0

Alle Spots aus der Playliste abrufen

Damit die Daten der Playliste in der HTML-Applikation abgefragt werden können, muss zunächst die Methode GFSpotBase.receiveOnGetAllSpots überschrieben werden. Dies geschieht am besten in der init()-Methode nach dem <body onload="init()">.

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

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

Funktion

Damit kann der Spot eine Liste aller Spots die in der Playliste sind abrufen. Diese Funktion kann beispielsweise genutzt werden, um von einem zentralen Steuerspot zu anderen Spots zu springen. Die Rückgabe erfolgt analog zu readFile() über eine Rückgabefunktion.

Parameter

Keine

Player

Android ab Playerversion 8.1.0.0

Windows/Linux ab Playerversion 10.1

Beispiel 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-Funktionen

Logausgaben der GFSpotBase integrieren

Funktion	Logeinträge, die von der GFSpotBase geschrieben werden, können so abgefangen und in den Logmechanismus Ihrer HTML-Applikation integriert werden.
Parameter	function(msg) à String msg ist die Lognachricht
Beispiele	function init() `{ GFSpotBase.spotBaseLog = function(msg) { yourOwnLogging(msg); }; }`
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0

GFSpotBase Version auslesen

Funktion	Liefert die Version der aktuellen GFSpotBase als String.
Parameter	Keine
Beispiele	GFSpotBase.getVersion();
Player	Windows ab Global Version 7.7 Linux ab Global Version 8.0

Nach einem URL-Parameter suchen

Funktion	Durchsucht die URL-Parameter nach einem gewissen Parameter und liefert den Wert dieses Parameters zurück, wenn er vorhanden ist. Andernfalls liefert die Methode "NULL" zurück.
Parameter	function(paramName) à String paramName ist der Parameter, nach dem gesucht wird.
Beispiele	Var usePreload = GFSpotBase.findUrlParam("usePreload");
Player	Windows ab Global Version 7.7

What's Next

Dashboard Widgets

In diesem Artikel

Verwendung
Funktionen für die Playerinteraktion
Helper-Funktionen