嵌入 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 對話同練習結果，佢哋喺每個套件入面嘅運作方式都一樣。