Implementierungsvorschrift für Streaming-Messung

Versionshistorie

Inhaltsverzeichnis

Einleitung

Ob Nachrichtensendungen, Produkt-Präsentationen oder Online-Radioprogramme – alle setzen mittlerweile Audio- und Video-Streams als Kommunikationsmittel ein.

Mehr noch als bei statischen Seiten ist hier nicht nur die Anzahl der Besucher, sondern auch das Verhalten der Nutzer innerhalb des Streams von Interesse. Wie lange wird der Clip tatsächlich geschaut, welche Abschnitte waren von besonderem Interesse und welche nicht?

Wird das Streaming- Media innerhalb einer Website aufgerufen, besteht durch das COM-Modell bzw. Flash nicht nur die Möglichkeit, Benutzerzahlen zu erfassen, sondern vielmehr eben dieses Benutzerverhalten zu beobachten.

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

// 1. 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);

[start, end, timestamp]

// 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"]]
}]

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:

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

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:

<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, {}, sensors.WMStreamAdapter);

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('<OBJECT id="wmplayer" width="435" height="326" CLASSID="CLSID:6BF52A52-394A-11d3-B153-00C04F79FAA6" 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>');
     }
      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('                 <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>

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.

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

var sensors:SpringStreams = 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.

Die Messwerte werden über eine HTTP-Anfrage an die Zählsysteme übermittelt. Soll diese Anfrage über SSL (HTTPS) erfolgen, so kann dies dem Sensor übermittelt werden:

var sensors:SpringStreams = new SpringStreams("test", true); 

Ein NetStream-Objekt kann nun direkt gemessen werden:

sensors.track(ns,{});

Dem gemessenen Objekt können weitere, beschreibende Informationen mitgegeben werden:

var description:Object = {
	"stream": "videos/teststream",
	"desc": "some additional infos",
	"sx": video.width,
	"sy": video.heigth,
};
sensors.track(ns, description);

Es ist möglich weitere Attribute hinzuzufügen. Erwartet werden hier mindestens stream mit dem Namen/der Hierarchie des Streams und sx bzw. sy mit der Grössenbeschreibung des sichtbaren Bereiches.

Anfragen an das Messsystem werden über die ActionScript-Funktion trace in der Debug-Umgebung protokolliert.

Die Klasse SpringStreams definiert eine Funktion SPRING_UNLOAD über die Flash-Klasse ExternalInterface, sofern diese verfügbar ist. Analog zu der Javascript-Implementation kann diese Funktion Verwendet werden um das Beenden der Laufzeitumgebung zu signalisieren. Beim Einbau in eine Webseite kann dies wie folgt geschehen:

<body onunload="unload()">
...
function unload() {
   FlexProject.SPRING_UNLOAD();
}

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

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

Wobei FlexProject die ID des Flash-Objektes ist. Sollte bereits ein unload-Mechanismus in der Flash-Applikation vorhanden sein, so kann dieser die statische Funktion SpringStreams.unload() aufrufen.

Einsatz als Embedded Player und Security Einstellungen

Wenn der Player auf einer anderen Website als Embedded Player eingesetzt werden soll, müssen die Security-Einstellungen beachtet werden.

Folgende Einstellungen sind vorzunehmen (siehe: ExternalInterface#addCallback())

1. Legen Sie in der HTML-Seite im object-Tag der SWF-Datei den folgenden Parameter fest:

   <param name="allowScriptAccess" value="always" />
   

2. Fügen Sie in der SWF-Datei den folgenden ActionScript-Code ein:

   flash.system.Security.allowDomain( sourceDomain )
   

Beim Fehlen dieser Einstellungen tritt in der API ein Securityfehler auf, weil der Versuch die SPRING_UNLOAD()-Funktion in der Webseite zu registrieren fehlschlägt. Dieser Fehler wird in der API behandelt und ignoriert und ist nicht zwingend erforderlich für das korrekte Funktionieren der Messung.
Des Weiteren ist für das korrekte Funktionieren auch der Eintrag des Attributes onunload="..." im body-Tag notwendig, um das Verlassen der Seite der API zu melden. Beim Fehlen dieser Einstellungen ist es möglich, dass am Ende der Messung das letzte Event nicht mehr an das Messsystem übermittel wird.

Beispiel Integration in Flash

 var nsClient:Object = {};
 nsClient.onMetaData = ...
 nsClient.onCuePoint = ...  

 nc = new NetConnection();
 nc.connect(null);

 ns = new NetStream(nc);
 ns.play(streamlocation);
 ns.client = nsClient;

 video = new Video();
 video.attachNetStream(ns);
 
 addChild(video);
                
 var tracker:SpringStreams = new SpringStreams("test");
 tracker.track(ns,{"stream":"videos/teststream","sx":video.width,"sy":video.height});

Die Bestimmung der Gesamtlänge des Streams erfolgt über einen zwischengeschalteten Stream-Client, der die Meta-Ereignisse des Streams abgreift. Dieser Stream-Client leitet transparent alle Ereignisse an den bereits registrierten Client (nsClient im obigen Beispiel) weiter.

Erwartet wird ein Meta-Ereignis (onMetaData) mit einem Info-Objekt. Von diesem Info-Objekt wird das Attribut duration (info.duration) abgefragt und als Streamlänge interpretiert.

Sollten die eingesetzten Streams diese Meta-Information nicht liefern, so kann die Länge des Streams auch “von aussen” angegeben werden. Das obige Beispiel ändert sich dann wie folgt:

Über die Streamreferenz:

var nsClient:Object = {};
 nsClient.onMetaData = ...
 nsClient.onCuePoint = ...  

 nc = new NetConnection();
 nc.connect(null);

 ns = new NetStream(nc);
 ns.play(streamlocation);
 ns.client = nsClient;

 video = new Video();
 video.attachNetStream(ns);
 
 addChild(video);
                
 var tracker:SpringStreams = new SpringStreams("test");
 var stream:Stream = tracker.track(ns,{"stream":"videos/teststream","sx":video.width,"sy":video.height});

 stream.setDuration(600/*10 minutes*/);

Messung eines beliebigen Streaming-Content in Adobe Flash

Wie im letzten Kapitel beschrieben, benötigt die Bibliothek ein flash.net.NetStream-Objekt, um einen Streaming-Content zu messen. Im Inneren der Messung wird die aktuelle Position auf diesem Streamobjekt ausgelesen.

Die Messung ruft hierzu regelmäßig die Eigenschaft NetStream.time auf.

var net:NetConnection = new NetConnection();
net.connect(null);
var ns:NetStream = new NetStream(net);
var currentPosition:Number = ns.time;

Mit diesem Wissen ist es somit möglich softwaretechnisch jedes beliebige Streaming-Objekt zu messen, bei dem es möglich ist die aktuelle Position in Sekunden auf dem Stream auszulesen.
Hierzu implementiert man ein eigenes NetStream-Objekt und überschreibt den Aufruf ns.time.

Im folgenden Beispiel wird ein NetStream-Adapter für ein flash.media.Sound-Objekt implementiert.

package 
{
import flash.media.SoundChannel;
import flash.net.NetConnection;
import flash.net.NetStream;
	
public class SoundNetStreamAdapter extends NetStream
{
	private var channel:SoundChannel;
	
	public function SoundNetStreamAdapter(net:NetConnection, c:SoundChannel)
	{
		super(net);
		channel = c;
	}
		
	override public function get time():Number { 
            // return the position in seconds
		return channel.position/1000;
	}

}
}

Dieser Adapter ist ebenfalls ein NetStream-Objekt und kann zur Messung an die Streaming Bibliothek übergeben werden. Bei der Implementierung wird das Property time überschrieben. Dieses Property liefert die aktuelle Position in Sekunden. Da das SoundChannel-Objekt Millisekunden statt Sekunden liefert, wird der Wert noch durch 1000 dividiert, um dies der Schnittstellenbeschreibung des NetStream-Objektes anzupassen.

Die Länge des Streams wird über das Property Sound.length genommen, in Sekunden umgewandelt und mit dem Namen duration in das Description-Objekt geschrieben.

var tracker:SpringStreams = new SpringStreams("test");
			
var s:Sound = new Sound();
s.load(new URLRequest("file:///pathto/sound.mp3"));

var desc:Object = {
	"stream":"sounds/sound.mp3",
	"sx":0,"sy":0,
};
			
var nc:NetConnection = new NetConnection();
nc.connect(null);

var ns:NetStream = new SoundNetStreamAdapter(nc, s.play());
var stream:Stream = tracker.track(ns, desc);
stream.setDuration(s.length/1000); // duration in seconds

Weiterführende Themen

Weitere Segmentierung von Streams

Eventuell besteht der Bedarf einen Stream weiter zu segmentieren. Dies kann notwendig sein, wenn z.B. ein Livestream ausgeliefert wird und es sollen die einzelnen Sendungen unterschieden werden.
Auch dies kann mit der Bibliothek realisiert werden, indem man jede Sendung separat misst. Hierzu muss der Player aber wissen wann welche Sendung läuft, d.h. er braucht so etwas wie ein Programmheft.

Beispiel für die Messung von einzelnen Sendungen auf einem Livestream:

 var nsClient:Object = {};
 nsClient.onMetaData = ...
 nsClient.onCuePoint = ...  

 nc = new NetConnection();
 nc.connect(null);

 ns = new NetStream(nc);
 ns.play(streamlocation);
 ns.client = nsClient;

 video = new Video();
 video.attachNetStream(ns);
 
 addChild(video);
                
// 20:00 - 20:15 Tagesschau
// 20:15 - 21:00 PlusMinus
var tracker:SpringStreams = new SpringStreams("test");
// 20:00
var stream:Stream = tracker.track(ns,{"stream":"livestreams/ard/Tagesschau","sx":video.width,"sy":video.height});

// 20:15
stream.stop();
stream = tracker.track(ns,{"stream":"livestreams/ard/PlusMinus","sx":video.width,"sy":video.height});

Mehrere Streams parallel messen

Die Bibliothek ist in der Lage mehrer Streams parallel zu messen. Alle Streams die gestartet werden, können direkt über die track-Methode an die Streamingmessung übergeben werden.

Beispiel für das Messung von zwei parallel laufenden Streams

...
ns1 = new NetStream(...);
...
ns2 = new NetStream(...);
...
var tracker:SpringStreams = new SpringStreams("test");
var stream1:Stream = tracker.track(ns1,{"stream":"streams/stream1","sx":video.width,"sy":video.height});
var stream2:Stream = tracker.track(ns2,{"stream":"streams/stream2","sx":video.width,"sy":video.height});