Cette page a été traduite par l'API Cloud Translation.

Wrapper ActionScript 3.0 pour le lecteur Chromeless

Cet article a été rédigé et envoyé par un développeur externe. L'équipe Outils et API de YouTube remercie Matthew Richmond pour son temps et son expertise.

Matthew Richmond, The Chopping Block, Inc.
Octobre 2008

Introduction
Ressources importantes
C'est parti !
Interagir avec le joueur
Opérations disponibles
Remarques sur la démonstration
Conclusion

Introduction

Dans cet article, je vais vous présenter brièvement un wrapper ActionScript 3.0 fiable pour le lecteur YouTube Chromeless. Le wrapper utilise 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 avec des budgets fixes qui ne permettent pas d'héberger des vidéos, ainsi que pour les projets à grande échelle pour les clients qui souhaitent bénéficier d'une expérience utilisateur personnalisée sans se distancier de leur audience YouYube.

Figure 1: Capture d'écran de l'enveloppe ActionScript 3.0

L'API Flash de YouTube et les lecteurs intégrés sont écrits et fonctionnent parfaitement avec ActionScript 2.0. Cependant, si votre projet est ActionScript 3.0, l'intégration parfaite devient un peu plus complexe. Bien qu'il soit facile de charger les lecteurs ActionScript 2.0 dans un fichier SWF ActionScript 3.0, vous ne pouvez pas communiquer directement ni transmettre d'appels fonctionnels vers le lecteur chargé. Le processus est plus complexe, car le fichier SWF issu des serveurs de YourTube charge une vidéo dans lui-même. Notre wrapper doit être pleinement conscient de ce fait et réagir en conséquence. Heureusement, le langage ActionScript contient deux solutions de contournement plausibles permettant de reconnecter ces éléments imbriqués et déconnectés : la classe LocalConnection ou la classe ExternalInterface. Cette démonstration sera consacrée à la deuxième méthode, car l'interface externe fonctionne parfaitement avec l'API JavaScript bien documentée et fonctionne donc parfaitement avec tout autre élément de la page XHTML.

Ressources importantes

Avant de commencer, voici une liste de ressources et de fichiers associés à votre disposition. De nombreux sujets abordés dans cet article sont décrits plus en détail dans les liens ci-dessous.

Approfondissement

Démo de l'enveloppe – Présentation

Figure 3: Fichier JavaScript

Figure 2: Fichiers de classe ActionScript

L'enveloppe ActionScript 3.0 se compose essentiellement de deux parties interconnectées, les fichiers de la 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 de YouTubeLoader. Votre page XHTML intègre le fichier Flash et l'enregistre avec les fonctions du fichier JavaScript youTubeLoader. Il est essentiel de comprendre qu'à partir de là, tout ce que fait YouTubeLoader dans le fichier Flash est contrôlé via les fonctions JavaScript.

Étant donné que toutes les fonctionnalités de Flash sont contrôlées via l'API JavaScript, vous ne pouvez PAS charger de contenu YouTube dans le lecteur "Test Movie" de Flash. Elle ne fonctionne que si elle est intégrée à une page XHTML et correctement connectée aux fonctions JavaScript de YouTube.

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

Créer un objet YouTubeLoader

Avant de créer une instance de l'objet YouTubeLoader dans votre projet Flash/Flex, vous devez 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 paramètre "classpath" de vos projets. Vous pouvez ensuite importer les fichiers du package:

import choppingblock.video.*;

Cela permet à votre fichier ActionScript d'accéder aux classes "YouTubeLoader.as" et "YouTubeLoaderEvent.as". Vous pouvez maintenant créer une instance de la classe YouTubeLoader et des é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
  };
};

Maintenant que le fichier JavaScript est en place et connecté correctement, youTubePlayerLoadedHandler doit être appelé avec succès et nous pouvons commencer à effectuer des requêtes.

Intégrer le fichier swf et connecter le code JavaScript de YouTube

Vous ne pourrez pas charger de contenu depuis YouTube tant que votre fichier swf n'a pas été intégré dans un fichier XHTML et connecté au code JavaScript de YouTube. Nous vous recommandons d'utiliser la méthode SWFObject pour intégrer tous les lecteurs accessibles à l'aide de l'API JavaScript. Cela vous permet de détecter la version de Flash Player de l'utilisateur final (l'API JavaScript nécessite Flash Player 8 ou une version ultérieure) et de supprimer la case à cocher "Activer cette commande" lorsque vous utilisez Internet Explorer.

Dans la partie <head> de votre fichier XHTML, connectez les fichiers swfobject 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 de SWFObject pour intégrer votre fichier SWF ActionScript 3.0 avec l'API JavaScript activée, puis transmettre une référence à ce fichier à l'API JavaScript 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>

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

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

swfobject.embedSWF charge le lecteur depuis YouTube et l'intègre à votre page.

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

swfUrlStr : URL du fichier SWF. Notez que nous avons ajouté les paramètres enablejsapi et playerapiid à l'URL YouTube SWF normale pour activer les appels de l'API JavaScript.
replaceElemIdStr : ID DIV HTML à remplacer par le contenu intégré. Dans l'exemple ci-dessus, il s'agit de ytapiplayer.
widthStr : largeur du lecteur.
heightStr : hauteur du lecteur.
swfVersionStr : version minimale requise pour permettre à l'utilisateur de 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 SWF d'installation express. Cet argument n'est pas utilisé dans cet exemple.
flashVarsObj (facultatif) : spécifie les éléments FlashVar dans des paires nom:valeur. Cet argument n'est pas utilisé dans cet exemple.
parObj (facultatif) : paramètres de l'objet intégré. Dans le cas présent, nous avons défini allowScriptAccess.
AttObj (facultatif) : attributs de l'objet intégré. Dans le cas présent, 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 que l'API JavaScript doit utiliser. Vous devez utiliser le même ID de l'objet d'intégration que celui que vous avez fourni 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é. Nous pouvons désormais effectuer une requête vidéo et interagir avec l'objet YouTubeLoader.

Interagir avec le joueur

Cette méthode de création d'un wrapper ActionScript 3.0 pour le lecteur Chromeless repose sur la classe ExternalInterface d'ActionScript. Il est désormais possible d'utiliser n'importe quelle opération de l'API Player YouTube JavaScript pour contrôler le lecteur chargé. Si vous regardez dans le fichier JavaScript "youTubeLoader.js" situé dans deploy/_assets/js/ (Figure 3), vous constaterez qu'il contient la plupart des fonctions disponibles. Chaque fonction de l'opération vérifie d'abord la fonction checkObj pour vérifier 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 Chromeless est d'offrir une interaction transparente 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 dans l'objet YouTubeLoader dans Flash/Flex. Voici ce que vous trouverez dans le fichier du cours:

// ------------------------------------
// 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, pour lire la vidéo lorsqu'un internaute clique sur un bouton, vous devez ajouter un écouteur d'événement MouseEvent.CLICK à votre bouton. Exemple :

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

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 éventuellement demander une vidéo en appelant directement la fonction JavaScript correspondante. Exemple :

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

Émettre des appels supplémentaires

Les appels supplémentaires fonctionnent exactement comme les demandes de vidéos. À partir d'ActionScript 3, vous pouvez simplement appeler des méthodes à l'aide de la référence du lecteur. La liste complète des méthodes disponibles est fournie 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);

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, puis stocker une référence à l'objet YouTubePlayer que vous souhaitez contrôler. Pour ce faire, vous pouvez appeler:

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: Charge la vidéo, mais ne la lit pas automatiquement en fonction de l'ID spécifié.
player.clearVideo():void: Efface la vidéo en file d'attente/chargée.
player.setSize(w:Number, h:Number):void: Définit la taille de l'instance YouTubePlayer.
player.play():void: Lire la vidéo en file d'attente/chargée
player.pause():void: Interrompt la lecture de la vidéo en file d'attente/chargée.
player.stop():void: Arrête la vidéo actuellement en file d'attente/chargée.
player.seekTo(seconds:Number):void: Recherche un moment précis dans la vidéo en file d'attente/chargée.
player.getPlayerState():String: Renvoie l'état actuel de la vidéo actuellement en file d'attente/chargée.
player.getBytesLoaded():Number: Renvoie la valeur du nombre d'octets chargés de la vidéo actuellement en file d'attente/chargée.
player.getBytesTotal():Number: Renvoie la valeur du nombre total d'octets chargés de la vidéo actuellement en file d'attente/chargée.
player.getCurrentTime():Number: Renvoie la position actuelle de la vidéo en file d'attente/chargée.
player.getDuration():Number: Renvoie la durée actuelle de la vidéo actuellement en file d'attente/chargée.
player.getStartBytes():Number: Renvoie les octets de début 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 en file d'attente/chargée.
player.mute():void: Enregistre le volume actuel et modifie le volume de la vidéo en file d'attente/chargée à 0.
player.unmute():void: Renvoie le volume de la vidéo en file d'attente/chargée à la dernière valeur stockée lorsqu'elle est coupée.
player.getEmbedCode():String: Renvoie le code d'intégration YouTube actuel de la vidéo actuellement en file d'attente/chargée.
player.getVideoUrl():String: Renvoie l'URL actuelle de la vidéo YouTube actuellement en file d'attente/chargée.

Événements

YouTubeLoaderEvent.LOADED: Déclenchement une fois le chargement du lecteur Chromeless terminé et prêt à accepter les appels d'opération.
YouTubeLoaderEvent.STATE_CHANGE: Déclenché chaque fois que l'état du joueur change. La classe YouTubeLoader traduit les numéros d'API JavaScript vers les valeurs de chaîne associées, la classe YouTubeLoaderEvent stocke l'événement en cours dans une variable appelée state. Les valeurs possibles sont "unstarted", "ended", "playing", "paused", "buffering", "video queuesd". Lors du premier chargement du fichier SWF, un événement non démarré est diffusé. Lorsque la vidéo est en file d'attente et prête à être lue, elle diffuse un événement en file d'attente.
YouTubeLoaderEvent.IO_ERROR: Déclenché en cas d'erreur 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 marquée comme privée. Le code 101 est diffusé lorsque la vidéo demandée n'autorise pas la lecture dans les lecteurs intégrés.

Notes sur la démonstration

À des fins de démonstration, nous souhaitons inclure les champs de formulaire XHTML, les boutons et l'interface utilisateur d'affichage sous l'enveloppe ActionScript 3 intégrée. Pour que le fichier SWF ET le contenu XHTML soient mis à jour en même temps, nous avons dû inclure deux lignes de code dans le fichier JavaScript "youTubeLoader.js" situé dans "deploy/_assets/js/" (Figure 3). Nous vous conseillons de supprimer les deux lignes suivantes [69, 79] lorsque vous intégrez 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 incluses sont des logiciels sans frais: vous pouvez les redistribuer et/ou les modifier selon les termes de la licence publique générale GNU. Ces fichiers seront distribués dans l'espoir qu'ils vous seront utiles, mais sans garantie.

Conclusion

Cet article, demo et source files, vous offre un aperçu complet d'une solution relativement simple et fiable pour intégrer l'API YouTube et les lecteurs intégrés dans des environnements ActionScript 3 à l'aide de la bibliothèque wrapper que nous avons développée pour nos propres projets. Comme j'ai beaucoup commenté le code, l'exploration et la réutilisation des bibliothèques sont idéales. Ce n'est pas sans limites, et il est toujours possible de s'améliorer. N'hésitez pas à me contacter si vous avez des questions à ce sujet.

Biographie de l'auteur

Matthew Richmond possède 14 ans d'expérience en conception, développement et architecture interactifs. Lorsqu'il n'est pas à l'atelier, il se rend à l'école des arts visuels pour enseigner les techniques d'illustration/photographie numériques et d'ActionScript avancé. Matthew est partenaire et concepteur fondateur chez choppingblock.com.