ActionScript 3.0-Wrapper für Chromeless Player

Dieser Artikel wurde von einem externen Entwickler verfasst und eingereicht. Das YouTube APIs and Tools-Team bedankt sich bei Matthew Richmond für seine Zeit und sein Fachwissen.

Matthew Richmond, The Chopping Block, Inc.
Oktober 2008

• Einführung
• Wichtige Ressourcen
• Los gehts
  • Wrapper-Demo – Übersicht
  • YouTubeLoader-Objekt erstellen
  • GIF-Datei einbetten und YouTubeLoader-JavaScript verbinden
• Interaktion mit dem Spieler
  • Video anfordern
  • Zusätzliche Aufrufe ausführen
  • Ereignisse abonnieren
• Verfügbare Vorgänge
• Hinweise zur Demo
• Schlusswort

Einführung

In diesem Artikel werde ich einen zuverlässigen ActionScript 3.0 Wrapper für den Chromeless YouTube-Player vorstellen und kurz vorstellen. Der Wrapper nutzt die Klasse ExternalInterface von ActionScript und das JavaScript-API von YouTube.

Mit den YouTube Player-Tools und dem Chromeless Player von Google können Designer/Entwickler die Möglichkeiten von YouTube schnell und einfach in ihre Onlineprojekte integrieren. Dieser Ansatz eignet sich sowohl für kleine Projekte mit einem festen Budget, bei denen kein Videohosting möglich ist, als auch für große Projekte für Kunden, die eine benutzerdefinierte Endnutzererfahrung wünschen, ohne sich von ihrer YouTube-Zielgruppe zu distanzieren.

Abbildung 1: ActionScript 3.0-Wrapper-Screenshot

Das Flash-API und die eingebetteten Player von YouTube sind geschrieben und funktionieren recht gut mit ActionScript 2.0. Wenn Sie ein Projekt mit einer Version von ActionScript 3.0 ausführen, wird die nahtlose Integration etwas komplexer. Es ist zwar einfach, die Action 2.0-Player in einer Version vom Typ "ActionScript 3.0" zu laden, es ist jedoch nicht möglich, direkt zu kommunizieren oder Funktionsaufrufe an den geladenen Player zu übergeben. Das Ganze wird noch komplizierter, da die SWF-Datei von den YouTube-Servern ein Video in sich selbst lädt. Unser Wrapper muss sich dieser Tatsache bewusst sein und entsprechend reagieren. Glücklicherweise bietet die ActionScript-Sprache zwei plausible Problemumgehungen, um diese verschachtelten, aber getrennten Teile wieder zu verbinden: die LocalConnection-Klasse oder die ExternalInterface-Klasse. In dieser Demo liegt der Schwerpunkt auf Letzterem, da das ExternalInterface nahtlos mit der gut dokumentierten JavaScript API funktioniert und daher gut mit allen anderen Elementen auf der XHTML-Seite zusammenspielt.

Wichtige Ressourcen

Bevor wir beginnen, finden Sie hier eine Liste der zugehörigen Ressourcen und Dateien, die Ihnen zur Verfügung stehen. Viele der in diesem Artikel behandelten Themen werden unter den folgenden Links ausführlicher erläutert.

• ActionScript 3.0-Wrapper ansehen und Quelldateien herunterladen
• Offizielle YouTube JavaScript Player API-Referenz
• Dokumentation zur Adobe ExternalInterface-Klasse
• SWFObject JavaScript Flash-Embedding

Eintauchen

Wrapper-Demo – Übersicht

Abbildung 3: JavaScript-Datei

Abbildung 2: ActionScript-Klassendateien

Der ActionScript 3.0-Wrapper besteht im Wesentlichen aus zwei miteinander verbundenen Teilen: den ActionScript 3.0-Klassendateien in src/choppingblock/video/ (Abbildung 2) und der JavaScript-Datei „youTubeLoader.js“ in deploy/_assets/js/ (Abbildung 3). Ihre Flash/Flex-Quelldatei erstellt eine Instanz der YouTubeLoader-ActionScript-Klasse. Ihre XHTML-Seite bettet die Flash-Datei ein und registriert sie mit den Funktionen in der YouTubeLoader-JavaScript-Datei. Wichtig ist, dass Sie verstehen, dass alles, was YouTubeLoader in der Flash-Datei ausführt, über die JavaScript-Funktionen gesteuert wird.

Da alle Funktionen in Flash über das JavaScript-API gesteuert werden, können Sie innerhalb des Flash-"Test Movie" KEINE YouTube-Inhalte laden. Player. Es funktioniert nur, wenn es in eine XHTML-Seite eingebettet und ordnungsgemäß mit den YouTubeLoader-JavaScript-Funktionen verbunden ist.

Hinweis: Wenn Sie einen dieser Aufrufe testen möchten, muss die Datei auf einem Webserver ausgeführt werden oder Sie müssen die Sicherheitseinstellungen Ihres Flash-Players ändern, da der Flash-Player Aufrufe zwischen lokalen Dateien und dem Internet einschränkt.

YouTubeLoader-Objekt erstellen

Bevor Sie eine Instanz des YouTubeLoader-Objekts in Ihrem Flash/Flex-Projekt erstellen können, müssen Sie sicherstellen, dass sich das Paket bzw. der Ordner mit den erforderlichen Dateien im selben Verzeichnis wie Ihr Projekt befindet (siehe Abbildung 2) oder mit dem Klassenpfad Ihres Projekts definiert ist. Anschließend können Sie die Paketdateien importieren:

import choppingblock.video.*;

Dadurch kann die ActionScript-Datei auf den Parameter "YouTubeLoader.as" zugreifen. und "YouTubeLoaderEvent.as". Klassen. Jetzt kannst du eine Instanz der Klasse „YouTubeLoader“ und die erforderlichen Ereignis-Listener erstellen:

import choppingblock.video.*;

public class YouTubeDemo extends Sprite {

  private var _youTubeLoader:YouTubeLoader;	
  
  // ------------------------------------
  // CONSTRUCTOR
  // ------------------------------------
  
  public function YouTubeDemo () {
    
    // create YouTubeLoader object
    _youTubeLoader = new YouTubeLoader();
    
    // add event listener to call youTubePlayerLoadedHandler method on load
    _youTubeLoader.addEventListener(YouTubeLoaderEvent.LOADED, youTubePlayerLoadedHandler);
    
    // create the actual loader 
    _youTubeLoader.create();
    
    // add object to the display stack
    addChild(_youTubeLoader);
  };
  
  // ------------------------------------
  // EVENT METHODS
  // ------------------------------------
  
  /**
  Called via player loaded event, lets you know you are all clear to send player commands.
  */
  private function youTubePlayerLoadedHandler (event:YouTubeLoaderEvent):void{
    //trace("YouTubeDemo: youTubePlayerLoadedHandler");
    
    // you are now clear to start making calls to the YouTubeLoader object
  };
};

Wenn jetzt die JavaScript-Datei vorhanden und verbunden ist, sollte youTubePlayerLoadedHandler erfolgreich aufgerufen werden und wir können mit dem Senden von Anfragen beginnen.

SWF-Datei einbetten und JavaScript-Code für YouTube-Videos verknüpfen

Du kannst erst dann Inhalte von YouTube erfolgreich laden, wenn deine SwF-Datei in eine XHTML-Datei eingebettet und mit dem YouTubeLoader-JavaScript verbunden ist. Wir empfehlen zur Einbettung aller Player, auf die über die JavaScript API zugegriffen wird, die Verwendung von SWFObject. So kannst du die Flash Player-Version des Endnutzers erkennen (für die JavaScript API ist Flash Player 8 oder höher erforderlich). Außerdem wird das Kästchen „Klicken, um dieses Steuerelement zu aktivieren“ entfernt, wenn du den Player im Internet Explorer aufrufst.

Im <head>-Teil deiner XHTML-Datei verbindest du die Dateien „swfobject“ und „youTubeLoader“:

<script type="text/javascript" src="_assets/js/swfobject.js"></script>
<script type="text/javascript" src="_assets/js/youTubeLoader.js"></script>

Unten findest du ein Beispiel dafür, wie du mit SWFObject dein ActionScript 3.0-SWF-Objekt mit aktivierter JavaScript API einbettest und dann eine Referenz auf dein SWF-Objekt an die YouTube-Lade-JavaScript API weitergibst.

<script type="text/javascript">

  var flashvars = {};
  var params = {
    menu: "false",
    allowScriptAccess: "always",
    scale: "noscale"
  };
  var attributes = {
    id: "youtubewrapper"
  };

  swfobject.embedSWF("YouTubeIntegrationDemo.swf", "flashcontent", "960", "500", "9.0.0", "_assets/swf/expressInstall.swf", flashvars, params, attributes);
  
  //init the youTubeLoader JavaScript methods
  SWFID = "youtubewrapper"
    
</script>

Der allowScriptAccess-Parameter im Code ist erforderlich, damit die Datei des Players Funktionen auf der zugehörigen HTML-Seite aufrufen kann, da der Chromeless Player auf einer anderen Domain als die XHTML-Seite gehostet wird.

Das einzige Attribut, das wir übergeben, ist die ID des eingebetteten Objekts, in diesem Fall „youtubewrapper“. Anhand dieser ID wird in der Datei „youTubeLoader.js“ mithilfe von getElementById() eine Referenz zum Player abgerufen.

swfobject.embedSWF lädt den YouTube-Player und bettet ihn auf deiner Seite ein.

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

• swfUrlStr: Dies ist die URL der SWF-Datei. Beachte, dass wir die Parameter enablejsapi und playerapiid an die normale YouTube-SWF-URL angehängt haben, um JavaScript API-Aufrufe zu ermöglichen.
• replaceElemIdStr – Dies ist die HTML DIV-ID, die mit dem eingebetteten Inhalt ersetzt werden soll. Im obigen Beispiel ist das ytapiplayer.
• widthStr: Breite des Players.
• heightStr: Höhe des Players.
• swfVersionStr: Die Version, die mindestens erforderlich ist, damit der Nutzer den Inhalt sehen kann. In unserem Fall handelt es sich dabei um die Version 8. Sollte der Nutzer diese Voraussetzung nicht erfüllen, wird die Standardtextzeile im HTML DIV angezeigt.
• xiSwfUrlStr: (optional) Gibt die URL der SWF-Datei für die Expressinstallation an. Wird in diesem Beispiel nicht verwendet.
• flashVarsObj: (optional) Gibt FlashVars-Variablen in Name:Wert-Paaren an. Wird in diesem Beispiel nicht verwendet.
• parObj (optional): Die Parameter für das eingebettete Objekt. In diesem Fall haben wir allowScriptAccess festgelegt.
• AttObj: (optional) Die Attribute für das eingebettete Objekt. In diesem Fall haben wir die ID auf myytplayer festgelegt.

Nähere Informationen findest du in der SWFObject-Dokumentation.

SWFID ≡ speichert einen Verweis auf die ID des eingebetteten Objekts, das von der JavaScript API verwendet werden kann. Sie müssen dieselbe ID für das eingebettete Objekt verwenden, die Sie dem SWF-Objekt zugewiesen haben.

SWFID ≡ "youtubewrapper"

Jetzt sollten Sie Ihr Projekt erfolgreich testen können. Das YouTubeLoader-Objekt sollte den Chromeless-Player laden und der YouTubeLoaderEvent.LOADED-Ereignis-Handler sollte erfolgreich aufgerufen werden. Jetzt können wir eine Videoanfrage senden und mit dem YouTubeLoader-Objekt interagieren.

Mit dem Spieler interagieren

Da bei diesem Ansatz zum Erstellen eines ActionScript 3.0-Wrappers für den Chromeless-Player die ExternalInterface-Klasse von ActionScript verwendet wird, können wir jetzt jeden der Vorgänge in der YouTube JavaScript Player API verwenden, um den geladenen Player zu steuern. Die Datei "youTubeLoader.js" enthält JavaScript-Datei, die sich in deploy/_assets/js/ befindet (Abbildung 3), enthält die meisten verfügbaren Funktionen. Jede Vorgangsfunktion prüft vor der Ausführung zuerst anhand der Funktion checkObj, ob die Variable SWFID korrekt festgelegt wurde.

//------------------------------------
// UTILITY METHODS
//------------------------------------

function checkObj () {
  // alert("youTubeLoader.js : checkObj");
  if (SWFID) {
    createObj();
    return true;
  } else{
    alert("YouTubeLoader: In order to call methods within a swf, you must first set the variable \"SWFID\"!");
    return false;
  };
}
  
//------------------------------------
// YOUTUBE METHODS
//------------------------------------

function loadVideoById(id, startSeconds) {
  // alert("youTubeLoader.js : loadVideoById");
  if (checkObj()) {
    obj.loadVideoById(id,startSeconds);
  };
};

function cueNewVideo(id, startSeconds) {
  // alert("youTubeLoader.js : loadVideoById");
  if (checkObj()) {
    obj.cueVideoById(id, startSeconds);
  }
}

function clearVideo() {
  // alert("youTubeLoader.js : clearVideo");
  if (checkObj()) {
    obj.clearVideo();
  }
}

// plus 17 more...

Da das Endziel unseres ActionScript 3.0-Wrappers für den Chromeless Player darin besteht, eine nahtlose Interaktion mit dem YouTube-API innerhalb eines Flash/Flex-Projekts von Action 3.0 zu ermöglichen, haben wir die gleichen öffentlichen Methoden zu "YouTubeLoader.as" hinzugefügt. Klassendatei in src/choppingblock/video/ (Abbildung 2). Das bedeutet, dass Sie genau die gleichen Vorgänge direkt an das YouTubeLoader-Objekt in Flash/Flex aufrufen können. In der Kursdatei finden Sie Folgendes:

// ------------------------------------
// YOUTUBE METHODS
// ------------------------------------

public function loadVideoById (id:String, startSeconds:Number = 0):void{
  //trace("YouTubeLoader: loadVideoById");
  ExternalInterface.call("loadVideoById", id, startSeconds);
};

public function cueNewVideo (id:String, startSeconds:Number = 0):void{
  //trace("YouTubeLoader: cueNewVideo");
  ExternalInterface.call("cueNewVideo", id, startSeconds);
};

public function clearVideo ():void{
  //trace("YouTubeLoader: clearVideo");
  ExternalInterface.call("clearVideo");
};

// plus 17 more...

Bei den Methoden vom Typ "ActionScript" wird die Klasse ExternalInterface verwendet, um einfach die entsprechende Funktion innerhalb des JavaScript-APIs aufzurufen.

Video anfragen

Du kannst jetzt ein Video direkt in deiner ActionScript 3.0-Datei anfordern, indem du Funktionen mit der Playerreferenz aufrufst. Wenn Sie beispielsweise das Video wiedergeben möchten, wenn ein Nutzer auf eine Schaltfläche klickt, fügen Sie Ihrer Schaltfläche einen MouseEvent.CLICK-Ereignis-Listener hinzu. Ein Beispiel:

// assuming your button was called 'myButton'
myButton.addEventListener(MouseEvent.CLICK, youtubeLoadVideoHandler);

Und erstellen Sie eine Ereignis-Handler-Methode, um die Anfrage zu verarbeiten. Ein Beispiel:

private function youtubeLoadVideoHandler (event:MouseEvent):void{
  
  // assuming that '_youTubeLoader' is a reference to your YouTubeLoader object
  _youTubeLoader.loadVideoById( "u1zgFlCw8Aw" );
};

Außerhalb der Flash-/Flex-Datei können Sie optional ein Video anfordern, indem Sie die entsprechende JavaScript-Funktion direkt aufrufen. Ein Beispiel:

 <a href="javascript:loadVideoById('u1zgFlCw8Aw')">Play</a> 

Zusätzliche Aufrufe

Weitere Aufrufe funktionieren genau wie Anfordern eines Videos: In ActionScript 3 können Sie einfach Methoden mithilfe der Playerreferenz aufrufen. Eine vollständige Liste der verfügbaren Methoden finden Sie unten.

Abonnieren von Ereignissen

Du kannst Ereignisse abonnieren, indem du der Playerreferenz einen Ereignis-Listener hinzufügst. Um beispielsweise benachrichtigt zu werden, wenn sich der Player-Status ändert, kannst du einen Ereignis-Listener für YouTubeLoaderEvent.STATE_CHANGE hinzufügen. Ein Beispiel:

// assuming that '_youTubeLoader' is a reference to your YouTubeLoader object
_youTubeLoader.addEventListener(YouTubeLoaderEvent.STATE_CHANGE, youTubePlayerStateChangeHandler);

Erstellen Sie eine Event-Handler-Methode, um die Anfrage zu verarbeiten. Ein Beispiel:

private function youTubePlayerStateChangeHandler (event:YouTubeLoaderEvent):void{
  //trace("YouTubeIntegrationDemo: youTubePlayerStateChangeHandler");
  
  _stateField.text = event.state;
};

Verfügbare Vorgänge

Damit du die Methoden der YouTubePlayer API aufrufen kannst, musst du zuerst in deiner ActionScript-Datei eine Instanz der Klasse „YouTubePlayer“ erstellen und einen Verweis auf das YouTubePlayer-Objekt speichern, das du steuern möchtest. Rufen Sie dazu Folgendes auf:

var _youTubeLoader:YouTubeLoader;
_youTubeLoader = new YouTubeLoader();

Public Methods

player.loadVideoById(id:String, startSeconds:Number = 0):void

Lädt und gibt ein Video basierend auf der angegebenen ID wieder.

player.cueNewVideo(id:String, startSeconds:Number = 0):void

Das Video wird anhand der angegebenen ID geladen, aber nicht automatisch wiedergegeben.

player.clearVideo():void

Löscht das aktuell positionierte/geladene Video.

player.setSize(w:Number, h:Number):void

Legt die Größe der YouTubePlayer-Instanz fest.

player.play():void

Spielt das aktuell cued/geladene Video ab.

player.pause():void

Pausiert das aktuell angesagte/geladene Video.

player.stop():void

Stellt das aktuell cued/geladene Video an.

player.seekTo(seconds:Number):void

Springt im aktuell angegebenen/geladenen Video zur angegebenen Zeit.

player.getPlayerState():String

Gibt den aktuellen Status des aktuell positionierten/geladenen Videos zurück.

player.getBytesLoaded():Number

Gibt den Wert der aktuell geladenen Bytes des aktuell angegebenen/geladenen Videos zurück.

player.getBytesTotal():Number

Gibt den Wert der insgesamt geladenen Byte des aktuell positionierten/geladenen Videos zurück.

player.getCurrentTime():Number

Gibt die aktuelle Zeitposition des aktuell positionierten/geladenen Videos zurück.

player.getDuration():Number

Gibt die aktuelle Dauer des aktuell angegebenen/geladenen Videos zurück.

player.getStartBytes():Number

Gibt die Startbyte des aktuell positionierten/geladenen Videos zurück.

player.setVolume(newVolume:Number):void

Legt die Lautstärke des aktuell angesagten/geladenen Videos fest.

player.getVolume():Number

Gibt die aktuelle Lautstärke des aktuell positionierten/geladenen Videos zurück.

player.mute():void

Speichert die aktuelle Lautstärke und ändert die Lautstärke des aktuell positionierten/geladenen Videos auf 0.

player.unmute():void

Stellt die Lautstärke des aktuell angesteuerten/geladenen Videos auf den zuletzt gespeicherten Wert zurück, wenn es stummgeschaltet ist.

player.getEmbedCode():String

Gibt den aktuellen YouTube-Einbettungscode des aktuell positionierten/geladenen Videos zurück.

player.getVideoUrl():String

Gibt die aktuelle YouTube-Video-URL des aktuell positionierten/geladenen Videos zurück.

Ereignisse

YouTubeLoaderEvent.LOADED

Wird ausgelöst, sobald der Chromeless-Player geladen wurde und bereit ist, Vorgangsanfragen zu akzeptieren.

YouTubeLoaderEvent.STATE_CHANGE

Wird immer dann ausgelöst, wenn sich der Status des Players ändert. Die YouTubeLoader-Klasse übersetzt die JavaScript API-Nummern in ihre zugehörigen Stringwerte. Die YouTubeLoaderEvent-Klasse speichert das aktuelle Ereignis in einer Variablen namens state. Mögliche Werte sind "unstarted", "ended", "play", "paused", "buffering" und "video cued". Wenn die Datei zum ersten Mal geladen wird, sendet sie ein Ereignis, das nicht gestartet wurde. Wenn das Video positioniert und bereit für die Wiedergabe ist, wird ein Video-cued-Ereignis gesendet.

YouTubeLoaderEvent.IO_ERROR

Wird ausgelöst, wenn ein Fehler im Player auftritt Es sind zwei Fehlercodes möglich: 100 wird gesendet, wenn das angeforderte Video nicht gefunden wird. Das ist der Fall, wenn ein Video aus irgendeinem Grund entfernt oder als privat gekennzeichnet wurde. „101“ wird gesendet, wenn das angeforderte Video nicht in den eingebetteten Playern wiedergegeben werden kann.

Anmerkungen zur Demo

Zu Demonstrationszwecken wollten wir die XHTML-Formularfelder, Schaltflächen und die Anzeigeoberfläche unter dem eingebetteten ActionScript 3-Wrapper einfügen. Damit die SWF-Datei UND die XHTML-Datei gleichzeitig aktualisiert werden, mussten wir zwei Codezeilen in die JavaScript-Datei „youTubeLoader.js“ im Verzeichnis „deploy/_assets/js/“ einfügen (Abbildung 3). Die folgenden beiden Zeilen [69, 79] sollten Sie entfernen, wenn Sie diese Datei in Ihr Projekt integrieren:

//------------------------------------
// SPECIAL YOUTUBE EVENT METHODS
//------------------------------------

function onYouTubePlayerReady(playerId) {

  if (checkObj()) {	
    obj.addEventListener("onStateChange", "onytplayerStateChange");
  };

  // PLEASE NOTE: For the purpose of this demo:
  // This calls a secondary method located in the index.html file allowing the html display to update.
  // You will most likely not need this, it's gross, remove this when you implement this code.
  secondaryOnYouTubePlayerReady(playerId);
}

function onytplayerStateChange(newState) {
    //alert("Player's new state: " + newState);
  obj.playerStateUpdateHandler(newState);

  // PLEASE NOTE: For the purpose of this demo:
  // This calls a secondary method located in the index.html file allowing the html display to update.
  // You will most likely not need this, it's gross, remove this when you implement this code.
  secondaryOnytplayerStateChange(newState)
}

Bei der Demo-Datei und den enthaltenen ActionScript-Bibliotheken handelt es sich um kostenlose Software. Sie können sie weiterverbreiten und/oder gemäß den Bedingungen der GNU Lesser General Public License ändern. Wir versenden diese Dateien in der Hoffnung, dass sie nützlich sind, jedoch ohne Gewährleistung.

Fazit

In diesem Artikel, den demo und Quelldateien, solltest du dir einen soliden Überblick über eine relativ einfache und zuverlässige Lösung für die Integration der YouTube API und der eingebetteten Player in eine ActionScript 3-Umgebung bieten. Dabei wird die Wrapper-Bibliothek verwendet, die wir für unsere eigenen Projekte entwickelt haben. Da ich einen Großteil des Codes kommentiert habe, ist es idealerweise recht einfach, die Bibliotheken zu erkunden und wiederzuverwenden. Es hat aber auch seine Grenzen und es gibt immer Verbesserungsmöglichkeiten, Refactoring und Optimierungen. Wenn Sie diesbezügliche Anmerkungen haben, können Sie sich gerne mit mir in Verbindung setzen.

Biografie des Autors

Matthew Richmond blickt auf 14 Jahre Erfahrung in den Bereichen interaktive Design, Entwicklung und Architektur zurück. Wenn er nicht im Studio ist, unterrichtet er an der School of Visual Arts digitale Illustrations-/Fotografietechniken und fortgeschrittenes ActionScript. Matthew ist Gründungspartner und Designer bei choppingblock.com.