Wrapper ActionScript 3.0 pour le lecteur Chromeless

Cet article a été rédigé et envoyé par un développeur externe. L'équipe API et outils YouTube tient à remercier Matthew Richmond pour le temps qu'il nous a consacré et l'expérience dont il nous a fait profiter.


Matthew Richmond, The Chopping Block, Inc.
Octobre 2008

Introduction

Dans cet article, je vais présenter et décrire brièvement un wrapper ActionScript 3.0 fiable pour le lecteur YouTube sans Chrome. Le wrapper exploite la classe ExternalInterface d'ActionScript et l'API JavaScript de YouTube.

Les outils YouTube Player et le lecteur Chromeless de Google ont permis aux concepteurs/développeurs d'intégrer rapidement et facilement la puissance de YouTube à leurs projets en ligne. Cette approche est idéale pour les petits projets à budget fixe qui ne permettent pas d'héberger de vidéos, ainsi que pour les projets à grande échelle pour les clients qui souhaitent une expérience personnalisée pour les utilisateurs finaux sans s'éloigner de leur audience YouTube.

Capture d'écran du code d'accompagnement de l'API 3.0
Figure 1 : Capture d'écran du wrapper ActionScript 3.0

L'API Flash et les lecteurs intégrés de YouTube sont écrits en ActionScript 2.0 et fonctionnent très bien avec ce langage. Toutefois, si votre projet est en ActionScript 3.0, l'intégration fluide devient un peu plus complexe. Même s'il est facile de charger les lecteurs ActionScript 2.0 dans un fichier .csv ActionScript 3.0, vous ne pouvez ni communiquer directement, ni transmettre des appels fonctionnels au lecteur chargé. La situation est encore plus complexe, car le fichier SWF provenant des serveurs de YouTube charge une vidéo en lui-même. Notre wrapper doit être pleinement conscient de ce fait et réagir en conséquence. Heureusement, le langage ActionScript propose deux solutions possibles pour reconnecter ces éléments imbriqués mais déconnectés : la classe LocalConnection ou la classe ExternalInterface. Cette démonstration se concentre sur ce dernier élément, car ExternalInterface fonctionne de manière transparente avec une API JavaScript bien documentée et, par conséquent, parfaitement compatible avec tout autre élément de la page XHTML.

Ressources importantes

Avant de commencer, voici une liste des ressources et des fichiers associés à votre disposition. La plupart des sujets abordés dans cet article sont décrits plus en détail à l'aide des liens ci-dessous.

Analyser les données

Présentation de la démonstration du wrapper

Fichiers de classe ActionScript
Figure 3: Fichier JavaScript
Fichiers de classe ActionScript
Figure 2 : Fichiers de classe ActionScript

Le wrapper ActionScript 3.0 se compose essentiellement de deux parties interconnectées : les fichiers de classe ActionScript 3.0 situés dans src/choppingblock/video/ (figure 2) et le fichier JavaScript "youTubeLoader.js" situé dans deploy/_assets/js/ (figure 3). Votre fichier source Flash/Flex crée une instance de la classe ActionScript YouTubeLoader. votre page XHTML intègre le fichier Flash et l'enregistre auprès des fonctions dans le fichier JavaScript youTubeLoader. Il est essentiel de comprendre que tout ce que YouTubeLoader fait dans le fichier Flash est contrôlé par les fonctions JavaScript.

Étant donné que toutes les fonctionnalités de Flash sont contrôlées par l'API JavaScript, vous ne pourrez PAS charger de contenu YouTube dans le film test de Flash. joueur. Il ne fonctionnera que lorsqu'il sera intégré à une page XHTML et correctement connecté aux fonctions JavaScript youTubeLoader.

Remarque: Pour tester ces appels, vous devez exécuter votre fichier sur un serveur Web ou modifier les paramètres de sécurité de Flash Player, car le lecteur Flash restreint les appels entre les fichiers locaux et Internet.

Créer un objet YouTubeLoader

Avant de pouvoir créer une instance de l'objet YouTubeLoader dans votre projet Flash/Flex, vous devez d'abord vous assurer que le package (dossier) des fichiers requis se trouve dans le même répertoire que votre projet (voir figure 2) ou qu'il est défini avec le chemin d'accès au classpath de votre projet. Vous pouvez ensuite importer les fichiers de package :

import choppingblock.video.*;

Ainsi, votre fichier ActionScript pourra accéder au fichier "YouTubeLoader.as" et "YouTubeLoaderEvent.as" classes. Vous pouvez maintenant créer une instance de la classe YouTubeLoader et les écouteurs d'événements nécessaires :

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

Si le fichier JavaScript est en place et connecté correctement, youTubePlayerLoadedHandler devrait être appelé correctement et nous sommes prêts à envoyer des requêtes.

Intégrer le fichier .csv et connecter le code JavaScript de YouTubeLoader

Vous ne pourrez pas charger de contenu depuis YouTube tant que votre fichier .csv n'aura pas été intégré dans un fichier XHTML et connecté au code JavaScript YouTubeLoader. Nous vous recommandons d'utiliser SWFObject pour intégrer tous les lecteurs auxquels vous accéderez à l'aide de l'API JavaScript. Vous pourrez ainsi détecter la version de Flash Player de l'utilisateur final (l'API JavaScript nécessite Flash Player 8 ou version ultérieure) et supprimer la case "Cliquez pour activer cette commande" lorsque vous utilisez Internet Explorer pour afficher le lecteur.

Dans la partie <head> de votre fichier XHTML, vous connectez les fichiers .csvobject et youTubeLoader:

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

Vous trouverez ci-dessous un exemple d'utilisation d'un élément SWFObject pour intégrer votre fichier .csv ActionScript 3.0 lorsque l'API JavaScript est activée, puis pour transmettre une référence à ce fichier dans l'API JavaScript de youTubeLoader.

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

Le paramètre allowScriptAccess du code est nécessaire pour permettre au lecteur SWF d'appeler des fonctions sur la page HTML contenante, car le lecteur Chromeless est hébergé sur un domaine différent de la page XHTML.

Le seul attribut que nous transmettons est l'ID de l'objet intégré, dans ce cas youtubewrapper. C'est cet ID que le fichier youTubeLoader.js utilisera pour obtenir une référence au lecteur à l'aide de getElementById().

swfobject.embedSWF chargera le lecteur depuis YouTube et l'intégrera à votre page.

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

  • swfUrlStr : il s'agit de l'URL du fichier CSV. Notez que nous avons ajouté les paramètres enablejsapi et playerapiid à l'URL SWF YouTube normale pour activer les appels d'API JavaScript.
  • replaceElemIdStr : ID de l'élément HTML DIV à remplacer par le contenu intégré. Dans l'exemple ci-dessus, il s'agit de ytapiplayer.
  • widthStr : largeur du lecteur.
  • heightStr : hauteur du joueur.
  • swfVersionStr : version minimale requise pour que l'utilisateur puisse voir le contenu. Dans cet exemple, la version 8 ou une version ultérieure est requise. Si l'utilisateur ne dispose pas de l'une de ces versions, le texte par défaut défini dans l'élément HTML DIV s'affiche.
  • xiSwfUrlStr (facultatif) : spécifie l'URL de votre fichier CSV d'installation express. Cet argument n'est pas utilisé dans cet exemple.
  • flashVarsObj (facultatif) : spécifie vos FlashVars sous forme de paires nom:valeur. Cet argument n'est pas utilisé dans cet exemple.
  • parObj (facultatif) : paramètres de l'objet d'intégration. Dans le cas présent, nous avons défini allowScriptAccess.
  • AttObj (facultatif) : attributs de l'objet intégré. Dans ce cas, nous avons défini l'ID sur myytplayer.

Consultez la documentation relative à la méthode SWFObject pour en savoir plus.

SWFID ≡ stocke une référence à l'ID de l'objet d'intégration à utiliser par l'API JavaScript. Vous devez utiliser le même ID de l'objet d'intégration que celui que vous avez attribué au fichier SWF.

SWFID ≡ "youtubewrapper"

À ce stade, vous devriez pouvoir tester votre projet. L'objet YouTubeLoader doit charger le lecteur Chromeless, et le gestionnaire d'événements YouTubeLoaderEvent.LOADED doit être appelé correctement. Nous sommes maintenant prêts à envoyer une requête vidéo et à interagir avec l'objet YouTubeLoader.

Interagir avec le lecteur

Étant donné que cette approche de création d'un wrapper ActionScript 3.0 pour le lecteur sans Chrome exploite la classe ExternalInterface d'ActionScript, nous pouvons désormais utiliser n'importe quelle opération de l'API YouTube JavaScript Player pour contrôler le lecteur chargé. Si vous regardez dans le fichier "youTubeLoader.js", fichier JavaScript situé dans "deploy/_assets/js/" (figure 3), vous constaterez qu'il contient la plupart des fonctions disponibles. Chaque fonction d'opération vérifie d'abord la fonction checkObj pour s'assurer que la variable SWFID a été correctement définie avant son exécution.

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

Étant donné que l'objectif final de notre wrapper ActionScript 3.0 pour le lecteur sans Chrome est d'offrir une interaction fluide avec l'API YouTube à partir d'un projet Flash/Flex ActionScript 3.0, nous avons ajouté exactement les mêmes méthodes publiques au fichier de classe "YouTubeLoader.as" situé dans src/choppingblock/video/ (figure 2). Cela signifie que vous pouvez appeler exactement les mêmes opérations directement sur l'objet YouTubeLoader dans Flash/Flex. Si vous examinez le fichier de classe, vous trouverez :

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

Les méthodes ActionScript utilisent la classe ExternalInterface pour appeler simplement la fonction appropriée dans l'API JavaScript.

Demander une vidéo

Vous pouvez désormais demander une vidéo à partir de votre fichier ActionScript 3.0 en appelant des fonctions à l'aide de la référence du lecteur. Par exemple, si vous souhaitez lire la vidéo lorsqu'un utilisateur clique sur un bouton, vous devez ajouter un écouteur d'événements MouseEvent.CLICK à votre bouton. Exemple :

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

Ensuite, créez une méthode de gestionnaire d'événements pour gérer la requête. Exemple :

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

En dehors de votre fichier Flash/Flex, vous pouvez demander une vidéo en appelant directement la fonction JavaScript correspondante. Exemple :

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

Émettre d'autres appels

Les appels supplémentaires fonctionnent exactement comme Demander une vidéo. À partir d'ActionScript 3, il vous suffit d'appeler des méthodes à l'aide de la référence du lecteur. La liste complète des méthodes disponibles est indiquée ci-dessous.

Activer les événements

Pour activer les événements, ajoutez un écouteur d'événements à la référence du lecteur. Par exemple, pour recevoir une notification lorsque l'état du lecteur change, ajoutez un écouteur d'événements pour YouTubeLoaderEvent.STATE_CHANGE. Exemple :

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

Ensuite, créez une méthode de gestionnaire d'événements pour gérer la requête. Exemple :


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

Opérations disponibles

Pour appeler les méthodes de l'API YouTubePlayer, vous devez d'abord créer une instance de la classe YouTubePlayer dans votre fichier ActionScript et stocker une référence à l'objet YouTubePlayer que vous souhaitez contrôler. Pour ce faire, appelez la commande suivante:

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

Méthodes publiques

player.loadVideoById(id:String, startSeconds:Number = 0):void
Charge et lit la vidéo en fonction de l'ID spécifié.
player.cueNewVideo(id:String, startSeconds:Number = 0):void
La vidéo se charge, mais n'est pas lue automatiquement en fonction de l'ID spécifié.
player.clearVideo():void
Efface la vidéo actuellement lue/chargée.
player.setSize(w:Number, h:Number):void
Définit la taille de l'instance YouTubePlayer.
player.play():void
Lance la vidéo en file d'attente/chargée.
player.pause():void
Met en pause la vidéo actuellement lue/téléchargée.
player.stop():void
Arrête la vidéo en file d'attente/chargée.
player.seekTo(seconds:Number):void
Recherche un moment précis de la vidéo en file d'attente/chargée.
player.getPlayerState():String
Renvoie l'état actuel de la vidéo actuellement lue/chargée.
player.getBytesLoaded():Number
Renvoie la valeur des octets actuellement chargés de la vidéo actuellement cued/chargée.
player.getBytesTotal():Number
Renvoie la valeur du nombre total d'octets chargés de la vidéo actuellement lue/chargée.
player.getCurrentTime():Number
Renvoie la position temporelle actuelle de la vidéo actuellement lue/chargée.
player.getDuration():Number
Renvoie la durée actuelle de la vidéo actuellement mise en file d'attente/chargée.
player.getStartBytes():Number
Renvoie les octets de départ de la vidéo actuellement en file d'attente/chargée.
player.setVolume(newVolume:Number):void
Définit le volume de la vidéo en file d'attente/chargée.
player.getVolume():Number
Renvoie le volume actuel de la vidéo actuellement lue/chargée.
player.mute():void
Stocke le volume actuel et définit le volume de la vidéo actuellement mise en attente/chargée sur 0.
player.unmute():void
Renvoie le volume de la vidéo actuellement mise en mémoire/chargée à la dernière valeur stockée lorsqu'elle est mise en sourdine.
player.getEmbedCode():String
Renvoie le code d'intégration YouTube actuel de la vidéo actuellement lue/chargée.
player.getVideoUrl():String
Renvoie l'URL YouTube actuelle de la vidéo actuellement lue/chargée.

Événements

YouTubeLoaderEvent.LOADED
Déclenché une fois que le lecteur Chromeless a terminé le chargement et est prêt à accepter les appels d'opérations.
YouTubeLoaderEvent.STATE_CHANGE
Se déclenche chaque fois que l'état du joueur change. La classe YouTubeLoader convertit les numéros de l'API JavaScript en valeurs de chaîne correspondantes, et la classe YouTubeLoaderEvent stocke l'événement actuel dans une variable appelée state. Les valeurs possibles sont "non démarré", "terminé", "lecture", "pause", "mise en mémoire tampon" et "en file d'attente". Lors du premier chargement du fichier CSV, un événement non démarré est diffusé. Lorsque la vidéo est mise en file d'attente et prête à être lue, elle diffuse un événement de mise en file d'attente de vidéo.
YouTubeLoaderEvent.IO_ERROR
Déclenchement lorsqu'une erreur se produit dans le lecteur. Deux codes d'erreur sont possibles: le code 100 est diffusé lorsque la vidéo demandée est introuvable. Cela se produit lorsqu'une vidéo a été supprimée (pour une raison quelconque) ou qu'elle a été marquée comme privée. Le message 101 est diffusé lorsque la vidéo demandée n'autorise pas la lecture dans les lecteurs intégrés.

Remarques sur la démonstration

À des fins de démonstration, nous avons souhaité inclure les champs de formulaire, les boutons et l'interface utilisateur d'affichage au format XHTML sous l'enveloppe ActionScript 3 intégrée. Pour que le fichier .f.f. ET la mise à jour XHTML soient effectuées en même temps, nous avons dû inclure deux lignes de code dans le fichier "youTubeLoader.js". Fichier JavaScript situé dans "deploy/_assets/js/" (Figure 3). Vous devrez supprimer les deux lignes suivantes [69, 79] lorsque vous intégrerez ce fichier à votre projet :

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

Le fichier de démonstration et les bibliothèques ActionScript qu'elles contiennent sont des logiciels sans frais. Vous pouvez les redistribuer et/ou les modifier conformément aux termes de la licence GNU Lesser General Public License. Ces fichiers sont distribués dans l'espoir qu'ils vous seront utiles, mais sans aucune garantie.

Conclusion

Cet article, demo et les fichiers sources devraient vous donner un bon aperçu d'une solution relativement simple et fiable permettant d'intégrer l'API YouTube et les lecteurs intégrés dans les environnements ActionScript 3 à l'aide de la bibliothèque de wrappers que nous avons développées pour nos propres projets. Comme j'ai commenté une grande partie du code, il sera dans l'idéal assez simple d'explorer et de réutiliser les bibliothèques. Il n'est pas exempt de limites, et il y a toujours une marge de progression possible, de refactorisation et d'amélioration. Si vous avez des commentaires à ce sujet, n'hésitez pas à me contacter.

Biographie de l'auteur


Matthew Richmond

Matthew Richmond cumule 14 ans d'expérience en conception, développement et architecture interactive. Lorsqu'il n'est pas en studio, il peut enseigner des techniques d'illustration/photographie numériques et un programme avancé d'ActionScript à la School of Visual Arts. Matthew est cofondateur et concepteur de choppingblock.com.