嵌入 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 对话和练习结果，它们在每个工具包中的工作方式都相同。