# 英語課程多元學習沉浸式數位教材
==**AI案次(11-15) - Linebot 使用說明**==

本文件包含環境設定與程式架構與發佈方法，若有特殊功能需參照可直接點選下列目錄至您想了解的功能；若為初次接觸者，請按順序閱讀此檔案、並依序操作。

[TOC]

*****

## 環境設定

建立此系統所需要的線上免費資源包含
* Line developer：程式<-->聊天機器人
* Heroku：程式<-->網路
* Google APIs中的Google sheets：程式<-->Google sheets

其他所需套件包含
* python
* git

接下來將會依序介紹上述資源的使用流程。

### **Line developer**
Line developer 的用途是建立與管理Linebot帳戶，連結程式碼及機器人的平台。

#### 背景資料
> Website：[Line developer](https://developers.line.biz/zh-hant/)
> 登入類別：Line business account
> 帳號：[e-mail]
> 密碼：eng66316666
> 提供者：英語遠距計畫
> 頻道：英語學習好朋友

#### 基礎設定
在這個頁面中，您可以取得／設定聊天機器人的
* 圖像（Channel icon）
* 說明文字（Channel description）
* Channel secret: 這個是讓程式連結聊天機器人的金鑰之一，詳細使用說明會放在[程式部分](#app.py)解釋。

#### 聊天API（Messaging API）
在這個頁面中，您可以取得／設定聊天機器人的
* 聊天機器人QRcode：掃描即可加入好友。
* 聊天機器人id： @990rwgwr
* Webhook URL：目前是 https://iiiedu-eng.herokuapp.com/callback ，連結是heroku的程式，詳細使用說明會放在heroku部分解釋。
* 使用webhook：需要開啟。
* Channel access token：這個是讓程式連結聊天機器人的金鑰之一，詳細使用說明會放在程式部分解釋。

### **Heroku**
Heroku 的用途是連結程式碼及機器人的平台。
#### 背景資料
> Website：[Heroku](https://dashboard.heroku.com/)
> 帳號：[e-mail]
> 密碼：eng@66316666
> app：iiiedu-eng

#### 本機設定
在本機使用Heroku需利用 Heroku CLI 和 Git 來控制及運作，這裡將進行Heroku CLI的教學。

Heroku CLI可以在[這裡](https://devcenter.heroku.com/articles/heroku-cli)，安裝完可以在cmd中以下述指令檢查是否安裝完成。
> $ heroku -h

確定下載完 heroku CLI後，先登入以方便後續操作。帳號及密碼為上述「背景資料」中的帳密。
> $ heroku login

heroku的設定到此為止，接著便需要使用 git，後續步驟請查閱[git的教學](#Git)。

#### 網頁功能：Deploy
這個頁面是協助將程式發佈到網站上，可以利用 Heroku CLI 和 Git 來進行。

#### 網頁功能：Setting
* APP information：Heroku git URL 為程式的git位置
* Config Vars：管理程式中的一些特定變數。請確認其中已加入下列 *KEY* 和 *VALUE* ：

> CHANNEL_ACCESS_TOKEN [<your_channel_access_token>](#聊天api（messaging-api）)
> CHANNEL_SECRET [<your_channel_secret>](#基礎設定）)

* Buildpacks：請確認已加入下列package

> heroku/python
> https://github.com/jonathanong/heroku-buildpack-ffmpeg-latest.git

#### 網頁功能：More
點選 *view log* 即可看到程式執行時的log訊息。

### Google APIs
Google APIs 的用途是連結程式與google sheet的設定。

#### 背景資料
> Website：[Google APIs](https://cloud.google.com/apis)
> 帳號：[e-mail]
> 密碼：eng66316666

#### 金鑰生成
1. 進入 *API Manager*
2. 點選 *憑證*
3. 在 *服務帳戶* 中點選 *管理服務帳戶*
4. 原先已有帳戶 [e-mail]， 若無請點選 *建立服務帳戶*
5. 在目標帳戶的最末端點選 *動作 > 建立金鑰*
6. 點選 *json* 建立
7. 將目標下載檔案更名為“driveKey”，並放至目標資料夾

#### 連結Google sheets
1. 進入此帳戶的[Google 雲端硬碟](https://drive.google.com/drive/u/0/my-drive?hl=zh-TW)
2. 將需要讀取的 sheets 上按右鍵選擇 *共用*
3. 新增共用使用者： [e-mail]

原本的表單包含：
1. [發音練習](https://docs.google.com/spreadsheets/d/194F1eOLPBick8Veoti9XtXEnypQgcIK6_dc9LcFUJDc/edit?usp=sharing)
2. []()
3. []()
4. []()
5. []()

### Git

#### 下載
請根據您所使用的電腦作業系統於[Git 官網](https://git-scm.com/)下載相對應版本的git。

#### 基礎設定
下載完git後，開啟cmd（命令提示字元）到您欲存放此計畫的位置中，並設定git帳戶。
例如：若我想將檔案放在桌面，應輸入：
> $ cd Desktop

其他cmd語法教學請參考[介紹命令行(command-line)介面](https://carolhsu.gitbooks.io/django-girls-tutorial-traditional-chiness/content/intro_to_command_line/README.html)

目前的設定如下：
> $ git config --global user.name "iiiedu-eng"
> $ git config --global user.email "[e-mail]"

第一次使用時，請確認heroku已登入。登入後我們先從heroku下載最新版本的程式，更新完後便可進行修改。
> $ git clone https://git.heroku.com/iiiedu-eng.git

#### 更新並使用程式
修改完程式後，請再確認cmd位置後輸入下列程式，以將程式上傳部署至heroku；"<comments>" 中請填入這次修改的內容作為git版本控管的紀錄。

> $ git add .
> $ git commit -m "<comments>"
> $ git push heroku master

當cmd指令執行完成後，可以切換頁面至Heroku網頁中的 ==view log== ，若看到以下文字即linebot發布成功、可以使用。

> heroku[web.1]: State changed from starting to up

#### 重啟程式
若遇到error或者太久沒使用使heroku的狀態已轉為休息模式，可以在cmd中打入下列指令以重啟程式：

> $ heroku restart -a iiiedu-eng

當cmd指令執行完成後，可以切換頁面至Heroku網頁中的 *view log* ，若看到以下文字即linebot發布成功、可以使用。

> heroku[web.1]: State changed from starting to up

*****

### 設定

#### app.py
以下環境變數皆以 *<SETUP>* 來標示，可依續搜尋 *<SETUP>* 來確認環境變數

> #<SETUP>
> WebhookHandler(<channel_secret>)
> LineBotApi(<channel_access_token>)
> GDriveJSON = 'driveKey.json'

*****

## 檔案列表

下載後路徑中應包含下列檔案：

* app .py
* driveKey.json：若缺此檔案可藉由[此](#金鑰生成)來生成新檔案
* Procfile
* README .md
* requirements.txt
* getVoc .py
* QA_bubble.py
* QA .py

*****

## 程式說明

在此資料夾中的檔案，以下是設定相關、==不能更動==的：
* requirements.txt
* Procfile
* driveKey.json

其他檔案之說明如下：
### app.py
此檔案為主要程式，所有的訊息處理都以handler處理。
* UnfollowEvent
* MessageEvent (TextMessage)
* MessageEvent (AudioMessage)
* PostbackEvent

其中，依照功能有類似的函數：
* setLevel_L/S/P/Q：設定難易度並取得相關題目
* rightBubble/tryagainBubble/nextBubble/finalBubble：聽力口說閱讀使用的
* ButtonBubble/TextBubble/ImageBubble/ConfirmBubble：瑟賽斯之門用的

在選擇題型種類時，是以文字訊息做為判斷，所以可以藉由點選菜單或是直接輸入相對應文字來進入題目。
type包含：['translation'(翻譯功能), 'quiz'(閱讀功能), 'listen'(聽力功能), 'speech'(口說功能), 'game'(瑟賽斯之門功能), 'score'(成績查看功能)]

在做按鈕回覆判斷時，postback的格式為：「type [等級; 功能; 題號] /[選項]」
> type：目前所在的題型
>
>> (1) 等級只會在選難易度時出現，會以L, M, H的方式呈現
>> (2) 功能包含start(開始每一個題目), next(重新開始新一輪), again(再試一次), end(完成這一輪)...
>> (3) 題號是針對回答問題時，判斷是否在正確的題目上按按鈕
>
> 選項只會在第二個是題號時出現，為1~4。

其餘的檔案也包含了一些函數，功能如下：
### getVoc.py
讀取聽力題目的函數，包含：
* getSheet 讀取挑定難易度的單字表單，並回傳該表單
* editSheet
* getOption 篩選單字他的選項
* getVoc 選單字
* getQA 亂數選項順序
* getAudio 取音檔

### QA_bubble.py
製作聊天泡泡的函數，包含：
* Voc 單字題
* Cloze 克漏字題
* Cloze_L3 高級克漏字題（四選項）
* Reading 閱讀題（單字下一個）
* Article 閱讀文章題

### QA.py
* getSheet 讀取挑定難易度的單字表單，並回傳該表單
* editSheet
* getOption 篩選單字他的選項
* getVoc 選單字
* getQA 亂數選項順序
* getAudio 取音檔

*****

## 除錯訊息

cmd 中較常出現之錯誤包含：
1. git無法push:
> $ error: src refspec master does not match any
> $ error: failed to push some refs to 'https://git.heroku.com/iiiedu-eng.git'

請將以下：
> $ git push heroku master

改成以下：
> $ git push heroku HEAD:master

Heroku log 中目前較常出現之錯誤包含：
1. Google api error:
此錯誤源自於Google api的讀取次數，由於免費版本的google api有時限內的讀取數量限制。
如果在「使用過程」中發生此error請稍待片刻再重新執行動作。
如果在「啟用程式」時發生此error請重啟此heroku app。
> $ heroku restart