Wijeti ya tovuti

Ukurasa huu umetafsiriwa kutoka Kiingereza. Ikiwa hizi mbili zinatofautiana, ukurasa wa Kiingereza ndio sahihi. Soma ukurasa wa Kiingereza

Kwenye tovuti, Lingara huendeshwa kama kipengele maalum (custom element), <lingara-embed>. Kipengele huchora mazoezi ya Lingara ndani ya fremu inayotolewa na Lingara, kwa hivyo ukurasa wako hauoni kamwe data ya mwanafunzi na ukurasa wa Lingara hauoni kamwe data yako.

Weka kipengele

Sakinisha @lingara/embed kutoka npm, au pakia toleo lake la moduli kutoka CDN ikiwa tovuti yako haina bundler. Kisha weka <lingara-embed> kwenye ukurasa na ukifafanue. Kipengele huchukua:

plan-id, mpango wa somo wa kufanyia mazoezi, ambao mchezaji anaumiliki;
surface, kile cha kuonyesha: practice, chaguo-msingi na uso pekee uliopo;
theme, mojawapo ya light, dark au auto;
locale, lugha ya maneno ya fremu yenyewe, ambayo vinginevyo hufuata mwanafunzi;
title, jina linalofikika la fremu.

Upambaji unaishia kwenye mandhari. Ukurasa wako hauwezi kufikia ndani ya fremu, na mandhari ndiyo mpangilio pekee inayotoa.

Kipe tokeni

Weka tokenProvider ya kipengele kuwa kitendakazi kinachoomba tokeni kutoka kwa seva yako mwenyewe. Seva yako huitengeneza kwa asili (origin) ya ukurasa, ikitumia kifurushi cha seva, na hujibu kwa tokeni na muda wake wa kuisha. Kipengele hukabidhi tokeni kwa fremu kwa ujumbe, na haisafiri kamwe ndani ya URL.

Sajili kila asili ambayo wijeti inaendeshwa juu yake kabla ya kutengeneza tokeni kwa ajili yake, katika mipangilio ya mteja wako kwenye dashibodi. Ukurasa wa vifurushi vya seva unaeleza jinsi. API hukataa tokeni iliyotengenezwa kwa asili nyingine yoyote, na fremu huonyesha hitilafu badala ya mazoezi.

Kifurushi cha seva kinaweza pia kukuandikia kipande kizima cha msimbo, kipengele na mtoa tokeni pamoja, kikiwa na script nonce ya ukurasa wako ikiwa sera yako ya usalama wa maudhui inaihitaji. Mfano wa mwisho hapa chini unaonyesha hilo.

Sikiliza kile fremu inasema

Fremu huzungumza na kipengele kupitia itifaki ya ujumbe yenye matoleo, na kipengele hugeuza kile ambacho ukurasa wako unahitaji kuwa matukio ya DOM:

lingara:practice-completed mwanafunzi anapokamilisha seti, pamoja na planId, setNumber, correct na total zake;
lingara:error fremu inaposimama, pamoja na code na retryable. Hitilafu inayoweza kujaribiwa upya inamaanisha kwamba kuweka kipengele upya kunaweza kufaulu; ni juu yako kuamua lini ujaribu tena.

Matokeo ya mazoezi hufika kwenye seva yako pia, kama inavyoelezwa katika matokeo ya mazoezi.

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();