init #

初始化Web component

基本使用範例 #

以下範例的參數為必填

其餘的參數皆為選填

可依照專案需求自行設定

window.$microMediaUploader.init({
  apiKey: 'ad0sf3=2n&42cx8/y013',
  apiEndpoint: 'http://localhost:3000',
  s3BucketName: 'my-bucket',
  s3BucketRegion: 'ap-southeast-1',
})

apiKey #

Required/String

API Gateway API Key

apiEndpoint #

Required/String

API Gateway endpoint

s3BucketName #

Required/String

儲存影片的S3 bucket名稱

s3BucketRegion #

Required/String

儲存影片的S3 bucket region

autoTriggerMediaConvertJob #

Optional/Boolean

是否在streaming原始檔上傳成功後

自動觸發MediaConvertJob

預設為false

autoPollMediaConvertJob #

Optional/Boolean

是否在media convert job建立之後自動poll job狀態(每5秒poll一次)

並在每次poll後執行eventOnPollMediaConvertJobData event hook

讓您可以透過此event hook取得轉檔job資訊

eventOnDetectUnfinishedUploadData #

Optional/Function

偵測到有未上傳完成的檔案資料的event hook

function可用參數 #

• unfinishedUploadData: Object, 未完成上傳的檔案(詳見Data Model - unfinishedUploadData)

eventOnChooseFileDetectUnfinishedUploadData #

Optional/Function

User選擇完檔案後

偵測到有未上傳完成的檔案資料的最後確認的event hook

您可使用這個event hook提示User目前有未上傳的檔案並提供檔名等資訊

透過confirm或其他popup讓User自行決定是否繼續

若在這個callback function中拋出Error

Web component catch到error之後將不會新的檔案來替代原本未上傳的檔案

透過這的方式就可保留原本未上傳的檔案

function可用參數 #

• unfinishedUploadData: Object, 未完成上傳的檔案(詳見Data Model - unfinishedUploadData)

範例 #

window.uploader.init({
  eventOnChooseFileDetectUnfinishedUploadData: async (unfinishedUploadData) => {
    this.unfinishedUploadData = unfinishedUploadData
    const filename = unfinishedUploadData.filename
    const result = confirm(`偵測到未上傳的檔案, ${filename}`)

    // 拋出錯誤web component將不會取代未上傳的檔案
    if(!result) {
      throw new Error('reject file')
    }
  },
})

eventOnFileChange #

Optional/Function

檔案更新event hook

可用來跳出popup或顯示讓User知道目前選擇的檔案、類型、大小等資訊

您更可以自行加入檔案限制規則

若不合規則只要拋出Error

Web component只要catch到error將不會載入User選取的檔案

function可用參數 #

• file: File/null, js的File介面, 或是null(User移除檔案的時候)

範例 #

window.$microMediaUploader.init({
  eventOnFileChange: (file) => {
    const sizeMb = !file ? 0 : Math.round(file.size/1024/1024)
    const maxSizeMb = 50
    if(sizeMb > maxSizeMb) {
      alert(`超過檔案限制大小${maxSizeMb}MB`)
      throw new Error('out of limit') // 拋出error讓web component不要載入這個檔案
    }
  },
})

eventOnLoadingChange #

Optional/Function

web component loading狀態改變event hook

外部可用來決定是否顯示loading

function可用參數 #

• status: Boolean, 當status為true代表web component正在上傳檔案中, false則反之

eventOnUploadRejectedForFileEmpty #

Optional/Function

因為沒選擇檔案導致上傳被拒絕的event hook

外部可用來顯示錯誤訊息提示User要先選取檔案

範例 #

window.uploader.init({
  eventOnUploadRejectedForFileEmpty: () => alert('請先選擇檔案'),
})

eventOnUploadRejectedForUploading #

Optional/Function

因為還有檔案在上傳中導致上傳被拒絕的event hook

外部可用來顯示錯誤訊息提示User目前還有檔案正在上傳中無法上傳

範例 #

window.uploader.init({
  eventOnUploadRejectedForUploading: () => alert('還有檔案正在上傳中'),
})

eventOnMultipartUploadStatusChange #

Optional/Function

上傳狀態改變event hook

function可用參數 #

• isUploading: Boolean, 是否正在上傳檔案

範例 #

window.uploader.init({
  eventOnMultipartUploadStatusChange: (status) => {
    if(status) {
      alert('檔案上傳中')
    } else {
      alert('檔案上傳結束')
    }
  },
})

eventOnMultipartUploadProgress #

Optional/Function

上傳進度改變的event hook

function可用參數 #

• uploadStatus: Object, S3大檔分段上傳的進度資訊物件, 詳見Data Model - uploadStatus

範例 #

html

<div id="upload-status-info" style="margin: 20px 0; display: none">
  <p>上傳階段: <span id="upload-stage"></span></p>
  <p>已上傳片段數: <span id="upload-uploaded"></span></p>
  <p>檔案總片段數: <span id="upload-total"></span></p>
  <p>進度百分比: <span id="upload-progress"></span>%</p>
</div>

javascript

window.uploader.init({
  eventOnMultipartUploadProgress: (status) => {
    $('#upload-stage').text(status.stage)
    $('#upload-uploaded').text(status.uploaded)
    $('#upload-total').text(status.total)
    $('#upload-progress').text(status.progress)
  },
  eventOnMultipartUploadStatusChange: (status) => {
    if(status) {
      $('#upload-status-info').show()
    } else {
      $('#upload-status-info').hide()
    }
  },
})

eventOnMultipartUploadFail #

Optional/Function

上傳失敗event hook

function可用參數 #

• file: File, js的File介面
• error: Error, 發生的錯誤資訊(js Error), 這個error通常只要console.error即可, 只需要顯示訊息讓User知道上傳失敗即可

範例 #

window.uploader.init({
  eventOnMultipartUploadFail: (file, error) => {
    console.error(error)
    alert(`檔案上傳出現意外的錯誤, 可能是暫存檔案已過期, 請再重新上傳一次`)
  },
})

eventOnMultipartUploadSuccess #

Optional/Function

上傳成功event hook

function可用參數 #

• uploadSuccessData: Object, 檔案上傳成功資訊
  • size: Number, 檔案大小(bytes)
  • filename: String, 檔案名稱
  • s3Path: String, 檔案儲存在S3的路徑(s3 object key)
  • fileType: String, 檔案類型(例如: video/mp4)
  • fileUid: String, 檔案uid, 用於建立media convert job用

範例 #

window.uploader.init({
  eventOnMultipartUploadSuccess: data => {
    alert(`${data.filename}已上傳成功, S3路徑:${data.s3Path}`)
    // TODO 應用程式使用這個data物件, call內部的API將檔案路徑儲存在DB中(可能與資料實體綁定)
  },
})

eventOnFileValidateFail #

Optional/Function

當User選擇檔案後

Web component將會驗證檔案是否為影片檔

若驗證失敗將會觸發此event hook

您可用使用此event hook來顯示錯誤訊息

function可用參數 #

• file: File, js的File介面

範例 #

window.uploader.init({
  eventOnFileValidateFail: (file) => {
    alert(`${file.name}並不是影片檔案, 請選擇影片檔再繼續`)
  },
})

eventOnCreateMediaConvertJobSuccess #

Optional/Function

串流影片轉檔任務成功

您可使用此hook取得轉檔任務資料

將需要的資訊存至資料庫

請注意, 必須將autoTriggerMediaConvertJob設定為true

啟動MediaConvert轉檔成功後才會執行此hook

function可用參數 #

• job: Object, 轉檔任務(詳見Data Model - mediaConvertJob)

範例 #

window.uploader.init({
  eventOnCreateMediaConvertJobSuccess: (job) => {
    // TODO
  },
})

eventOnCreateMediaConvertJobFail #

Optional/Function

串流影片轉檔任務失敗

function可用參數 #

• error: Error, 轉檔任務失敗錯誤

範例 #

window.uploader.init({
  eventOnCreateMediaConvertJobFail: (error) => {
    // TODO
  },
})

eventOnPollMediaConvertJobData #

Optional/Function

前端poll取得轉檔任務event hook

function可用參數 #

• job: Object, 轉檔任務(詳見Data Model - mediaConvertJob)
• status: String, 影片轉檔狀態
• progress: Number, 影片轉檔進度百分比

範例 #

window.uploader.init({
  eventOnPollMediaConvertJobData: (error) => {
    // TODO
  },
})

eventOnClearPollMediaConvertJobInterval #

Optional/Function

前端自動poll取得轉檔任務機制結束

當前端取得轉檔任務(job)的狀態為以下狀態將會停止poll

• COMPLETE: 轉檔完成
• CANCEL: 取消轉檔
• ERROR: 轉檔失敗

範例 #

window.uploader.init({
  eventOnClearPollMediaConvertJobInterval: (error) => {
    // TODO
  },
})

eventOnStaticVodUploadSuccess #

Optional/Function

靜態影片上傳成功

function可用參數 #

• data: Object, 靜態影片資訊
  • url: String, 靜態影片網址(可直接拿來播放)

範例 #

window.uploader.init({
  eventOnStaticVodUploadSuccess: (data) => {
    // TODO
  },
})