Agreli
Probeer gratis
Docs / Inbedden en terugsturen

Inbedden en terugsturen

Standaard stuur je de medewerker naar de hosted_url, op het domein van Agreli. Je kunt de onboarding ook in je eigen site tonen met embed.js, en de medewerker na afloop terugsturen naar je eigen app met return_url. Voor allebei moet je domein op de lijst met toegestane domeinen staan.

MarkdownOpenAPI

Toegestane domeinen

Een eigenaar of manager zet de domeinen in het developer dashboard, onder Toegestane domeinen. Je kunt ze niet met een API-sleutel wijzigen. Zo kan iemand met een gelekte sleutel medewerkers niet naar een eigen pagina in de huisstijl van de werkgever sturen.

  • Eén domein per regel, met https://, zoals https://app.jouwapp.nl. Een pad laten we weg. Jokertekens kunnen niet: noem elk subdomein apart. Hooguit 20 domeinen.
  • De sandbox volgt de lijst van de organisatie zelf.
  • Bij een softwarepartner tellen twee lijsten: die van de werkgever en die van de partner. Een partner zet zijn eigen domeinen één keer en kan ze dan gebruiken voor elke werkgever die hem toelaat.
  • GET /v1/organization geeft de lijst terug in allowed_origins.

Terugsturen met return_url

Geef bij het aanmaken options.return_url mee. Na het versturen toont de statuspagina een knop terug naar dat adres.

JSON
{ "options": { "return_url": "https://app.jouwapp.nl/onboarding/klaar?sollicitant=4711" } }
  • Alleen https, op een toegestaan domein. Anders krijg je 422 return_url_not_allowed (geen toegestaan domein) of 422 return_url_invalid (geen https-adres).
  • Zet geen persoonsgegevens in het adres; een eigen kenmerk zoals een sollicitant-id kan wel.

De onboarding in je eigen site

Laad embed.js en geef het de hosted_url uit POST /v1/onboardings. Het script maakt een iframe die meegroeit met de inhoud.

html
<div id="onboarding"></div>
<script src="https://app.agreli.nl/embed.js"></script>
<script>
  const onboarding = Agreli.mount("#onboarding", {
    url: hostedUrl, // hosted_url uit POST /v1/onboardings
    onEvent: (e) => {
      if (e.type === "submitted") toonBedankt();
      if (e.type === "status") console.log("Stand:", e.state);
    },
  });
  // Later weghalen: onboarding.destroy();
</script>

De iframe werkt alleen op een toegestaan domein. Op elke andere site weigert de browser hem; daarvoor zet Agreli per link de kop Content-Security-Policy: frame-ancestors met jouw domeinen.

Berichten aan je pagina

onEvent krijgt berichten met source: "agreli" en een type. Ze bevatten nooit persoonsgegevens.

typeWanneerExtra
readyDe pagina is geladen.
resizeDe hoogte van de inhoud verandert. embed.js past de iframe zelf aan.height
verifiedDe medewerker heeft de eenmalige code bevestigd.
submittedDe medewerker heeft de gegevens verstuurd.
signedDe medewerker heeft het contract getekend.
statusDe stand van de onboarding, bij elke wijziging.state
returnDe medewerker klikt op de knop terug naar je return_url. De hele pagina gaat daarheen, niet alleen de iframe.return_url
closedDe medewerker sluit af.

Vertrouw voor je administratie niet op deze berichten: ze komen uit de browser. Gebruik webhooks of GET /v1/onboardings/{id} voor de echte stand.

Goed om te weten

  • Inloggen. Ook ingebed bevestigt de medewerker met een eenmalige code. Omdat browsers cookies van een ander domein in een iframe vaak blokkeren, onthoudt de pagina de sessie alleen zolang de iframe open is. Na herladen vraagt de medewerker een nieuwe code.
  • Camera. embed.js geeft de iframe toestemming voor de camera, voor de scan van het identiteitsbewijs. Zet je zelf een Permissions-Policy, sta dan camera toe voor https://app.agreli.nl.
  • Je eigen CSP. Heeft je site een Content-Security-Policy, voeg dan https://app.agreli.nl toe aan script-src (voor embed.js) en aan frame-src.
  • Zonder script. Een eigen iframe kan ook: https://app.agreli.nl/m/…?embed=1&origin=https://app.jouwapp.nl, met allow="camera". Berichten komen dan als postMessage binnen. Controleer altijd dat event.origin gelijk is aan https://app.agreli.nl.
  • Huisstijl. De pagina toont het logo en de kleur van de werkgever, ook ingebed.