Widget para sitios web

Esta página está traducida del inglés. Si ambas difieren, la página en inglés es la correcta. Leer la página en inglés

En un sitio web, Lingara se ejecuta como un elemento personalizado, <lingara-embed>. El elemento dibuja la práctica de Lingara en un marco servido por Lingara, de modo que tu página nunca ve los datos del aprendiz y la página de Lingara nunca ve los tuyos.

Montar el elemento

Instala @lingara/embed desde npm, o carga su versión de módulo desde un CDN si tu sitio no tiene bundler. Después pon <lingara-embed> en la página y defínelo. El elemento admite:

plan-id, el plan de lección que se va a practicar, que debe ser del jugador;
surface, qué mostrar: practice, el valor predeterminado y la única superficie que hay;
theme, uno de light, dark o auto;
locale, el idioma de los textos propios del marco, que de lo contrario sigue al aprendiz;
title, el nombre accesible del marco.

El estilo se limita al tema. Tu página no puede acceder al interior del marco, y el tema es el único ajuste que ofrece.

Darle tokens

Asigna al tokenProvider del elemento una función que pida un token a tu propio servidor. Tu servidor lo emite con el origen de la página, usando un kit de servidor, y responde con el token y su caducidad. El elemento pasa el token al marco mediante un mensaje, y el token nunca viaja en una URL.

Registra cada origen en el que se ejecute el widget antes de emitir tokens para él, en la configuración de tu cliente en la consola. La página de kits de servidor explica cómo. La API rechaza un token emitido para cualquier otro origen, y el marco muestra un error en lugar de la práctica.

Un kit de servidor también puede escribir por ti el fragmento completo, el elemento y el proveedor de tokens juntos, con el nonce de script de tu página si tu política de seguridad de contenido lo requiere. El último ejemplo de abajo lo muestra.

Escuchar lo que dice el marco

El marco se comunica con el elemento mediante un protocolo de mensajes con versiones, y el elemento convierte lo que necesita tu página en eventos del DOM:

lingara:practice-completed cuando el aprendiz termina un conjunto, con su planId, setNumber, correct y total;
lingara:error cuando el marco se detiene, con un code y retryable. Un error reintentable significa que un nuevo montaje puede tener éxito; cuándo volver a intentarlo lo decides tú.

El resultado de la práctica también llega a tu servidor, como se describe en resultados de práctica.

npm install @lingara/embed@0.1.0-alpha.6
# No bundler? One module script instead:
# <script type="module" src="https://cdn.jsdelivr.net/npm/@lingara/embed@0.1.0-alpha.6/dist/lingara-embed.min.js"></script>

<!-- plan-id is a lesson plan your server made for this player. -->
<lingara-embed surface="practice" plan-id="0b9d4f2e-3c1a-4e8b-9f6d-2a7c5e1b8d40" theme="auto" title="Practice"></lingara-embed>
<script type="module">
  import { defineLingaraEmbed } from '@lingara/embed'
  defineLingaraEmbed()
</script>

// Your own endpoint, on your own server. It mints with this page's origin and
// returns exactly { token, expires_at }: the token (lgr_et_…) never touches a URL.
widget.tokenProvider = async () => {
  const response = await fetch('/lingara/token', { method: 'POST', credentials: 'same-origin' })
  if (!response.ok) throw new Error(`token endpoint answered ${response.status}`)
  return response.json()
}

widget.addEventListener('lingara:practice-completed', (event) => {
  const { planId, setNumber, correct, total } = (event as CustomEvent).detail
  console.log(`set ${setNumber} of ${planId}: ${correct}/${total}`)
})
widget.addEventListener('lingara:error', (event) => {
  const { code, retryable } = (event as CustomEvent).detail
  // `retryable` means a remount may succeed; when to try is yours to decide.
  if (retryable) setTimeout(() => widget.reload(), 30_000)
  else console.warn('Lingara practice stopped:', code)
})

TypeScriptRustGoJavaKotlinRubyPHPC#

TypeScript

// The page that mounts the widget: the token never appears in it.
export function practicePage(planId: string, cspNonce: string): string {
  const widget = widgetSnippet({ planId, tokenEndpoint: '/lingara/token', theme: 'auto', locale: 'fr', title: 'Pratique', nonce: cspNonce })
  return `<!doctype html><title>Practice</title>${widget}`
}

Rust

// The element, its script build and a token provider that POSTs to your
// token route. The token never appears in the markup.
let html = widget_snippet(&SnippetOptions {
    locale: Some("fr".into()),
    nonce: Some(csp_nonce.into()), // your page's CSP nonce, for a strict script-src
    ..SnippetOptions::new(plan_id, "/lingara/token")
})?;

// The plan your server made for this player, and the token route above.
// Pass the request's CSP nonce when your script-src allows no inline
// script; the token itself never appears in the markup.
theme := "auto"
html, err := lingaraembed.WidgetSnippet(lingaraembed.SnippetOptions{
	PlanID:        planID,
	TokenEndpoint: "/lingara/token",
	Theme:         &theme,
	Nonce:         &cspNonce,
})
if err != nil {
	return "", err // a *lingaraembed.SnippetError names the refused option
}
return template.HTML(html), nil // already escaped by the kit

Java

// planId is the lesson plan your server made for this player. The element
// POSTs to tokenEndpoint with same-origin cookies: the token never appears
// in the markup. Pass this request's CSP nonce if your page sets one.
String html =
    WidgetSnippet.render(
        SnippetOptions.builder(planId, "/lingara/token").locale("fr").nonce(cspNonce).build());

Kotlin

// planId is the lesson plan your server made for this player. The element
// POSTs to tokenEndpoint with same-origin cookies: the token never appears
// in the markup. Pass this request's CSP nonce if your page sets one.
val html =
    widgetSnippet(
        SnippetOptions(planId, tokenEndpoint = "/lingara/token").apply {
            locale = "fr"
            nonce = cspNonce
        },
    )

Ruby

# The plan your server made for this player, rendered into your page.
# nonce: your page's CSP nonce, when its script-src allows no inline script.
def self.widget(plan_id, csp_nonce)
  Lingara::Embed.widget_snippet(plan_id: plan_id, token_endpoint: "/lingara/token", locale: "fr", nonce: csp_nonce)
end

PHP

use Lingara\Embed\SnippetOptions;
use Lingara\Embed\WidgetSnippet;

// In your page's template: the plan your server made for this player, and
// your token route. Pass the request's CSP nonce if your script-src allows
// no inline script. A bad option throws SnippetException naming its field.
function practiceWidget(string $planId, string $cspNonce): string
{
    return WidgetSnippet::render(new SnippetOptions(
        planId: $planId,
        tokenEndpoint: '/lingara/token',
        theme: 'auto',
        nonce: $cspNonce,
    ));
}

app.MapGet("/practice/{planId}", (string planId, HttpContext http) =>
{
    var widget = WidgetSnippet.Render(new SnippetOptions
    {
        PlanId = planId,                              // the plan your server made for this player
        TokenEndpoint = "/lingara/token",             // same origin: the element sends this page's cookies
        Nonce = http.Items["csp-nonce"] as string,     // your CSP's nonce, if script-src has one
    });
    return Results.Content($"<!doctype html><title>Practice</title>\n{widget}", "text/html");
}).RequireAuthorization();