ActionScript 3.0-Wrapper für Chromeless Player

Dieser Artikel wurde von einem externen Entwickler verfasst. Das YouTube APIs- und YouTube-Team dankt Matthew Richmond für seine Zeit und seine Fachkenntnisse.


Matthew Richmond, The Chopping Block, Inc.
Oktober 2008

Einführung

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

Mit den YouTube Player-Tools und dem Chromeless Player von Google können Designer/Entwickler die Vorteile von YouTube schnell und einfach in ihre Onlineprojekte einbinden. Dieser Ansatz ist ideal für kleine Projekte mit festen Budgets, in denen keine Videos gehostet werden können, sowie für große Projekte, bei denen Kunden eine individuelle Nutzererfahrung wünschen, ohne sich von ihrer YouYube-Zielgruppe abwenden zu müssen.

Screenshot: ActionScript 3.0-Wrapper
Abbildung 1: Screenshot: Wrapper für ActionScript 3.0

Das Flash-API und die eingebetteten Player von YouTube sind geschrieben und funktionieren gut mit ActionScript 2.0. Bei einem Projekt mit ActionScript 3.0 wird die nahtlose Integration jedoch etwas komplexer. Es ist zwar einfach, die ActionScript 2.0-Player in eine ActionScript 3.0-SWF-Datei zu laden, es ist jedoch nicht möglich, Funktionsaufrufe direkt zu kommunizieren oder an den geladenen Player weiterzuleiten. Dies ist noch komplizierter, weil die SWF-Datei von den YouTube-Servern ein Video selbst lädt. Unser Wrapper muss sich dieser Tatsache bewusst sein und entsprechend reagieren. Glücklicherweise enthält die ActionScript-Sprache zwei mögliche Problemumgehungen für die erneute Verbindung dieser verschachtelten, aber nicht verbundenen Komponenten: die LocalConnection-Klasse oder die ExternalInterface-Klasse. Der Schwerpunkt dieser Demo liegt auf Letzterem, da die ExternalInterface nahtlos mit der gut dokumentierten JavaScript API funktioniert und daher mit allen anderen Elementen auf der XHTML-Seite gut funktioniert.

Wichtige Ressourcen

Bevor wir beginnen, möchten wir Ihnen hier eine Liste mit ähnlichen Ressourcen und Dateien zur Verfügung stellen. Viele der in diesem Artikel behandelten Themen werden unter den folgenden Links ausführlicher beschrieben.

Vergraben

Wrapper-Demo – Übersicht

ActionScript-Klassendateien
Abbildung 3: JavaScript-Datei
ActionScript-Klassendateien
Abbildung 2: ActionScript-Klassendateien

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

Da alle Funktionen in Flash über die JavaScript API gesteuert werden, kannst du KEINE YouTube-Inhalte in den Testfilm-Player von Flash laden. Es funktioniert nur, wenn es in eine XHTML-Seite eingebettet und ordnungsgemäß mit den JavaScript-Funktionen von YouTubeLoader verbunden ist.

Hinweis: Um einen dieser Aufrufe zu testen, muss deine Datei auf einem Webserver ausgeführt werden oder die Sicherheitseinstellungen deines 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 zuerst prüfen, ob sich das Paket (der Ordner) der erforderlichen Dateien im selben Verzeichnis wie das Projekt befindet (siehe Abbildung 2) oder mit dem Classpath Ihres Projekts definiert ist. Anschließend können Sie die Paketdateien importieren:

import choppingblock.video.*;

Dadurch können Sie über die ActionScript-Datei auf die Klassen „YouTubeLoader.as“ und „YouTubeLoaderEvent.as“ zugreifen. Jetzt können Sie eine Instanz der YouTubeLoader-Klasse 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 die JavaScript-Datei vorhanden ist und richtig verbunden ist, sollte youTubePlayerLoadedHandler erfolgreich aufgerufen werden und wir können Anfragen stellen.

Einbetten der SWF-Datei und Verbinden des JavaScript-Codes von YouTube

Du kannst erst dann Inhalte von YouTube laden, wenn deine SWF-Datei in eine XHTML-Datei eingebettet und mit dem YouTubeLoader-JavaScript verknüpft ist. Wir empfehlen die Verwendung von SWFObject zur Einbettung aller Player, auf die über die JavaScript API zugegriffen wird. So können Sie die Flash Player-Version des Endnutzers erkennen. Für die JavaScript API ist Flash Player 8 oder höher erforderlich. Außerdem wird das Kontrollkästchen zum Aktivieren dieses Steuerelements entfernt, wenn Sie den Player im Internet Explorer aufrufen.

Verbinden Sie im Abschnitt <head> der XHTML-Datei die SWF- und YouTube-Dateien:

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

Im Folgenden finden Sie ein Beispiel für die Verwendung von SWFObject zur Einbettung Ihrer ActionScript 3.0-SWF-Datei bei aktiviertem JavaScript API und zur Übergabe eines Verweises auf Ihre SWF-Datei an die JavaScript-API von YouTube.

<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 Parameter allowScriptAccess im Code ist erforderlich, damit die SWF-Datei des Players Funktionen auf der entsprechenden HTML-Seite aufrufen kann, da der Chromeless Player auf einer anderen Domain als der XHTML-Seite gehostet wird.

Das einzige Attribut, das wir übergeben, ist die ID des eingebetteten Objekts, in diesem Fall „youtubewrapper“. Diese ID wird von der Datei „youTubeLoader.js“ verwendet, um über „getElementById()“ einen Verweis auf den Player abzurufen.

swfobject.embedSWF lädt den Player von YouTube 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. Wir haben die Parameter enablejsapi und playerapiid an die normale SWF-URL von YouTube angehängt, um JavaScript API-Aufrufe zu ermöglichen.
  • replaceElemIdStr: Dies ist die HTML DIV-ID, die durch den eingebetteten Inhalt ersetzt wird. Im Beispiel oben ist es ytapiplayer.
  • widthStr: Breite des Players.
  • heightStr: Höhe des Players.
  • swfVersionStr: Die mindestens erforderliche Version, damit der Nutzer die Inhalte 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 die FlashVars in name:value-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 die JavaScript API verwenden kann. Sie müssen dieselbe ID des eingebetteten Objekts verwenden, das Sie der SWF-Datei zugewiesen haben.

SWFID ≡ "youtubewrapper"

Jetzt sollten Sie Ihr Projekt testen können. Das YouTubeLoader-Objekt sollte den Chromeless Player laden und der Event-Handler YouTubeLoaderEvent.LOADED 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 ein ActionScript 3.0-Wrapper für die Chromeless Player-Klasse auf die ExternalInterface-Klasse von ActionScript zurückgreift, können wir nun alle geladenen Player in der JavaScript JavaScript Player API steuern. Wenn Sie sich die JavaScript-Datei „youTubeLoader.js“ in Deploy/_assets/js/ (Abbildung 3) ansehen, werden Sie feststellen, dass sie die meisten verfügbaren Funktionen enthält. Jede Vorgangsfunktion prüft zuerst die Funktion checkObj, um zu prüfen, ob die Variable SWFID vor dem Ausführen 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 unser Ziel des ActionScript 3.0-Wrappers für den Chromeless Player darin besteht, von einem ActionScript 3.0-Flash-/Flex-Projekt aus nahtlos mit dem YouTube-API zu interagieren, haben wir der Klassendatei „YouTubeLoader.as“ (src/choppingblock/video/ in Abbildung 2) exakt dieselben öffentlichen Methoden hinzugefügt. Das bedeutet, dass die exakt gleichen Vorgänge direkt im FlashLoader-Objekt in Flash/Flex aufgerufen werden können. In der Kursdatei sehen 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...

Die ActionScript-Methoden verwenden die Klasse "ExternalInterface", um einfach die entsprechende Funktion innerhalb der JavaScript API aufzurufen.

Ein Video anfordern

Sie können jetzt in Ihrer ActionScript 3.0-Datei ein Video anfordern, indem Sie Funktionen mithilfe der Player-Referenz aufrufen. Wenn Sie das Video beispielsweise abspielen 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 eine Event-Handler-Methode erstellen, 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 Ihrer 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 Anrufe senden

Zusätzliche Aufrufe funktionieren genau wie Ein Video anfordern. In ActionScript 3 kannst du einfach Methoden mithilfe der Player-Referenz 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. Wenn du beispielsweise benachrichtigt werden möchtest, wenn sich der Player-Status ändert, musst du für YouTubeLoaderEvent.STATE_CHANGE einen Ereignis-Listener hinzufügen. Ein Beispiel:

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

und eine Event-Handler-Methode erstellen, um die Anfrage zu verarbeiten. Ein Beispiel:


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

Verfügbare Vorgänge

Zum Aufrufen der YouTubePlayer API-Methoden musst du zuerst eine Instanz der YouTubePlayer-Klasse in deiner ActionScript-Datei erstellen und eine Referenz 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
Ladet ein Video anhand der angegebenen ID und gibt es wieder.
player.cueNewVideo(id:String, startSeconds:Number = 0):void
Wird basierend auf der angegebenen ID geladen, aber nicht automatisch wiedergegeben.
player.clearVideo():void
Aktuell gelöschtes Video wird gelöscht/geladen.
player.setSize(w:Number, h:Number):void
Legt die Größe der YouTubePlayer-Instanz fest.
player.play():void
Spielt das derzeit positionierte/geladene Video.
player.pause():void
Pausiert das aktuell positionierte/geladene Video.
player.stop():void
Stoppt das derzeit positionierte/geladene Video.
player.seekTo(seconds:Number):void
Spult zur angegebenen Zeit innerhalb des derzeit positionierten/geladenen Videos.
player.getPlayerState():String
Gibt den aktuellen Status des derzeit positionierten/geladenen Videos zurück.
player.getBytesLoaded():Number
Gibt den Wert der aktuell geladenen Byte des aktuell Cu/Laden geladen.
player.getBytesTotal():Number
Gibt den Gesamtwert der Bytes zurück, die für das aktuell Cu/Laden geladen sind.
player.getCurrentTime():Number
Gibt die aktuelle Position des derzeit positionierten/geladenen Videos zurück.
player.getDuration():Number
Gibt die aktuelle Dauer des aktuell positionierten/geladenen Videos zurück.
player.getStartBytes():Number
Gibt die Startbyte des derzeit positionierten/geladenen Videos zurück.
player.setVolume(newVolume:Number):void
Legt die Lautstärke des aktuell positionierten/geladenen Videos fest.
player.getVolume():Number
Gibt die aktuelle Lautstärke des derzeit positionierten/geladenen Videos zurück.
player.mute():void
Speichert die aktuelle Lautstärke und ändert die Lautstärke des derzeit positionierten/geladenen Videos auf 0.
player.unmute():void
Setzt die Lautstärke des derzeit positionierten/geladenen Videos auf den zuletzt gespeicherten Wert zurück, wenn es stummgeschaltet wird.
player.getEmbedCode():String
Gibt den aktuellen YouTube-Einbettungscode des derzeit positionierten/geladenen Videos zurück
player.getVideoUrl():String
Gibt die aktuelle URL des YouTube-Videos des derzeit positionierten/geladenen Videos zurück.

Events

YouTubeLoaderEvent.LOADED
Ausgelöst, sobald der Chromeless Player vollständig geladen wurde und zum Annehmen von Vorgangsaufrufen bereit ist.
YouTubeLoaderEvent.STATE_CHANGE
Wird ausgelöst, wenn sich der Player-Status ändert Die YouTubeLoader-Klasse übersetzt die JavaScript API-Nummern in die zugehörigen Stringwerte. Die YouTubeLoaderEvent-Klasse speichert das aktuelle Ereignis in einer Variablen namens state. Mögliche Werte sind „started“, „beendet“, „playing“, „paused“, „buffering“ und „video cued“. Beim ersten Laden der SWF-Datei wird ein nicht gestartetes Ereignis gesendet. 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 gibt zwei Fehlercodes: 100 wird gesendet, wenn das angeforderte Video nicht gefunden wurde. Das passiert, wenn ein Video aus irgendeinem Grund entfernt wurde oder als privat gekennzeichnet wurde. 101 wird gesendet, wenn das angeforderte Video die Wiedergabe in den eingebetteten Playern nicht zulässt.

Hinweise zur Demo

Zu Demonstrationszwecken sollen die XHTML-Formularfelder, Schaltflächen und die Benutzeroberfläche unter dem eingebetteten ActionScript 3-Wrapper eingefügt werden. Um die SWF-Datei UND das XHTML-Update gleichzeitig zu aktualisieren, mussten wir zwei Codezeilen in die JavaScript-Datei „youTubeLoader.js“ einfügen, die sich in „deploy/_assets/js/“ befindet (Abbildung 3). Sie sollten die folgenden beiden Zeilen entfernen [69, 79], 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)
}

Die Demodatei und die enthaltenen ActionScript-Bibliotheken sind kostenlos. Sie können sie unter den Bedingungen der GNU Lesser General Public License neu verteilen und/oder ändern. Diese Dateien werden in der Hoffnung bereitgestellt, dass sie nützlich, aber ohne Garantie sind.

Fazit

In diesem Artikel finden Sie Demo- und Quelldateien, die eine solide Übersicht über eine relativ einfache und zuverlässige Lösung zur Integration der YouTube API und der eingebetteten Player in ActionScript 3-Umgebungen in der Wrapper-Bibliothek für unsere eigenen Projekte bieten. Da ich einen großen Teil des Codes kommentiert habe, ist es im Idealfall relativ einfach, die Bibliotheken zu untersuchen und umzufunktionieren. Es gibt keine Einschränkungen und es gibt immer Raum für Verbesserungen, Refaktorierung und Verbesserung. Du kannst dich jederzeit mit mir in Verbindung setzen, wenn du eine Frage hast.

Biografie des Autors


Matthew

Matthew Richmond verfügt über 14 Jahre Erfahrung in den Bereichen interaktives Design, Entwicklung und Architektur. Wenn er nicht im Studio ist, kann er an der School of Visual Arts Technik mit digitalen Illustrations-/Fotografietechniken und einem erweiterten ActionScript unterrichten. Matthew ist Gründungspartner und Designer auf choppingblock.com.