Page Comparison

Versionshistorie

Inhaltsverzeichnis

...

Das vorliegende Dokument beschreibt die Integration der Streamingmessung für verschiedene Anwendungsfälle.

Konzeption der Messung

Um einen Streaming-Inhalt messen zu können, wird ein Sensor beim Client benötigt, der misst welche Bereiche auf einen Stream vom User abgespielt werden.
Diese Bereiche können durch Zeitintervalle in Sekunden definiert werden - vorausgesetzt der entsprechende Player oder die abspielende Instanz kann über eine Methode die aktuelle Position in Sekunden auf dem Stream liefern. Durch regelmäßiges Auslesen der aktuellen Position ist es somit möglich alle Aktionen auf einen Stream zu tracken. Spulvorgänge können identifiziert werden, wenn es unerwartete Sprünge beim Auslesen der Position gibt und Stop- bzw. Pause-Aktionen werden dadurch identifiziert, dass sich die aktuelle Position nicht mehr verändert.

Das folgende Diagramm zeigt die Architektur der API:

Grundsätzliche Benutzung der API (programmiersprachenunabhängig)

In den folgenden Erläuterungen wird die Javascript-Syntax verwendet. Die Vorgehensweise ist aber bei jeder verwendeten Programmiersprache im Grundsatz die gleiche.

Einbau über Javascript für beliebige Player (auch proprietäre)

Vor Benutzung der springStreams-Funktionen muss die Javascript-Bibiliothek geladen werden. Dies geschieht über den folgenden Script-Tag:

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

Die springStreams-Funktionen stehen über die Klasse SpringStreams zur Verfügung. Bei der Erzeugung eines Objektes dieser Klasse wird die Websitekennung übergeben:

	
var sensors = new SpringStreams("test"); 

test ist in diesem Fall die Kennung der Website. Diese Kennung muss durch die eigene, von spring zur Verfügung gestellte Kennung ersetzt werden.

Um beliebige Player zu messen wird ein Adapter für den jeweiligen Player erstellt und an die Sensoren übergeben. Der Adapter stellt zur Messung drei Funktionen zur Verfügung:

//var 1.myAdapter Instantiiere= das{
API-Objekt
var sensors = new SpringStreams("angebotsname");

// 2. Ein Description-Objekt für den Streaming-Content anlegen.
var desc = {
   "stream":"videos/mystream",
   "duration":600, // in Sekunden
   "sx":video.width,
   "sy":video.height
};

// 3. Das Content-Objekt zur Verfügung stellen
var content = ...; // Irgendein Objekt, dass in der Lage ist die aktuelle Position in Sekunden zu liefern

// 4. Den Content mit dem Description-Objekt auf dem Sensor registieren.
var stream = sensors.track(content, desc);

Erläuterungen:

zu 1: Instantiiere das API-Objekt

• Der korrekte Angebotsname muß angegeben werden. Dieser Angebotsname wird vom Betreiber der Streaming-Lösung vergeben.

  Code Block
  borderColor grey bgColor #eeeeee borderStyle solid lang javascript
  var sensors = new SpringStreams("angebotsname");

• Eine Instanz des Objektes SpringStreams ist im Framework nur einmalig anzulegen. Ab da können ein oder mehrere Streams der track-Methode zur Messung übergeben werden.

zu 2: Ein Description-Objekt für den Streaming-Content anlegen

Im Description-Objekt muss mindestens der Name des Streams angegeben werden.

...

	"getMeta" : function(id) {
		return {
			"pl" :"own player",
			"plv" :"version1",
			"sx" : screen.width,
			"sy" : screen.height
		}
	},
	"getDuration" : function(id) {
		return 0;
	},
	"getPosition" : function(id) {
		return new Date().getTime() / 1000;
	}
};

1. Die Funktion getMeta wird verwendet um eine Beschreibung des Players und des verfügbaren Bildschirms zu beziehen. Bei Aufruf dieser Funktion wird als Rückgabe ein Objekt mit den folgenden Attributen erwartet:

2. Die Funktion getDuration wird verwendet um die Gesamtlänge des Streams zu ermitteln, sie liefert die Gesamtdauer des Streams in Sekunden. Sollte die Dauer des Streams nicht zu ermitteln sein, so sollte diese Funktion 0 liefern.

3. Die Funktion getPosition wird verwendet, um die aktuelle Position im Stream zu ermitteln. Sie liefert die aktuelle Abspielposition in Sekunden. Diese Funktion dient zur Ermittlung der jeweiligen Abspiel-, Stop- und Spulintervalle.

Allen Funktionen wird beim Aufruf das zu messende Objekt (aus dem ersten Parameter des Aufrufs von sensors.track(…)) übergeben.

Der selbst erstellte Adapter kann nun zur Messung verwendet werden:

...

	
var desc = {
   "stream":"videos/mystream",
   "duration":600 // in Sekunden
};

...

Mit dem Description-Objekt übergibt man der API nähere Informationen zum Streaming-Content. Hierbei sind folgende Variablen erlaubt bzw. werden vom Messsystem verstanden.

zu 3: Das Content-Objekt zur Verfügung stellen

Die einzige Anforderung an dieses Objekt seitens der Streaming-API ist, dass es die Möglichkeit bietet die aktuelle Position auf einem Stream in Sekunden auslesen zu können. Je nach Programmiersprache sind hier ebenfalls softwaretechnische Lösungen denkbar, wie die Implementierung von Interfaces oder die Implementierung von Adapterklassen.

sensors.track(someObject, desc, myAdapter);

Die Ausführung der Messung kann überwacht werden, indem die Methode debug auf dem SpringStreams-Objekt belegt wird:

sensors.debug = function(v) {
        window.status = " " + v;
}

Bei jeder Übermittlung des Sensors an die Zählsysteme wird diese Methode mit dem aufgerufenen URL als Parameter (String) aufgerufen.

SpringStreams verwendet keine Eingriffe in das Event-Model des umgebenden Dokuments, daher ist es notwendig das Verlassen oder Beenden der Wiedergabe des Streams durch Ereignisse ausserhalb des Players an die Sensoren zu übermitteln. Die einfachste Variante ist das Einfügen einer unload-Funktion mit Aufruf der Methode sensors.unload() beim Verlassen der Webseite:

function unload() {
        sensors.unload();
}

Da die Browser nach Abschluss der Unload-Sequenz die Seite beenden, wurde uU. der abschließende Zählimpuls noch nicht ausgelöst. Eine Verbesserung schafft der Einsatz einer kurzen, vom Benutzer nicht bemerkbaren Verzögerung am Ende der Unload-Sequenz:

...

var content = ...; 

zu 4: Den Content mit dem Description-Objekt auf dem Sensor registieren.

...

function unload() {
	sensors.unload();
        // give time for submission
	var start= new Date(); var now = null; do now = new Date();  
        while(now-start < 100);
}

Damit diese Funktion beim Verlassen der Webseite aufgerufen wird, kann diese etwa in den Body-Tag eingefügt werden:

<body onunload="unload();">

Einzelne Streams können auch direkt beendet werden, etwa beim Wechseln in einer Playliste:

var stream = sensors.track(

...

someObject, desc, myAdapter);

...

...
stream.stop()

...

Interne Funktionsbeschreibung der API

Nachdem der Streaming-Content der track-Methode mit dem zugehörigen Description-Objekt übergeben worden ist, wird intern alle 200ms die aktuelle Position auf dem Streaming-Content abgefragt. Intern werden alle Intervalle gesammelt, die vom User auf dem Stream betrachtet worden sind. Bei konstanter Sichtung ist dies ein Intervall. Sobald festgestellt wird, dass sich die aktuelle Position um mehr als 1 Sekunde um die zu erwarteten Position verändert, kann von einem Start-, Stop- oder Spulereignis oder auch einem Buffering ausgegangen werden. In diesem Fall wird ein neues Sichtungsintervall angelegt.

[start, end, timestamp]

Alle gesammelten Nutzungsinformationen der gemessenen Streams werden in einem HTTP-Request codiert und regelmäßig dem Messsystem übermittelt. Hierbei gelten folgende Regeln:

• bei jeder Interaktion (Start-, Stop- oder Spulvorgänge oder Bufferingphasen) wird sofort ein Update gesendet.
• bei konstanter Sichtung mindestens alle 20 Sekunden.

Datentransport

// System-Objekt
[{"sx":1280,
"sy":1024,
"pl":"FlashPlugin",
"plv":"WIN 10,0,45,2"
},
// Nutzungsinformationen
{"stream":"spring/teststream", 
     "dur":"600", 
     "sx":"400",
     "sy":"300",
     "uid":"267fgut",
      "vt":356, 
     "pst":[[0,0,"kzog7e"],[22,378,"kzog7e"]]
}]

Beim Datentransport werden zwei Objekte übermittelt:

• Das System-Objekt, dass Informationen enthält wie Bildschirmauflösung, Playername und Playerversion.

  Variable	Optional?	Beschreibung
  sx	Nein	Die Breite des Bildschirms in Pixel (width)
  sy	Nein	Die Höhe des Bildschirms in Pixel (height)
  pl	Nein	Der Name des Players
  plv	Nein	Die Playerversion

• Die Nutzungsinformationeneiner Messung

  Variable	Optional?	Beschreibung
  plv	Nein	Die Playerversion
  stream	Nein	Der Name des Streams
  dur,duration	Nein, wenn es kein Livestream ist.	Die Länge des Streams in Sekunden
  sx	Nein	Die Breite des Streamfensters in Pixel(width) oder den Wert 0
  sy	Nein	Die Höhe des Streamfensters in Pixel(height) oder den Wert 0
  uid	Nein	Die Unique Id des Nutzungsvorganges
  vt	Nein	Die Viewtime in Sekunden. Die Viewtime wird gemessen ab dem Aufruf der Methode SpringStreams.track(...)
  pst	Nein	Die Playstates. Die Liste mit Sichtungsintervallen auf dem Stream.

Einbau über Javascript für beliebige Player (auch proprietäre)

Vor Benutzung der springStreams-Funktionen muss die Javascript-Bibiliothek geladen werden. Dies geschieht über den folgenden Script-Tag:

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

Die springStreams-Funktionen stehen über die Klasse SpringStreams zur Verfügung. Bei der Erzeugung eines Objektes dieser Klasse wird die Websitekennung übergeben:

	
var sensors = new SpringStreams("test"); 

test ist in diesem Fall die Kennung der Website. Diese Kennung muss durch die eigene, von spring zur Verfügung gestellte Kennung ersetzt werden.

Um beliebige Player zu messen wird ein Adapter für den jeweiligen Player erstellt und an die Sensoren übergeben. Der Adapter stellt zur Messung drei Funktionen zur Verfügung:

var myAdapter = {

	"getMeta" : function(id) {
		return {
			"pl" :"own player",
			"plv" :"version1",
			"sx" : screen.width,
			"sy" : screen.height
		}
	},
	"getDuration" : function(id) {
		return 0;
	},
	"getPosition" : function(id) {
		return new Date().getTime() / 1000;
	}
};

1. Die Funktion getMeta wird verwendet um eine Beschreibung des Players und des verfügbaren Bildschirms zu beziehen. Bei Aufruf dieser Funktion wird als Rückgabe ein Objekt mit den folgenden Attributen erwartet:

2. Die Funktion getDuration wird verwendet um die Gesamtlänge des Streams zu ermitteln, sie liefert die Gesamtdauer des Streams in Sekunden. Sollte die Dauer des Streams nicht zu ermitteln sein, so sollte diese Funktion 0 liefern.

3. Die Funktion getPosition wird verwendet, um die aktuelle Position im Stream zu ermitteln. Sie liefert die aktuelle Abspielposition in Sekunden. Diese Funktion dient zur Ermittlung der jeweiligen Abspiel-, Stop- und Spulintervalle.

Allen Funktionen wird beim Aufruf das zu messende Objekt (aus dem ersten Parameter des Aufrufs von sensors.track(…)) übergeben.

Der selbst erstellte Adapter kann nun zur Messung verwendet werden:

sensors.track(someObject, desc, myAdapter);

Die Ausführung der Messung kann überwacht werden, indem die Methode debug auf dem SpringStreams-Objekt belegt wird:

sensors.debug = function(v) {
        window.status = " " + v;
}

Bei jeder Übermittlung des Sensors an die Zählsysteme wird diese Methode mit dem aufgerufenen URL als Parameter (String) aufgerufen.

SpringStreams verwendet keine Eingriffe in das Event-Model des umgebenden Dokuments, daher ist es notwendig das Verlassen oder Beenden der Wiedergabe des Streams durch Ereignisse ausserhalb des Players an die Sensoren zu übermitteln. Die einfachste Variante ist das Einfügen einer unload-Funktion mit Aufruf der Methode sensors.unload() beim Verlassen der Webseite:

function unload() {
        sensors.unload();
}

Da die Browser nach Abschluss der Unload-Sequenz die Seite beenden, wurde uU. der abschließende Zählimpuls noch nicht ausgelöst. Eine Verbesserung schafft der Einsatz einer kurzen, vom Benutzer nicht bemerkbaren Verzögerung am Ende der Unload-Sequenz:

;

Bei anderen, eingebetteten MediaPlayern als dem Windows Media Player kann ein Adapter angegeben werden. Hier ein Beispiel mit einem Real-Player der id rvplayer:

sensors.track(rvplayer, description, sensors.RVStreamAdapter);

Beispiel beliebiger Player

<html>
<head>
<title>spring sensors</title>
<script src="springstreams.js"></script>
</head>
<body onunload="unload();">
<script type="text/javascript">

var sensors = new SpringStreams("test"); 
var adapter = {
	"getMeta" : function() {
		return {
			"pl" :"own player",
			"plv" :"version1",
			"sx" : screen.width,
			"sy" : screen.height
		}
	},
	"getDuration" : function() {
		return 1000;
	},
	"getPosition" : function() {
		return new Date().getTime() / 1000;
	}
};

var desc = {
	"stream": "videos/teststream"
}

sensors.track("someid", desc, adapter);

// uncomment for debugging
//	sensors.debug = function(v) {
//		window.status = v;
//	}

function unload() {
	sensors.unload();
        // give time for submission
	var start= new Date(); var now = null; do now = new Date();  
        while(now-start < 100);
}

...

</script>	
</body>

Einbau über Javascript für Windows Mediaplayer

Vor Benutzung der springStreams-Funktionen muss die Javascript-Bibiliothek geladen werden. Dies geschieht über den folgenden Script-Tag:

<body<script onunloadsrc="unload();">

...

.../springstreams.js"></script>

Die springStreams-Funktionen stehen über die Klasse SpringStreams zur Verfügung. Bei der Erzeugung eines Objektes dieser Klasse wird die Websitekennung übergeben:

var streamsensors = sensors.track(someObject, desc, myAdapter);
...
stream.stop();

...

 new SpringStreams("test"); 

test ist in diesem Fall die Kennung der Website. Diese Kennung muss durch die eigene, von spring zur Verfügung gestellte Kennung ersetzt werden.

Ein in die Website eingebetteter Mediaplayer kann nun direkt gemessen werden. Um die Messung durchzuführen, wird das zu messende Objekt benötigt. Dies ist idR. durch die id des Object-Tag verfügbar. In diesem Beispiel wird das Objekt mit der ID wmplayer mit einer Referenz auf den Windows Media Player verwendet.

sensors.track(rvplayerwmplayer, description{}, sensors.RVStreamAdapterWMStreamAdapter);

Beispiel beliebiger PlayerNeben der ID des zu messenden Objektes können beschreibende Informationen zu diesem Objekt in Form eines Javascript-Objektes angegeben werden:

var description = {
	"getMetastream" : function() {
		return {
			"pl" :"own player",
			"plv" :"version1",
			"sx" : screen.width,
			"sy" : screen.height
		}
	},
	"getDuration" : function() {
		return 1000;
	},
	"getPosition" : function() {
		return new Date().getTime() / 1000;
	}
};

var desc = {
	"stream": "videos/teststream"
}

sensors.track("someid", desc, adapter);

// uncomment for debugging
//	sensors.debug = function(v) {
//		window.status = v;
//	}

function unload() {
	sensors.unload();"videos/teststream"
	"desc": "some additional description" 
};
sensors.track(wmplayer, description);

Es ist möglich, mehrere zusätzliche Attribute zu der Beschreibung hinzuzufügen. Erwartet wird mindestens die Angabe von stream mit dem Namen/der Hierarchie des Streams.

Es können mehrere Objekte gemessen werden.

Beispiel Windows Media Player

<html>
<head>
<title>spring sensors</title>
<script src="springstreams.js"></script>
</head>
<body onunload="unload();">

<SCRIPT type="text/javascript">
      if(-1 != navigator.userAgent.indexOf("MSIE"))
      {
        document.write('<OBJECT id="wmplayer" width="435" height="326" CLASSID="CLSID:6BF52A52-394A-11d3-B153-00C04F79FAA6" type="application/x-ms-wmp">');
        document.write('         // give time for submission 	var start= new Date(); var now = null; do now = new Date(<param name="URL" value="http://wstreaming.zdf.de/zdf/veryhigh/070912_iaa_mim.asx">');
          while(now-start < 100);
}
</script>	
</body>

Einbau über Javascript für Windows Mediaplayer

Vor Benutzung der springStreams-Funktionen muss die Javascript-Bibiliothek geladen werden. Dies geschieht über den folgenden Script-Tag:

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

Die springStreams-Funktionen stehen über die Klasse SpringStreams zur Verfügung. Bei der Erzeugung eines Objektes dieser Klasse wird die Websitekennung übergeben:

var sensors = new SpringStreams("test"); 

test ist in diesem Fall die Kennung der Website. Diese Kennung muss durch die eigene, von spring zur Verfügung gestellte Kennung ersetzt werden.

Ein in die Website eingebetteter Mediaplayer kann nun direkt gemessen werden. Um die Messung durchzuführen, wird das zu messende Objekt benötigt. Dies ist idR. durch die id des Object-Tag verfügbar. In diesem Beispiel wird das Objekt mit der ID wmplayer mit einer Referenz auf den Windows Media Player verwendet.

sensors.track(wmplayer, {});

Neben der ID des zu messenden Objektes können beschreibende Informationen zu diesem Objekt in Form eines Javascript-Objektes angegeben werden:

var description = {
	"stream": "videos/teststream"
	"desc": "some additional description" 
};
sensors.track(wmplayer, description);

Es ist möglich, mehrere zusätzliche Attribute zu der Beschreibung hinzuzufügen. Erwartet wird mindestens die Angabe von stream mit dem Namen/der Hierarchie des Streams.

Es können mehrere Objekte gemessen werden.

Beispiel Windows Media Player

<html>
<head>
<title>spring sensors</title>
<script src="springstreams.js"></script>
</head>
<body onunload="unload();">

<SCRIPT type="text/javascript">
      if(-1 != navigator.userAgent.indexOf("MSIE"))
      {document.write('                <param name="AutoStart" VALUE="1">');
        document.write('                <param name="ShowStatusBar" VALUE="1">');
        document.write('</object>');
     }
      else  {
       document.write('<OBJECT id="wmplayer" width="435" height="326" type="application/x-ms-wmp">');
       document.write('                 <param name="URL" value="http://wstreaming.zdf.de/zdf/veryhigh/070912_iaa_mim.asx">');
       document.write('                 <param name="AutoStart" VALUE="1">');
       document.write('                document.write('<OBJECT id="wmplayer" width="435" height="326" CLASSID="CLSID:6BF52A52-394A-11d3-B153-00C04F79FAA6" type="application/x-ms-wmp" <param name="ShowStatusBar" VALUE="1">');
        document.write(' </object>');
      }         
 <param  name="URL" value="http://wstreaming.zdf.de/zdf/veryhigh/070912_iaa_mim.asx">');
        document.write('                <param name="AutoStart" VALUE="1">');
        document.write('           </SCRIPT>
		
<script type="text/javascript">

// "test" is the name of the tracked website
var sensors = new SpringStreams("test");

// wmplayer is the id of the stream above
sensors.track(wmplayer, {"stream":"videos/teststream"});

// uncomment for debugging
//sensors.debug = function(v) {
//	window.status = v;
//}

function unload() {
	sensors.unload();
     <param name="ShowStatusBar" VALUE="1">');
        document.write('</object>');
     } // give time for submission
	var start= new Date(); var now = null; do now = new Date();  
    else  {  while(now-start < 100);
}
</script>	
 document.write('<OBJECT id="wmplayer" width="435" height="326" type="application/x-ms-wmp">');
       document.write('                 <param name="URL" value="http://wstreaming.zdf.de/zdf/veryhigh/070912_iaa_mim.asx">');
       document.write('                 <param name="AutoStart" VALUE="1">');
       document.write('                 <param name="ShowStatusBar" VALUE="1">');
       document.write(' </object>');
      }         
    </SCRIPT>
		
<script type="text/javascript">

// "test" is the name of the tracked website
var sensors = new SpringStreams("test");

// wmplayer is the id of the stream above
sensors.track(wmplayer, {"stream":"videos/teststream"});

// uncomment for debugging
//sensors.debug = function(v) {
//	window.status = v;
//}

function unload() {
	sensors.unload();
        // give time for submission
	var start= new Date(); var now = null; do now = new Date();  
        while(now-start < 100);
}
</script>	
</body>
</body>

Einbau mit HTML5

Vor Benutzung der springStreams-Funktionen muss die Javascript-Bibiliothek geladen werden. Dies geschieht über den folgenden Script-Tag:

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

Die springStreams-Funktionen stehen über die Klasse SpringStreams zur Verfügung. Bei der Erzeugung eines Objektes dieser Klasse wird die Websitekennung übergeben:

var sensors = new SpringStreams("test"); 

 test ist in diesem Fall die Kennung der Website.  Diese Kennung muss durch die eigene, von spring zur Verfügung gestellte Kennung ersetzt werden.

Ein in die Website eingebettetes video- oder audio Element (siehe: http://www.w3schools.com/tags/ref_av_dom.asp) kann nun direkt gemessen werden. Um die Messung durchzuführen, wird das zu messende Objekt benötigt. Dies ist idR. durch die id des Object-Tag verfügbar. In diesem Beispiel wird das Objekt mit der ID video5 mit einer Referenz auf ein HTML video Element verwendet.

sensors.track(video5, {});

Neben der ID des zu messenden Objektes können beschreibende Informationen zu diesem Objekt in Form eines Javascript-Objektes angegeben werden:

var description = {
	"stream": "videos/teststream"
	"desc": "some additional description" 
};
sensors.track(video5, description);

Es ist möglich, mehrere zusätzliche Attribute zu der Beschreibung hinzuzufügen. Erwartet wird mindestens die Angabe von stream mit dem Namen/der Hierarchie des Streams.

Beispiel HTML5 video

<!DOCTYPE html>
<html lang="en">
<head>
  <title>HTML5 Video Example</title>
  <script src="./springstreams.js"></script>
</head>
<body onunload="unload()">
<script type="text/javascript">
    var sensors = new SpringStreams("test"); 
</script>

   <div align="center">
    <video id='video' controls preload='none' >
      <source id='mp4' src="./wetter.ard.20101209.mp4" type='video/mp4; codecs="avc1, mp4a"'></source>
      <p>Your user agent does not support the HTML5 Video element.</p>
    </video>
   </div>

    <script type="text/javascript">
	var description = {
		"stream":"videos/news/wetter.ard.20101209.mp4"
	};

    var handle = sensors.track(video, description, sensors.HTML5Adapter);
    function unload() {
	  sensors.unload();
    }

</script>
</body>
</html>

Einbau in Adobe Flash

Der Einbau in Adobe Flash erfolgt ähnlich dem in Javascript. Zur Benutzung der springStreams-Funktionen wird die Bibiliothek springstreams.as3.swc (bzw. springstreams.as2.swc für Actionscript2) in die Applikation eingebunden.

...