Embedding Lingara

Lingara can live inside your game or your website. A character in your world can hold a conversation at the player’s level, and practice your player finishes counts as Lingara practice. The embed has two halves, and the first thing to settle is which half runs where.

Who holds what

Your server holds your OAuth client’s secret and your webhook signing secret. Neither ever leaves it.

The player’s device holds one thing: an embed token, which starts lgr_et_. Anything you ship inside a game binary or a web page is public, so the device never holds a client secret, a webhook secret or an access token of your own client. An embed token acts for one player only, lasts minutes rather than hours, and holds only the scopes your server gave it.

A player needs no Lingara account. The first token your server mints for a player creates a guest learner for them, and every later token reaches the same learner. A player who already has a Lingara account can bring it: the server kits page describes how your server links the two.

How a token reaches the player

1. The player kit, in your game or on your page, needs a token and asks your server through its token source.
2. Your server checks its own session for that player and mints a token for them with the server kit.
3. Your server hands the token back as two fields, the token and its expiry, through your own session and never in a URL.
4. The player kit uses the token until it nears its expiry, then asks your server again. Lingara never refreshes a token.

 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 ─────────────────────▶

A token for a website is bound to one origin: the page’s own scheme, host and port. Register every origin your widget runs on before you mint for it, as the server kits page describes. A token for a game has no origin.

What a token may do

Your server chooses each token’s scopes when it mints it, from these five: events:read, events:write, lesson_plans:read, lesson_plans:write and embed:play. A token can hold only scopes your own client already holds. embed:play lets the player hold conversations with your characters and report the practice they finish.

Who pays

Only a client on the metered plan may mint tokens. Everything a player does with a token is counted as your client’s usage and billed to you, not to the player.

Deleting a player

When a player deletes their account in your game, your server deletes them at Lingara too. That removes their learner and everything Lingara holds for them, and revokes every token they hold.

Which kit you need

Every integration uses two kits: a server kit on your server, and a player kit where the player plays.

Then read NPC dialogue and practice results, which work the same way in every kit.