Youtube Iframe API 常用功能

Youtube Iframe API 常用功能

影片愈來愈重要的這時代,前端會遇到嵌Youtube的相關需求

最近做的幾個案子,頁面上很常會要嵌入Youtube,比方一些形象的宣傳影片、一些看起來很感人但其實是廣告的影片(咦?)。

大部份遇到這需求,都是直接用Youtube本來就有提供的iframe來解決,但有些時候會需要用到API,像是當企劃說:「我想要滑到出現影片這塊時,影片就自動播放。」、「當影片播放時,幫我埋個GA事件。」…etc。

這時如果只會基本的iframe,是不夠的。而且為了節省流量,公司又沒有串流功能時,影片很少很少會放自己的主機,大部份都是放Youtube上,這些情況就需要用到Youtube提供的iframe API。

本篇要筆記的就是Youtube iframe API的一些常用功能,比方嵌入、自動播放、監聽影片狀態、做一個自己的控制器等。

放個廣告賺點養主機的$$,謝謝

再配合之前寫過的二篇,就可以滿足上面企劃提的例子了:

滑到影片出現時自動播放,可用IntersectionObserver配合。

發送GA事件,先了解GA事件要傳送哪三個值


基本使用:嵌入影片+自動播放

Youtube iframe API最基本的使用,就是嵌入影片了。API中嵌入影片有二種方式:

  1. html中放一個div,由JS去嵌入
  2. html裡直接放個iframe

這兩種方式不論哪一種,都可以直接在嵌入完成後,自動播放影片。

要注意的是,瀏覽器的政策是不能干擾使用者的瀏覽,所以如果想要自動播放影片,影片就必須要是靜音,這樣自動播放時,使用者也不會因為突然出現的聲音而被嚇到。

以下的html,UI用了Bootstrap,因此會看見出現Bootstrap的class name。

另外本筆記所有Demo,會統一整理在一個頁面上,網址連結附在最後一段。


1 html中放一個div,由JS去嵌入

程式碼如下:

放個廣告賺點養主機的$$,謝謝

可以看到,html就是放一個 <div id="player"></div>,再由JavaScript呼API去指定player這個id的div去嵌入影片。

因為Bootstrap的CSS會讓iframe有響應式,因此iframe的寬高就寫預設值的640*390就行。

videoId就是要嵌入的Youtube影片id。影片id可以從網址上找到,我們一般看到的Youtube網址是這樣:

https://www.youtube.com/watch?v=KuhIY-AUG6c

影片id就是 v= 後面的那一串,像這個例子就是 KuhIY-AUG6c。順帶一提,這部影片的泱泱好可愛~

API中跟一般嵌入Youtube最大的不同,就是有一個callback,可以在影片嵌入完就緒時,執行一個function,就是程式碼中的這段:

events: {
  'onReady': onPlayerReady
}

當影片ready的時候,就執行 onPlayerReady 這個function。

onPlayerReady寫的內容是這樣:

function onPlayerReady(e) {
  e.target.mute().playVideo();
}

function會自動帶一個參數,這邊用小寫e,實際上你想叫什麼都行,也可以寫成event,或是你家小狗的英文名字,一般我們會用event或是偷懶用小寫e。

e.target就是這個Youtube本身,mute()是讓它靜音,playVideo()就是播放影片。

2 html裡直接放個iframe

直接放個iframe的方式,跟我們一般複製貼上Youtube給的嵌入碼很像,但還是有小地方不一樣:

在iframe src的部份,最後要帶一個參數:enablejsapi=1

origin=嵌入youtube的網域" 這個則是選填,如果有填,那嵌入Youtube的網域,就要是你寫在origin後面的那個網域。比方如果這邊寫了origin=https://letswrite.tw,那這一段程式碼就只能在本站中執行Youtube iframe API,如果不是在本站,就會報錯。

JavaScript的部份跟前一種方式是一樣的,但因為寬高可以寫在iframe上,因此呼API這段可以不必寫寬高。

html上,iframe的id還是要有,API在呼的時候不管是1、2哪種方式,都要寫上id。


自製Youtube播放器

這段來筆記自製播放器的部份,最後會完成的樣子如下:

自製播放器Demo
自製播放器Demo

可以看到,泱泱好可愛~~啊不是,是這邊的Demo上總共接了API提供的幾項功能:

  • 播放、暫停、停止
  • 後退10秒、前進10秒(秒數可以自己設定)
  • 播放速度,捲軸的值是:0.25 / 0.5 / 0.75 / 1 / 1.25 / 1.5 / 1.75 / 2
  • 音量:0 – 100
  • 是否靜音

這些API文件上都有寫,不過散在各段中,覺得未來總會有遇到以上需求的時候,這邊就把這幾項功能整理在一起,程式碼如下:

每個功能按鈕都給一個id,這個按鈕就監聽click事件,捲軸的話就是監聽input事件,聽到事件後的callback,都是寫在 onPlayerReady 的function中。

需要說明的是後退、前進幾秒這個,這邊Youtube並沒有直接給一個往前/往後的功能,但有給了兩個API:抓目前播放到幾秒、讓影片直接跳到幾秒。

因此所謂的後退、前進功能,其實就是按了按鈕後,先抓目前影片播放的秒數,接著讓影片跳到目前秒數 +10 或 -10 的地方。加多少或減多少可以自行修改。

其它的功能程式碼裡面都有寫上註解了,可以直接看註解說明。


監聽Youtube播放狀態

Youtube的影片我們可以用API來知道目前是:準備好的、初次載入的、播放的、暫停的、播完的、緩衝中,這六種狀態。

可以看到,在原本 'onReady': onPlayerReady 下面多加了一個callback:

'onStateChange': onPlayerStateChange

onPlayerStateChange這個function一樣會帶上一個參數,這邊取名為小寫e。小寫e一樣指的是這個Youtube這個影片本身,但會另外多帶另一個data出來,console.log的話會看到以下:

onPlayerStateChange的console
onPlayerStateChange的console

這個data就是影片的狀態碼,總共有 -1、0、1、2、3、5 這六個數字,對應的狀態如下:

  • -1:unstarted 未啟動,初次載入
  • 0:ended 結束
  • 1:playing 播放中
  • 2:paused 暫停
  • 3:buffering 緩衝中
  • 5:video cued 準備好可以播放了

當頁面嵌入的Youtube,這個影片準備就緒時,用 e.target.getPlayerState() 會得到 5 這個狀態。

當你按下播放,這時影片會開始載入,狀態會回傳 -1,這段就是當我們按下播放,會看到Youtube一開始出現的轉圈圈那段。

當Youtube開始播影片,狀態碼是1

按下暫停是2

如果網路太慢需要緩衝又在那轉圈圈時是3

影片整個播完了是0

我們可以針對不同的狀態,發送不同的GA事件,就可以大概統計有多少人點了影片播放,又有多少人有看完。


Demo、原始碼

Demo跟原始碼的部份都有整理在Github上。

Demo:https://letswritetw.github.io/letswrite-youtube-iframe-api/

原始碼:https://github.com/letswritetw/letswrite-youtube-iframe-api

本篇參考資源主是Youtube IFrame Player API的文件:

YouTube Player API Reference for iframe Embeds

Summary
Youtube Iframe API 常用功能
Article Name
Youtube Iframe API 常用功能
Description
本篇大綱:影片愈來愈重要的這時代,前端會遇到嵌Youtube的相關需求。基本使用:嵌入影片+自動播放。1 html中放一個div,由JS去嵌入。2 html裡直接放個iframe。自製Youtube播放器。監聽Youtube播放狀態。Demo、原始碼。
Augustus
Let's Write
Let's Write
Publisher Logo

留言