Hoe integreer je de Linguineo-gespreksspeler in je leeromgeving?

๐ŸŽ“ Hoe integreer je de Linguineo-gespreksspeler in je leeromgeving?

Met de conversationele AI-speler van Linguineo oefenen leerders spreken in realistische situaties, rechtstreeks vanuit jouw platform. In deze tutorial leggen we stap voor stap uit hoe je de speler in je LMS of eigen leeromgeving integreert.

๐Ÿ” 1. Identity provider instellen & het access token ophalen

Belangrijk: in een echte productieomgeving moet je je eigen identity provider gebruiken. Je moet de URL van je JWKS-set met ons delen bij Linguineo. Ons team stelt dit in op onze API’s: deze stap kun je niet zelf uitvoeren. Om het eenvoudig te houden, tonen we de integratie in deze tutorial met de Keycloak identity provider van Linguineo.

Eerst meld je je gebruikers aan en haal je een access token op voor de speler.

Gebruik de identity provider van Linguineo (alleen om te testen of voor een demo):

Eenvoudige aanmeldflow in JavaScript:

Voeg de volgende knop toe aan je HTML-pagina:

<button id="login">Login with OAuth</button>

Voeg daarna het volgende JavaScript-script toe. Deze code zet het opgehaalde access token op het element met id linguineo-conversation op je pagina (dat we in de volgende stappen toevoegen):

const clientId = 'moodle';
const authorizationUrl = 'https://keycloak.linguineo.com/auth/realms/moodle/protocol/openid-connect/auth';
const tokenUrl = 'https://keycloak.linguineo.com/auth/realms/moodle/protocol/openid-connect/token';

document.getElementById('login').onclick = () => {
  const authUrl = `${authorizationUrl}?response_type=code&client_id=${clientId}&redirect_uri=${encodeURIComponent(window.location.href)}&scope=openid`;
  window.location.href = authUrl;
};

const params = new URLSearchParams(window.location.search);
if (params.has('code')) {
  const code = params.get('code');
  fetch(tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: window.location.href,
      client_id: clientId,
    }),
  })
  .then(res => res.json())
  .then(data => {
    const accessToken = data.access_token;
    document.getElementById('linguineo-conversation').setAttribute('access-token', accessToken);
  });
}

Om de aanmelding met de identity provider van Linguineo te testen, kun je gebruiker tester01 met wachtwoord testing2025 gebruiken

๐Ÿงฉ 2. De nodige JavaScript-bestanden importeren

Om de component linguineo-conversation te gebruiken, voeg je de volgende script-tags toe aan je pagina (meestal onderaan):

<script nomodule src="https://cdn.linguineo.com/linguineo-conversation/1.0.0/conversation-webcomponents-es5.js"></script>
<script type="module" src="https://cdn.linguineo.com/linguineo-conversation/1.0.0/conversation-webcomponents-es2015.js"></script>

Wil je liever niet naar URL’s van Linguineo verwijzen? Kopieer deze js- en css-bestanden dan gerust naar je eigen omgeving. Je kunt ze hier downloaden.

๐Ÿงฑ 3. De component <linguineo-conversation> aan de pagina toevoegen

Voorzie een container voor de speler en voeg de component met jouw configuratie toe. Hoe je de component linguineo-conversation configureert, lees je in detail hier.

<style>
  .linguineo-conversation-container {
    height: 100vh;
    width: 100vw;
  }
</style>

<div class="linguineo-conversation-container">
  <linguineo-conversation
    id="linguineo-conversation"
    access-token=""
    auth-method="bearer"
    bot-name="Bot"
    application="TEST_APP"
    language="fr"
    tutor-language="nl"
    scenario-id="503"
    answer-type="SPEAKING_WITH_INTERMEDIATE_WRITING"
    show-pronunciation-feedback="false"
    show-simple-corrective-feedback="false"
    sound-effects-enabled="false"
    additional-corrective-feedback="false"
    always-wait-for-bot-to-finish-speaking="false"
    enable-contextualized-grammar-corrections="false"
    do-additional-pronunciation-analysis="false"
  ></linguineo-conversation>
</div>

Zorg ervoor dat je het access-token na het aanmelden dynamisch bijwerkt via JavaScript (zie het voorbeeld in de eerste stap).

๐Ÿ›Ž๏ธ 4. Luisteren naar het event linguineo:end

Je kunt luisteren naar het moment waarop een gebruiker een gesprek afrondt:

window.addEventListener('linguineo:end', (exerciseResult) => {
  console.log('Conversation finished', exerciseResult.detail);
  // Handle end-of-conversation logic here
});

Het object exerciseResult heeft de volgende eigenschappen:

percentage: number;
needsManualEvaluation: boolean;
pointsAwarded: number;
durationInMs?: number;
taskResultInfos?: TaskResultInfo[];
purpose: string;
conversationId?: number;
exerciseSessionId?: string;

๐Ÿงช Optioneel: integratie in React & Angular

De Linguineo-speler integreert vlot in moderne frameworks zoals React en Angular. Je kunt het access-token doorgeven als prop (React) of input (Angular), en event listeners zoals linguineo:end koppelen in de logica van je component.

Volledig werkende voorbeelden, inclusief het beheer en vernieuwen van tokens, vind je in onze GitHub-repository:
๐Ÿ‘‰ Linguineo Conversation Client Usage Example
Je vindt er volledige opstellingen voor gewoon JavaScript, React en Angular.

โœ… Conclusie

Je hebt nu een volledig werkende conversationele AI-component in je LMS! Denk er in productie aan om:

Vragen of hulp nodig bij de installatie? Neem contact op met ons technisch team: we helpen je graag verder.