Wrapper ActionScript 3.0 dla odtwarzacza Chromeless

Ten artykuł został napisany i przesłany przez zewnętrznego dewelopera. Zespół YouTube ds. interfejsów API i narzędzi dziękuje Matthew Richmondowi za jego czas i doświadczenie.

Matthew Richmond, The Chopped Block, Inc.
Październik 2008 r.

• Wprowadzenie
• Ważne materiały
• Więcej informacji
  • Omówienie prezentacji funkcji wrappera
  • Tworzenie obiektu YouTubeLoader
  • Wstawianie pliku SWF i łączenie kodu JavaScript youTubeLoader
• Interakcja z graczem
  • Wysyłanie prośby o odtworzenie filmu
  • Wywoływanie dodatkowych połączeń
  • Subskrybowanie zdarzeń
• Dostępne operacje
• Uwagi dotyczące wersji demonstracyjnej
• Podsumowanie

Wprowadzenie

W tym artykule przedstawię i pokrótce przedstawię niezawodny opakowanie ActionScript 3.0 przeznaczone do odtwarzacza YouTube Chromeless. Opakowanie korzysta z klasy ExternalInterface w ActionScript i interfejsu JavaScript API w YouTube.

Dzięki narzędziom YouTube Player i Chromeless Player od Google projektanci i programiści mogą szybko i łatwo integrować możliwości YouTube w swoich projektach internetowych. Ta metoda jest idealna w przypadku małych projektów o stałym budżecie, które nie pozwalają na hosting wideo, oraz w przypadku dużych projektów, które są przydatne dla klientów, którzy chcą zapewnić użytkownikom spersonalizowaną obsługę, nie tracąc dystansu z odbiorcami w YouTube.

Rys.1: Zrzut ekranu z kodem opakowującym Action i DDR

Interfejs API Flash YouTube i odtwarzacze wbudowane w YouTube są napisane w języku JavaScript 2.0 i całkiem dobrze działają. w przypadku projektów w języku JavaScript 3.0 płynna integracja staje się jednak nieco bardziej złożona. Mimo że odtwarzacze Actions 2.0 można łatwo załadować do pliku SWF SKU 3.0, nie można bezpośrednio przekazywać ani przekazywać żadnych funkcjonalnych wywołań. Jest to dodatkowo komplikowane, ponieważ plik SWF pochodzący z serwerów YourTube jest wczytywany do samego siebie. Nasz kod musi być w pełni o tym informowany i odpowiednio na nie zareagować. Na szczęście język ActionScript zawiera 2 możliwe obejścia, które umożliwiają ponowne połączenie tych zagnieżdżonych, ale odłączonych elementów: klasę LocalConnection lub ExternalInterface. W tej prezentacji skoncentrujemy się na drugiej z tych funkcji, ponieważ interfejs ExternalInterface bezproblemowo współpracuje z dobrze udokumentowanym interfejsem JavaScript API i dlatego dobrze współgra z każdą inną funkcją na stronie XHTML.

Ważne informacje

Zanim zaczniemy, oto lista dostępnych materiałów i plików. Wiele tematów omawianych w tym artykule można znaleźć bardziej szczegółowo w poniższych linkach.

• Wyświetl Papier do kodu Action 3.0 i pobierz pliki źródłowe.
• Oficjalna dokumentacja interfejsu API odtwarzacza JavaScript YouTube
• Dokumentacja klasy Adobe ExternalInterface
• Wstawianie obiektu SWF JavaScript Flash

Analiza

Omówienie opakowania demonstracyjnego

Rysunek 3. Plik JavaScript

Rys. 2. Pliki klas języka JavaScript

Wrapper ActionScript 3.0 składa się z 2 połączonych ze sobą części: plików klas ActionScript 3.0 znajdujących się w folderze src/choppingblock/video/ (patrz rys. 2) oraz pliku JavaScript „youTubeLoader.js” w folderze deploy/_assets/js/ (patrz rys. 3). Plik źródłowy Flash/Flex utworzy instancję klasy YouTubeLoader Action; na stronie XHTML osadzony jest plik Flash i rejestrowanie go za pomocą funkcji w pliku JavaScript YouTubeLoader. Ważne jest, aby zrozumieć, że od tego momentu wszystko, co YouTubeLoader robi w pliku Flash, jest kontrolowane przez funkcje JavaScriptu.

Ponieważ całą funkcjonalnością Flasha jest sterowana przez interfejs API JavaScript, NIE będzie można załadować żadnych treści YouTube do „filmu testowego” we Flashu. . Działa tylko wtedy, gdy jest umieszczony na stronie XHTML i prawidłowo połączony z funkcjami JavaScript youTubeLoader.

Uwaga: aby przetestować każde z tych wywołań, musisz uruchomić plik na serwerze internetowym lub zmienić ustawienia zabezpieczeń odtwarzacza Flash Player, ponieważ odtwarzacz Flash ogranicza połączenia między plikami lokalnymi a internetem.

Tworzenie obiektu YouTubeLoader

Zanim utworzysz instancję obiektu YouTubeLoader w projekcie Flash/Flex, musisz się najpierw upewnić, że pakiet (folder) wymaganych plików znajduje się w tym samym katalogu co projekt (patrz rys. 2) lub jest zdefiniowany w ścieżce klas. Następnie możesz zaimportować pliki pakietu:

import choppingblock.video.*;

Dzięki temu plik ActionScript ma dostęp do klas „YouTubeLoader.as” i „YouTubeLoaderEvent.as”. Teraz możesz utworzyć instancję klasy YouTubeLoader i wymagane detektory zdarzeń:

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

Jeśli plik JavaScript jest już na swoim miejscu i prawidłowo połączony, wywołanie funkcji youTubePlayerLoadedHandler powinno się powieść, a my będziemy gotowi do wysyłania żądań.

Wstawianie pliku SWF i łączenie z JavaScriptem youTubeLoader

Nie uda Ci się wczytać treści z YouTube, dopóki plik SWF nie zostanie umieszczony w pliku XHTML i połączony ze skryptem JavaScript youTubeLoader. Zalecamy użycie SWFObject w celu umieszczenia odtwarzaczy, które będą dostępne za pomocą interfejsu JavaScript API. Pozwoli to wykryć wersję Flash Playera użytkownika (interfejs API JavaScript wymaga programu Flash Player w wersji 8 lub nowszej) i zostanie usunięty link „Kliknij, aby aktywować element sterujący”. w przeglądarce Internet Explorer.

W części <head> pliku XHTML łączysz pliki KMZobject i YouTubeLoader:

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

Poniżej znajdziesz przykład użycia SWFObject w celu umieszczenia pliku SWF w języku JavaScript 3.0 z włączonym interfejsem JavaScript API, a następnie przekazanie odwołania do pliku SWFObject do interfejsu API YouTubeLoader JavaScript.

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

Parametr allowScriptAccess w kodzie jest potrzebny, aby plik SWF odtwarzacza mógł wywoływać funkcje na stronie HTML, na której się znajduje, ponieważ odtwarzacz Chromeless jest hostowany w innej domenie niż strona XHTML.

Jedynym atrybutem, który przekazujemy, jest identyfikator obiektu do wklejenia – w tym przypadku youtubewrapper. Tego identyfikatora będzie używać plik YouTubeLoader.js do uzyskania odniesienia do odtwarzacza za pomocą metody getElementById().

swfobject.embedSWF wczyta odtwarzacz z YouTube i umieści go na Twojej stronie.

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

• swfUrlStr – to URL pliku SWF. Pamiętaj, że do normalnego adresu URL SWF w YouTube dodaliśmy parametry enablejsapi i playerapiid, aby umożliwić wywołania interfejsu API JavaScript.
• replaceElemIdStr – identyfikator elementu DIV na stronie HTML, który zostanie zastąpiony umieszczoną treścią. W przykładzie powyżej jest to ytapiplayer.
• widthStr – szerokość odtwarzacza.
• heightStr – wysokość odtwarzacza.
• swfVersionStr – najniższa wersja wymagana do wyświetlenia treści przez użytkownika. W tym przypadku potrzebna jest wersja 8 lub nowsza. Jeżeli użytkownik nie ma oprogramowania w wersji 8 lub nowszej, to w tagu DIV zobaczy domyślną linię tekstu.
• xiSwfUrlStr – (opcjonalnie) określa adres URL pliku SWF do ekspresowej instalacji. Nieużywany w tym przykładzie.
• flashVarsObj – (opcjonalny) określa zmienne FlashVar w postaci par nazwa:wartość. Nieużywany w tym przykładzie.
• parObj – (opcjonalne) parametry umieszczonego obiektu. W tym przypadku ustawiliśmy allowScriptAccess.
• AttObj – (opcjonalne) atrybuty umieszczonego obiektu. W tym przypadku ustawiliśmy identyfikator na myytplayer.

Dokładniejsze objaśnienia znajdziesz w dokumentacji SWFObject.

SWFID ≡ przechowuje odwołanie do identyfikatora obiektu do umieszczania, którego ma użyć interfejs JavaScript API. Musisz użyć tego samego identyfikatora obiektu do osadzenia, który został podany w pliku SWF.

SWFID ≡ "youtubewrapper"

Na tym etapie możesz już bezbłędnie przetestować projekt. Obiekt YouTubeLoader powinien wczytać odtwarzacz Chromeless, a obsługa zdarzenia YouTubeLoaderEvent.LOADED powinna zostać wywołana. Teraz możemy wysłać żądanie wideo i wejść w interakcję z obiektem YouTubeLoader.

Interakcja z odtwarzaczem

Jako że ta metoda tworzenia opakowania kodu Action 3.0 dla odtwarzacza Chromeless korzysta z klasy ExternalInterface w języku Action, do sterowania załadowanym odtwarzaczem możemy użyć dowolnej operacji dostępnej w interfejsie YouTube JavaScript Player API. Jeśli zajrzysz do pliku JavaScript „youTubeLoader.js” w folderze deploy/_assets/js/ (rysunek 3), zobaczysz, że zawiera on większość dostępnych funkcji. Każda funkcja operacji najpierw sprawdza funkcję checkObj, aby przed wykonaniem sprawdzić, czy zmienna SWFID została prawidłowo skonfigurowana.

//------------------------------------
// 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...

Ponieważ celem naszego opakowania ActionScript 3.0 dla odtwarzacza bez Chrome jest zapewnienie płynnej interakcji z interfejsem YouTube API z poziomu projektu ActionScript 3.0 Flash/Flex, dodaliśmy te same metody publiczne do pliku klasy „YouTubeLoader.as” znajdującego się w folderze src/choppingblock/video/ (rysunek 2). Oznacza to, że te same operacje możesz wywoływać bezpośrednio do obiektu YouTubeLoader Object we Flashu/Flex. W pliku zajęć znajdziesz:

// ------------------------------------
// 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...

Metody ActionScript używają klasy ExternalInterface do wywołania odpowiedniej funkcji w interfejsie JavaScript API.

Prośba o film

Teraz możesz zażądać filmu wideo z pliku ActionScripcie 3.0, wywołując funkcje przy użyciu odwołania do odtwarzacza. Jeśli np. chcesz odtworzyć film, gdy użytkownik kliknie przycisk, dodaj do niego detektor zdarzenia MouseEvent.CLICK. W ten sposób:

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

Utwórz metodę modułu obsługi zdarzeń, która obsłuży żądanie. W ten sposób:

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

Poza plikiem Flash/Flex możesz opcjonalnie zażądać filmu, bezpośrednio wywołując odpowiednią funkcję JavaScript. W ten sposób:

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

Wybieranie dodatkowych połączeń

Połączenia dodatkowe działają tak samo jak żądanie filmu. z poziomu języka JavaScript 3 możesz po prostu wywoływać metody przy użyciu odwołania do odtwarzacza. Poniżej znajdziesz pełną listę dostępnych metod.

Subskrypcja zdarzeń

Dodanie odbiornika do odniesień do odtwarzacza pozwala subskrybować zdarzenia. Aby na przykład otrzymywać powiadomienia o zmianie stanu odtwarzacza, dodaj detektor zdarzeń dla YouTubeLoaderEvent.STATE_CHANGE. W ten sposób:

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

Utworzyć też metodę obsługi zdarzeń, która będzie obsługiwała żądanie. W ten sposób:

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

Dostępne operacje

Aby wywoływać metody interfejsu API YouTubePlayer, musisz najpierw utworzyć instancję klasy YouTubePlayer w pliku JavaScript i zapisać odwołanie do obiektu YouTubePlayer, który chcesz kontrolować. Aby to zrobić, zadzwoń pod numer:

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

Metody publiczne

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

Ładuje i odtwarza film na podstawie określonego identyfikatora.

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

Wczytuje film, ale nie odtwarza go automatycznie na podstawie podanego identyfikatora.

player.clearVideo():void

Usuwa aktualnie wskazany/wczytany film.

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

Określa rozmiar wystąpienia YouTubePlayer.

player.play():void

Odtwarza aktualnie wskazany/wczytany film.

player.pause():void

Wstrzymuje aktualnie odtwarzany lub wczytywany film.

player.stop():void

Wstrzymuje aktualnie odtwarzany lub wczytany film.

player.seekTo(seconds:Number):void

Przechodzi do określonego punktu czasowego w obecnie odtwarzanym lub załadowanym filmie.

player.getPlayerState():String

Zwraca bieżący stan aktualnie odtwarzanego lub wczytanego filmu.

player.getBytesLoaded():Number

Zwraca wartość bieżących wczytanych bajtów aktualnie wskazanego/wczytanego filmu.

player.getBytesTotal():Number

Zwraca wartość łącznej liczby wczytanych bajtów aktualnie wskazanego/wczytanego filmu.

player.getCurrentTime():Number

Zwraca bieżącą pozycję w czasie bieżącego filmu z cue lub załadowanego filmu.

player.getDuration():Number

Zwraca bieżący czas trwania aktualnie odtwarzanego lub wczytanego filmu.

player.getStartBytes():Number

Zwraca bajty początkowe bieżącego filmu z podpowiedzią lub załadowanego.

player.setVolume(newVolume:Number):void

Ustawia głośność aktualnie odtwarzanego lub wczytanego filmu.

player.getVolume():Number

Zwraca bieżącą głośność aktualnie wskazanego/wczytanego filmu.

player.mute():void

Zapisuje bieżącą głośność i zmienia głośność aktualnie odtwarzanego filmu na 0.

player.unmute():void

Zwraca głośność aktualnie odtwarzanego lub załadowanego filmu do ostatniej zapisanej wartości wyciszenia.

player.getEmbedCode():String

Zwraca bieżący kod YouTube do umieszczenia na stronie dla aktualnie wskazanego/wczytanego filmu.

player.getVideoUrl():String

Zwraca bieżący adres URL filmu w YouTube, który jest obecnie odtwarzany lub wczytywany.

Wydarzenia

YouTubeLoaderEvent.LOADED

Uruchamiany po zakończeniu ładowania odtwarzacza Chromeless i gotowości do przyjmowania wywołań operacyjnych.

YouTubeLoaderEvent.STATE_CHANGE

Wywoływane, gdy zmienia się stan odtwarzacza. Klasa YouTubeLoader przekształca liczby interfejsu JavaScript API w powiązane wartości ciągu znaków, a klasa YouTubeLoaderEvent przechowuje bieżące zdarzenie w zmiennej o nazwie state. Możliwe wartości to nierozpoczęte, zakończone, odtwarzanie, wstrzymanie, buforowanie, film z podkładem dźwiękowym. Gdy plik SWF zostanie wczytany po raz pierwszy, wyemituje nierozpoczęte zdarzenie. Gdy film jest gotowy do odtworzenia, wyśle zdarzenie wideo z podpowiedzią.

YouTubeLoaderEvent.IO_ERROR

Wywoływane, gdy wystąpi błąd w odtwarzaczu. Możliwe są 2 kody błędów: 100 jest przesyłany, gdy nie można znaleźć żądanego filmu. Dzieje się tak, gdy film został usunięty (z jakiegokolwiek powodu) lub oznaczony jako prywatny. 101 jest transmitowany, gdy żądany film nie może być odtworzony w odtwarzaczach umieszczonych na stronie.

Uwagi na temat demonstracji

W celu demonstracji chcieliśmy umieścić pola formularza XHTML, przyciski i interfejs wyświetlania pod wbudowanym opakowaniem ActionScript 3. Aby plik SWF i zaktualizowany XHTML były aktualizowane jednocześnie, musieliśmy umieścić 2 wiersze kodu w pliku JavaScript „youTubeLoader.js” znajdującym się w folderze „deploy/_assets/js/” (patrz rys. 3). Po zintegrowaniu tego pliku z projektem usuń te 2 wiersze [69, 79]:

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

Plik demonstracyjny i dołączone biblioteki ActionScript są wolnym oprogramowaniem: możesz je rozpowszechniać lub modyfikować zgodnie z warunkami GNU Lesser General Public License. Pliki te rozpowszechniasz w nadziei, że będą przydatne, ale nie są objęte żadnymi gwarancjami.

Podsumowanie

W tym artykule, demo i plikach źródłowych znajdziesz dokładne omówienie jednego stosunkowo prostego i niezawodnego rozwiązania do integracji interfejsu YouTube API i umieszczonych na niej odtwarzaczy ze środowiskami języka Action, wykorzystujących bibliotekę opakowań, którą stworzyliśmy na potrzeby naszych własnych projektów. Ponieważ skomentowałem znaczną część kodu, przeglądanie i ponowne wykorzystanie bibliotek powinno być dość łatwe. Nie ma jednak w tym przypadku żadnych ograniczeń i zawsze jest miejsce na ulepszenia, przefaktorowanie i rozszerzenie. Jeśli macie jakieś uwagi na ten temat, proszę o kontakt.

Biogram autora

Matthew Richmond może pochwalić się 14-letnim doświadczeniem w tworzeniu interaktywnego projektowania, programowaniu i architekturze. Poza pracą uczy się technik ilustracji cyfrowych i fotografii oraz zaawansowanego języka Action w szkole Sztuk Wizualnych. Matthew jest współzałożycielem i projektantem w firmie choppingblock.com.