Lingara Lingara بەڵگەنامەکان ڕێنماییەکان API کتێبخانەکان ئەپەکان دروستکردن جێگیرکردن ئەپی وێب
زمان: سۆرانی

ئەورووپا

ئاسیا

ڕۆژهەڵاتی ناوەڕاست

ئەفریقا

ویجێتی ماڵپەڕ

ئەم پەڕەیە لە ئینگلیزییەوە وەرگێڕدراوە. ئەگەر هەردووکیان جیاواز بوون، پەڕە ئینگلیزییەکە ڕاستە. پەڕە ئینگلیزییەکە بخوێنەوە

لەسەر ماڵپەڕێک، Lingara وەک توخمێکی تایبەت، <lingara-embed>، کار دەکات. توخمەکە ڕاهێنانی Lingara لەناو چوارچێوەیەکدا دەکێشێت کە Lingara پێشکەشی دەکات، بۆیە پەڕەکەت هەرگیز داتای فێرخوازەکە نابینێت و پەڕەی Lingara هەرگیز هی تۆ نابینێت.

توخمەکە دابنێ

@lingara/embed لە npm ـەوە دابمەزرێنە، یان ئەگەر ماڵپەڕەکەت bundler ی نییە بنیاتی مۆدیولەکەی لە CDN ێکەوە بار بکە. پاشان <lingara-embed> بخەرە سەر پەڕەکە و پێناسەی بکە. توخمەکە ئەمانە وەردەگرێت:

  • plan-id، ئەو پلانی وانەیەی ڕاهێنانی لەسەر دەکرێت، یەکێک کە یاریزانەکە خاوەنیەتی؛
  • surface، چی نیشان بدات: practice، بنەڕەتییەکە و تاکە ڕووکار کە هەیە؛
  • theme، یەکێک لە light، dark یان auto؛
  • locale، زمانی وشەکانی خودی چوارچێوەکە، کە ئەگەرنا شوێن فێرخوازەکە دەکەوێت؛
  • title، ناوی دەستپێگەیشتنی چوارچێوەکە.

شێوەدان لە تێمەکەدا دەوەستێت. پەڕەکەت ناتوانێت بگاتە ناو چوارچێوەکە، و تێمەکە تاکە ڕێکخستنە کە پێشکەشی دەکات.

تۆکنی پێبدە

tokenProvider ـی توخمەکە بکە بە فەنکشنێک کە داوای تۆکن لە سێرڤەرەکەی خۆت دەکات. سێرڤەرەکەت بە origin ـی پەڕەکە دروستی دەکات، بە بەکارهێنانی کیتی سێرڤەر، و بە تۆکنەکە و کاتی بەسەرچوونی وەڵام دەداتەوە. توخمەکە تۆکنەکە بە پەیام ڕادەستی چوارچێوەکە دەکات، و هەرگیز لە URL دا گەشت ناکات.

هەموو ئەو origin انەی ویجێتەکە لەسەریان کار دەکات پێش دروستکردنی تۆکن بۆیان تۆمار بکە، لە ڕێکخستنەکانی کلاینتەکەتدا لە کۆنسۆڵ. پەڕەی کیتەکانی سێرڤەر دەڵێت چۆن. API ئەو تۆکنە ڕەت دەکاتەوە کە بۆ هەر origin ێکی تر دروستکرابێت، و چوارچێوەکە لە جیاتی ڕاهێنان هەڵەیەک نیشان دەدات.

کیتێکی سێرڤەر دەتوانێت هەموو پارچە کۆدەکەش بۆت بنووسێت، توخم و دابینکەری تۆکن پێکەوە، لەگەڵ script nonce ـی پەڕەکەت ئەگەر سیاسەتی ئاسایشی ناوەڕۆکەکەت پێویستی پێی بێت. دوایین نموونەی خوارەوە نیشانی دەدات.

گوێ لەوە بگرە کە چوارچێوەکە دەیڵێت

چوارچێوەکە لە ڕێگەی پرۆتۆکۆلێکی پەیامی وەشاندارەوە لەگەڵ توخمەکە قسە دەکات، و توخمەکە ئەوەی پەڕەکەت پێویستی پێیەتی دەیکات بە ڕووداوەکانی DOM:

  • lingara:practice-completed کاتێک فێرخوازەکە کۆمەڵەیەک تەواو دەکات، لەگەڵ planId، setNumber، correct و total ـەکەی؛
  • lingara:error کاتێک چوارچێوەکە دەوەستێت، لەگەڵ code و retryable. هەڵەیەکی شیاوی هەوڵدانەوە واتای ئەوەیە کە دانانێکی نوێ لەوانەیە سەرکەوێت؛ کەی دووبارە هەوڵ بدەیتەوە بڕیاری خۆتە.

ئەنجامی ڕاهێنانەکە دەگاتە سێرڤەرەکەتیش، وەک لە ئەنجامەکانی ڕاهێنان دا ڕوونکراوەتەوە.

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)
})
زمانی نموونەی کۆد

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")
})?;

Go

// 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,
    ));
}

C#

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