ActionScript 3.0 Wrapper for Chromeless Player

این مقاله توسط یک توسعه دهنده خارجی نوشته و ارسال شده است. تیم YouTube APIs and Tools از متیو ریچموند برای وقت و تخصصش تشکر می کند.


متیو ریچموند، The Chopping Block، Inc.
اکتبر 2008

معرفی

در این مقاله، من یک ActionScript 3.0 Wrapper قابل اعتماد برای Chromeless YouTube Player را ارائه و به طور خلاصه شرح خواهم داد. بسته بندی از کلاس ExternalInterface ActionScript و JavaScript API YouTube استفاده می کند.

ابزارهای YouTube Player Google و Chromeless Player به طراحان/توسعه دهندگان این امکان را داده اند تا به سرعت و به راحتی قدرت YouTube را در پروژه های آنلاین خود ادغام کنند. این رویکرد برای پروژه‌های کوچک با بودجه ثابت که اجازه میزبانی ویدیو را نمی‌دهند، و همچنین پروژه‌های مقیاس بزرگ برای مشتریانی که می‌خواهند یک تجربه کاربر نهایی سفارشی بدون فاصله گرفتن از مخاطبان یویوبی خود داشته باشند، ایده‌آل است.

اسکرین شات ActionScript 3.0 Wrapper
شکل 1: اسکرین شات ActionScript 3.0 Wrapper

Flash API یوتیوب و پخش‌کننده‌های تعبیه‌شده در آن نوشته شده‌اند و با ActionScript 2.0 به خوبی کار می‌کنند. اگر پروژه شما ActionScript 3.0 باشد، ادغام یکپارچه کمی پیچیده تر می شود. در حالی که بارگیری پخش کننده های ActionScript 2.0 در یک ActionScript 3.0 swf آسان است، شما نمی توانید مستقیماً ارتباط برقرار کنید یا هیچ تماس کاربردی را به پخش کننده بارگذاری شده ارسال کنید. این پیچیده تر است زیرا فایل swf که از سرورهای YourTube می آید در حال بارگذاری یک ویدیو در خودش است. لفاف ما باید کاملاً از این واقعیت آگاه باشد و مطابق با آن واکنش نشان دهد. خوشبختانه زبان ActionScript شامل دو راه حل قابل قبول برای اتصال مجدد این قطعات تودرتو و در عین حال جدا شده است، کلاس LocalConnection یا کلاس ExternalInterface. این نسخه ی نمایشی بر روی دومی تمرکز خواهد کرد زیرا ExternalInterface یکپارچه با API جاوا اسکریپت مستند کار می کند و بنابراین با هر چیز دیگری در صفحه XHTML به خوبی بازی می کند.

منابع مهم

قبل از شروع، در اینجا لیستی از منابع و فایل های مرتبط در دسترس شما است. بسیاری از موضوعات مورد بحث در این مقاله در پیوندهای زیر با جزئیات بیشتر توضیح داده شده است.

حفاری در

بررسی اجمالی نسخه ی نمایشی Wrapper

فایل های کلاس اکشن اسکریپت
شکل 3: فایل جاوا اسکریپت
فایل های کلاس اکشن اسکریپت
شکل 2: فایل های کلاس ActionScript

ActionScript 3.0 Wrapper اساساً از دو بخش به هم پیوسته تشکیل شده است، فایل‌های کلاس ActionScript 3.0 واقع در src/choppingblock/video/ (شکل 2) و فایل جاوا اسکریپت 'youTubeLoader.js' واقع در deploy/_assets/js/ (شکل 3) . فایل منبع Flash/Flex شما نمونه ای از کلاس YouTubeLoader ActionScript ایجاد می کند. صفحه XHTML شما فایل فلش را جاسازی می کند و آن را با توابع موجود در فایل جاوا اسکریپت youTubeLoader ثبت می کند. درک این نکته ضروری است که از اینجا، هر کاری که YouTubeLoader در فایل فلش انجام می دهد، از طریق توابع جاوا اسکریپت کنترل می شود.

از آنجایی که تمام عملکردهای داخل Flash از طریق API جاوا اسکریپت کنترل می شود، نمی توانید محتوای YouTube را در پخش کننده «تست فیلم» Flash بارگیری کنید. فقط زمانی کار می کند که در یک صفحه XHTML تعبیه شده باشد و به درستی به توابع جاوا اسکریپت youTubeLoader متصل شود.

توجه : برای آزمایش هر یک از این تماس‌ها، باید فایل خود را روی یک وب سرور اجرا کنید یا تنظیمات امنیتی Flash Player خود را تغییر دهید، زیرا Flash player تماس‌های بین فایل‌های محلی و اینترنت را محدود می‌کند.

ایجاد یک شی YouTubeLoader

قبل از اینکه بتوانید نمونه ای از آبجکت YouTubeLoader را در پروژه Flash/Flex خود ایجاد کنید، ابتدا باید مطمئن شوید که بسته (پوشه) فایل های مورد نیاز در همان دایرکتوری پروژه شما است (شکل 2) یا با پروژه های شما Classpath تعریف شده است. . سپس می توانید فایل های بسته را وارد کنید:

import choppingblock.video.*;

این اجازه می دهد تا فایل ActionScript شما به کلاس های "YouTubeLoader.as" و "YouTubeLoaderEvent.as" دسترسی داشته باشد. اکنون می‌توانید نمونه‌ای از کلاس YouTubeLoader و شنونده‌های رویداد لازم ایجاد کنید:

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

اکنون، اگر فایل جاوا اسکریپت در جای خود قرار داشته باشد و به درستی وصل شده باشد، باید youTubePlayerLoadedHandler با موفقیت فراخوانی شود و ما آماده شروع درخواست هستیم.

جاسازی swf و اتصال جاوا اسکریپت youTubeLoader

تا زمانی که فایل swf شما در یک فایل XHTML جاسازی نشده و به جاوا اسکریپت youTubeLoader متصل نشود، نمی‌توانید با موفقیت محتوا را از YouTube بارگیری کنید. توصیه می کنیم از SWFObject برای جاسازی هر پخش کننده ای که با استفاده از JavaScript API به آنها دسترسی پیدا می کند، استفاده کنید. این به شما امکان می‌دهد نسخه فلش پلیر کاربر نهایی را شناسایی کنید (API جاوا اسکریپت به Flash Player 8 یا بالاتر نیاز دارد)، و همچنین هنگام استفاده از اینترنت اکسپلورر برای مشاهده پخش‌کننده، از جعبه «برای فعال کردن این کنترل کلیک کنید» خلاص می‌شوید.

در بخش <head> فایل XHTML خود، فایل‌های swfobject و youTubeLoader را به هم وصل می‌کنید:

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

نمونه ای از استفاده از SWFObject برای جاسازی ActionScript 3.0 swf با فعال کردن API جاوا اسکریپت را در زیر ببینید و سپس یک مرجع به swf خود را به API جاوا اسکریپت 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>

پارامتر allowScriptAccess در کد مورد نیاز است تا به پخش کننده SWF اجازه دهد تا توابع را در صفحه HTML حاوی آن فراخوانی کند، زیرا پخش کننده Chromeless در دامنه متفاوتی از صفحه XHTML میزبانی می شود.

تنها خصیصه‌ای که ما به آن منتقل می‌کنیم، شناسه شی جاسازی است - در این مورد، youtubewrapper. این شناسه همان چیزی است که فایل youTubeLoader.js برای دریافت ارجاع به پخش کننده با استفاده از getElementById() استفاده می کند.

swfobject.embedSWF پخش کننده را از YouTube بارگیری می کند و آن را در صفحه شما جاسازی می کند.

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

  • swfUrlStr - این نشانی اینترنتی SWF است. توجه داشته باشید که ما پارامترهای enablejsapi و playerapiid را به URL معمولی YouTube SWF اضافه کرده‌ایم تا تماس‌های JavaScript API را فعال کنیم.
  • replaceElemIdStr - این شناسه HTML DIV برای جایگزینی با محتوای جاسازی شده است. در مثال بالا، ytapiplayer است.
  • widthStr - عرض پخش کننده.
  • heightStr - ارتفاع بازیکن.
  • swfVersionStr - حداقل نسخه مورد نیاز برای مشاهده محتوا توسط کاربر. در این مورد، نسخه 8 یا بالاتر مورد نیاز است. اگر کاربر 8 یا بالاتر نداشته باشد، خط متن پیش فرض را در HTML DIV می بیند.
  • xiSwfUrlStr - (اختیاری) نشانی اینترنتی SWF نصب سریع شما را مشخص می کند. در این مثال استفاده نشده است.
  • flashVarsObj - (اختیاری) FlashVars شما را در جفت های name:value مشخص می کند. در این مثال استفاده نشده است.
  • parObj - (اختیاری) پارامترهای شی جاسازی شده. در این مورد، ما allowScriptAccess تنظیم کرده‌ایم.
  • AttObj - (اختیاری) ویژگی های شی جاسازی شده. در این مورد، شناسه را روی myytplayer قرار داده ایم.

برای توضیح بیشتر به مستندات SWFObject مراجعه کنید.

SWFID ≡ یک ارجاع به شناسه شی جاسازی شده را برای استفاده از JavaScript API ذخیره می کند. شما باید از همان id شی embed استفاده کنید که به swf داده اید.

SWFID ≡ "youtubewrapper"

در این مرحله باید بتوانید پروژه خود را با موفقیت آزمایش کنید. شی YouTubeLoader باید Chromeless Player را بارگیری کند و کنترل کننده رویداد YouTubeLoaderEvent.LOADED باید با موفقیت فراخوانی شود. اکنون ما آماده ایم تا یک درخواست ویدیویی داشته باشیم و با شی YouTubeLoader تعامل کنیم.

تعامل با بازیکن

از آنجایی که این رویکرد برای ایجاد ActionScript 3.0 Wrapper برای Chromeless Player از کلاس ExternalInterface ActionScript استفاده می کند، اکنون می توانیم از هر یک از عملیات در YouTube JavaScript Player API برای کنترل پخش کننده بارگذاری شده خود استفاده کنیم. اگر به فایل جاوا اسکریپت 'youTubeLoader.js' واقع در deploy/_assets/js/ (شکل 3) نگاه کنید، خواهید دید که حاوی اکثر توابع موجود است. هر تابع عملیات ابتدا تابع checkObj را بررسی می کند تا بررسی کند که متغیر SWFID قبل از اجرا به درستی تنظیم شده است.

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

با توجه به اینکه هدف نهایی ActionScript 3.0 Wrapper ما برای Chromeless Player ارائه تعامل یکپارچه با YouTube API از داخل یک پروژه ActionScript 3.0 Flash/Flex است، ما دقیقاً همان روش های عمومی را به کلاس "YouTubeLoader.as" اضافه کرده ایم. فایل واقع در src/choppingblock/video/ (شکل 2). این بدان معناست که می‌توانید دقیقاً همان عملیات را مستقیماً به شی YouTubeLoader در Flash/Flex فراخوانی کنید. اگر به فایل کلاس نگاه کنید، خواهید دید:

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

متدهای ActionScript از کلاس ExternalInterface برای فراخوانی تابع مناسب در API جاوا اسکریپت استفاده می کنند.

درخواست ویدیو

اکنون می توانید با فراخوانی توابع با استفاده از مرجع پخش کننده، یک ویدیو از داخل فایل ActionScript 3.0 خود درخواست کنید. برای مثال، اگر می‌خواهید وقتی کاربر روی دکمه‌ای کلیک می‌کند، ویدیو را پخش کنید، یک شنونده رویداد MouseEvent.CLICK را به دکمه خود اضافه می‌کنید. مثل این:

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

و یک متد کنترل کننده رویداد برای رسیدگی به درخواست ایجاد کنید. مثل این:

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

خارج از فایل Flash/Flex خود، می توانید به صورت اختیاری با فراخوانی مستقیم تابع جاوا اسکریپت مربوطه، یک ویدیو درخواست کنید. مثل این:

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

صدور تماس های اضافی

تماس‌های اضافی دقیقاً مانند درخواست ویدیو عمل می‌کنند. از داخل اکشن اسکریپت 3 می توانید به سادگی روش ها را با استفاده از مرجع پخش فراخوانی کنید. فهرست کاملی از روش های موجود در زیر ارائه شده است.

اشتراک در رویدادها

با افزودن شنونده رویداد به مرجع پخش کننده، در رویدادها مشترک شوید. برای مثال، برای اطلاع از تغییر وضعیت بازیکن، یک شنونده رویداد برای YouTubeLoaderEvent.STATE_CHANGE اضافه کنید. مثل این:

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

و یک متد کنترل کننده رویداد برای رسیدگی به درخواست ایجاد کنید. مثل این:


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

عملیات در دسترس

برای فراخوانی متدهای YouTubePlayer API، ابتدا باید یک نمونه از کلاس YouTubePlayer در فایل ActionScript خود ایجاد کنید و یک مرجع به شی YouTubePlayer که می‌خواهید کنترل کنید ذخیره کنید. این کار را می توان با تماس تلفنی انجام داد:

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

روش های عمومی

player.loadVideoById(id:String, startSeconds:Number = 0):void
ویدیو را بر اساس شناسه مشخص شده بارگیری و پخش می کند.
player.cueNewVideo(id:String, startSeconds:Number = 0):void
بارگیری می شود اما به طور خودکار ویدیو را بر اساس شناسه مشخص شده پخش نمی کند.
player.clearVideo():void
ویدیوی نمایش داده شده/بارگذاری شده فعلی را پاک می کند.
player.setSize(w:Number, h:Number):void
اندازه نمونه YouTubePlayer را تنظیم می کند.
player.play():void
ویدیوی نمایش داده شده/بارگذاری شده فعلی را پخش می کند.
player.pause():void
ویدیوی نشان‌داده‌شده/بارگذاری‌شده فعلی را متوقف می‌کند.
player.stop():void
ویدیوی نمایش داده شده/بارگذاری شده فعلی را متوقف می کند.
player.seekTo(seconds:Number):void
به دنبال زمان مشخصی در ویدیوی نمایش داده شده/بارگذاری شده فعلی است.
player.getPlayerState():String
وضعیت فعلی ویدیوی نشان‌داده‌شده/بارگذاری‌شده فعلی را برمی‌گرداند.
player.getBytesLoaded():Number
مقدار بایت های فعلی بارگیری شده از ویدیوی نشان داده شده/بارگذاری شده فعلی را برمی گرداند.
player.getBytesTotal():Number
مقدار کل بایت های بارگیری شده از ویدیوی نشان داده شده/بارگذاری شده فعلی را برمی گرداند.
player.getCurrentTime():Number
موقعیت فعلی را در زمان ویدیوی نمایش داده شده/بارگذاری شده کنونی برمی گرداند.
player.getDuration():Number
مدت زمان فعلی ویدیوی نمایش داده شده/بارگذاری شده فعلی را برمی‌گرداند.
player.getStartBytes():Number
بایت های شروع ویدیوی نمایش داده شده/بارگذاری شده فعلی را برمی گرداند.
player.setVolume(newVolume:Number):void
حجم ویدیوی نمایش داده شده/بارگذاری شده فعلی را تنظیم می کند.
player.getVolume():Number
حجم فعلی ویدیوی نشان‌داده‌شده/بارگذاری‌شده فعلی را برمی‌گرداند.
player.mute():void
حجم فعلی را ذخیره می‌کند و صدای ویدیوی بارگذاری‌شده/در حال حاضر را به 0 تغییر می‌دهد.
player.unmute():void
در صورت بی‌صدا کردن، حجم ویدیوی نشان‌داده‌شده/بارگذاری‌شده فعلی را به آخرین مقدار ذخیره‌شده برمی‌گرداند.
player.getEmbedCode():String
کد فعلی جاسازی YouTube ویدیوی نشان‌داده‌شده/بارگذاری‌شده فعلی را برمی‌گرداند.
player.getVideoUrl():String
آدرس اینترنتی ویدیوی YouTube فعلی ویدیوی نشان‌داده‌شده/بارگذاری‌شده فعلی را برمی‌گرداند.

مناسبت ها

YouTubeLoaderEvent.LOADED
هنگامی که Chromeless Player بارگیری با موفقیت کامل شد و آماده پذیرش تماس‌های عملیاتی شد، فعال می‌شود.
YouTubeLoaderEvent.STATE_CHANGE
هر زمان که وضعیت بازیکن تغییر کند اخراج می شود. کلاس YouTubeLoader اعداد API جاوا اسکریپت را به مقادیر رشته مرتبط آنها ترجمه می کند، کلاس YouTubeLoaderEvent رویداد فعلی را در متغیری به نام state ذخیره می کند. مقادیر احتمالی شروع نشده، پایان یافته، پخش، متوقف شده، بافر کردن، نمایش ویدئو هستند. هنگامی که SWF برای اولین بار بارگیری می شود، یک رویداد شروع نشده را پخش می کند. وقتی ویدیو آماده پخش شد، یک رویداد ویدیویی نمایش داده می‌شود.
YouTubeLoaderEvent.IO_ERROR
زمانی که خطایی در پخش کننده رخ می دهد شلیک می شود. دو کد خطا ممکن است: 100 زمانی پخش می شود که ویدیوی درخواستی پیدا نشود. این زمانی اتفاق می افتد که یک ویدیو (به هر دلیلی) حذف شده باشد یا به عنوان خصوصی علامت گذاری شده باشد. 101 زمانی پخش می شود که ویدیوی درخواستی اجازه پخش در پخش کننده های تعبیه شده را نمی دهد.

یادداشت ها در مورد نسخه ی نمایشی

برای اهداف نمایشی، ما می‌خواستیم فیلدهای فرم XHTML، دکمه‌ها و رابط کاربری نمایش را در زیر ActionScript 3 Wrapper تعبیه‌شده اضافه کنیم. برای اینکه فایل swf و به‌روزرسانی XHTML را همزمان داشته باشیم، باید دو خط کد را در فایل جاوا اسکریپت 'youTubeLoader.js' واقع در 'deploy/_assets/js/' قرار دهیم (شکل 3). هنگامی که این فایل را در پروژه خود ادغام می کنید، می خواهید دو خط زیر [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)
}

فایل آزمایشی و کتابخانه‌های ActionScript شامل نرم‌افزار رایگان هستند: می‌توانید آن را مجدداً توزیع کنید و/یا آن را تحت شرایط مجوز عمومی عمومی کوچک گنو تغییر دهید. این فایل ها به امید مفید بودن اما بدون ضمانت توزیع می شوند.

نتیجه

این مقاله، نسخه آزمایشی و فایل‌های منبع باید یک نمای کلی از یک راه حل نسبتا ساده و قابل اعتماد برای ادغام API YouTube و پخش‌کننده‌های جاسازی شده در محیط‌های ActionScript 3 با استفاده از کتابخانه پوششی که برای پروژه‌های خود ایجاد کرده‌ایم، به شما ارائه دهد. از آنجایی که من بسیاری از کدها را توضیح داده‌ام، کاوش و تغییر کاربری کتابخانه‌ها در حالت ایده‌آل نسبتاً ساده خواهد بود. بدون محدودیت نیست و همیشه جا برای بهبود، فاکتورگیری مجدد و بهبود وجود دارد. اگر در این مورد نظری دارید، با من تماس بگیرید.

بیوگرافی نویسنده


متیو ریچموند

متیو ریچموند دارای 14 سال تجربه طراحی تعاملی، توسعه و معماری است. وقتی در استودیو نیست، می‌توان او را در حال تدریس تکنیک‌های تصویرسازی/عکاسی دیجیتال و اکشن اسکریپت پیشرفته در دانشکده هنرهای تجسمی یافت. متیو شریک و طراح choppingblock.com است.