嵌入 Lingara

本頁譯自英文。如兩者有出入，以英文頁面為準。 閱讀英文頁面

Lingara 可以存在於你的遊戲或網站之中。你的世界裡的角色可以依照玩家的等級與其對話，玩家完成的練習也會計為 Lingara 練習。嵌入分為兩半，首先要確定的是哪一半在哪裡執行。

誰持有什麼

你的伺服器持有你的 OAuth 用戶端密鑰和你的 webhook 簽章密鑰。兩者都永遠不會離開伺服器。

玩家的裝置只持有一樣東西：一個嵌入權杖，以 lgr_et_ 開頭。你在遊戲二進位檔或網頁中發布的任何內容都是公開的，所以裝置從不持有用戶端密鑰、webhook 密鑰或你自己用戶端的存取權杖。嵌入權杖只代表一名玩家行事，有效期以分鐘而非小時計，而且只持有你的伺服器授予它的權限範圍。

玩家不需要 Lingara 帳戶。你的伺服器第一次為某位玩家核發權杖時，會為其建立一個訪客學習者，之後的每個權杖都指向同一個學習者。已經擁有 Lingara 帳戶的玩家可以帶上它：伺服器套件頁面說明了你的伺服器如何把兩者連結起來。

權杖如何送到玩家手中

1. 位於你的遊戲或頁面中的玩家套件需要權杖時，會透過它的權杖來源向你的伺服器要求。
2. 你的伺服器檢查自己為該玩家保存的工作階段，並用伺服器套件為其核發權杖。
3. 你的伺服器以兩個欄位（權杖及其到期時間）把權杖交回，透過你自己的工作階段傳遞，絕不放在 URL 中。
4. 玩家套件會一直使用該權杖，直到它接近到期，再重新向你的伺服器要求。Lingara 從不更新權杖。

 player's device                your server                    Lingara
 ───────────────                ───────────                    ───────
 player kit ── needs a token ──▶ your token route
                                 server kit ── mint ─────────▶ token for one player
 player kit ◀── token, expiry ── your token route ◀──────────
 player kit ── API calls with the token ─────────────────────▶

網站用的權杖會繫結到一個來源：頁面自身的協定、主機和連接埠。在為某個來源核發權杖之前，先註冊你的小工具執行的每一個來源，詳見伺服器套件頁面。遊戲用的權杖沒有來源。

權杖可以做什麼

你的伺服器在核發每個權杖時選擇它的權限範圍，可從以下五個中選擇：events:read、events:write、lesson_plans:read、lesson_plans:write 和 embed:play。權杖只能持有你自己的用戶端已經持有的權限範圍。embed:play 讓玩家可以與你的角色對話，並回報他們完成的練習。

誰付費

只有使用按用量計費方案的用戶端才能核發權杖。玩家用權杖所做的一切都會計入你的用戶端的用量並向你收費，而不是向玩家收費。

刪除玩家

當玩家在你的遊戲中刪除自己的帳戶時，你的伺服器也要在 Lingara 刪除該玩家。這會移除其學習者以及 Lingara 為其保存的一切，並撤銷其持有的每一個權杖。

你需要哪個套件

每個整合都使用兩個套件：你伺服器上的伺服器套件，以及玩家遊玩之處的玩家套件。

接著閱讀 NPC 對話和練習結果，它們在每個套件中的運作方式都相同。