Documentatie

Actualign-overzicht

Deze documentatie beschrijft Actualign van begin tot eind: een account en project maken, de meetcode installeren, een waardeafspraak maken, resultaten begrijpen, privacygrenzen bewaken en technische koppelingen gebruiken.

Actualign heeft daarnaast drie verschillende technische ingangen. Gebruik de meetcode of opname-API om gebeurtenissen te schrijven, de lees-API om één project uit te lezen en de MCP-koppelingen om een AI-assistent te laten helpen.

Wil je eerst begrijpen wat Actualign meet, wat de resultaten betekenen en welke privacygrenzen gelden, lees dan **Wat Actualign meet en laat zien**.

Adressen

• POST /api/v1/events neemt metingen op met een hm_ing_...-sleutel.
• GET /api/v1/screens en GET /api/v1/heatmap lezen metingen met een hm_read_...-sleutel.
• GET /api/v1/visits leest tijdelijke anonieme bezoeken van maximaal zeven dagen met een hm_read_...-sleutel.
• /mcp laat een AI-assistent na aanmelden één gekozen project lezen.
• /mcp/docs is openbaar en kent alleen deze gepubliceerde documentatie.

De opname- en leessleutel zijn niet uitwisselbaar. De openbare documentatie-MCP kan geen projectgegevens lezen.

Wat Actualign meet en laat zien

Actualign laat zien hoe mensen een website of webapp gebruiken op mobiel, tablet en desktop. De dienst voegt metingen van meerdere bezoeken samen en kan gebeurtenissen maximaal zeven dagen binnen één tijdelijk anoniem bezoek verbinden. Zo zie je patronen en routes zonder een herkenbare persoon of sessieopname.

Tijdelijke anonieme bezoeken

Tijdens één bezoek kan Actualign paginaweergaven, klikken op vaste elementen en scrollbereik met elkaar verbinden. Daardoor zie je welke routes worden gevolgd en waar een bezoek eindigt. Een bezoekcode geldt alleen in één browsertabblad, verloopt na dertig minuten zonder activiteit en herkent dezelfde persoon bij een later bezoek niet.

Wat wordt gemeten

Paginaweergaven

Actualign telt iedere gemeten weergave van een pagina of scherm. Een paginaweergave is geen unieke bezoeker. Dezelfde persoon kan een pagina meerdere keren bekijken.

Klikken en tikken

Bij een klik of tik bewaart Actualign de positie als verhouding van de pagina en het zichtbare scherm. Daardoor kunnen metingen van verschillende schermformaten samen worden weergegeven. De heatmap laat zien waar veel en weinig interactie plaatsvindt.

Een klik bewijst niet waarom iemand klikte. Een drukke plek kan zowel interesse als verwarring betekenen.

Scrollbereik

Actualign legt vast of iemand 25%, 50%, 75% of 100% van de pagina bereikt. Zo kun je zien hoeveel gemeten paginaweergaven belangrijke inhoud lager op de pagina bereikten.

Apparaat en scherm

Elke meting bevat de apparaatklasse, mobiel, tablet of desktop, plus de afmetingen en oriëntatie van het browservenster. Daardoor kun je het gedrag per schermcategorie vergelijken.

Herkenbare elementen

Een knop, link of ander belangrijk onderdeel kan een vaste data-heatmap-id krijgen. Daarmee blijft het element herkenbaar wanneer de positie of vormgeving verandert.

Pagina-, scherm- en ontwerpversie

Actualign onderscheidt pagina's en routes van webapps. Ook een schermtoestand of ontwerpversie kan worden meegestuurd. Zo kun je metingen van verschillende varianten uit elkaar houden.

Wat je ermee kunt onderzoeken

Met de metingen kun je onder meer onderzoeken:

• of de belangrijkste actie wordt aangeklikt;
• of bezoekers belangrijke informatie onderaan bereiken;
• of niet-klikbare onderdelen toch vaak worden aangeklikt;
• of mobiel, tablet en desktop verschillend worden gebruikt;
• of een gewijzigde pagina andere patronen laat zien;
• welke pagina, route of ontwerpversie aandacht nodig heeft.

De uitkomst is een aanwijzing voor nader onderzoek of een ontwerpaanpassing. Actualign bewijst geen oorzaak en vertelt niet automatisch wat een bezoeker dacht.

Wat Actualign niet meet

De tracker verzamelt geen ingevulde tekst, formulierwaarden, e-mailadressen, IP-adressen, cookies of blijvende bezoeker-ID's. Invoervelden, bewerkbare tekst en elementen met data-heatmap-private worden niet als klikdoel gemeten.

Actualign maakt geen sessieopnamen en volgt geen herkenbare persoon. De huidige versie meet ook geen muisbewegingen of zweefgedrag. Tijdelijke bezoekverbanden verdwijnen na maximaal zeven dagen; daarna blijven alleen losse gebeurtenissen voor samengevoegde patronen over.

Resultaten bekijken en gebruiken

In het Actualign-dashboard kun je een pagina, apparaatklasse, periode en weergave kiezen. De lees-API en de project-MCP kunnen dezelfde samengevoegde projectgegevens veilig beschikbaar maken voor een eigen dashboard of AI-assistent.

Gebruik de pagina- en schermlijst om eerst de juiste pagina of ontwerpversie te kiezen. Lees daarna de klikpunten en het scrollbereik voor die selectie.

Een waardeafspraak maken

Een waardeafspraak verbindt drie dingen: wat een pagina, boodschap of route voor iemand moet betekenen, welk resultaat voor de organisatie telt en bij welke meetbare grens je van succes spreekt.

Open in Projectbeheer een project en vul de drie stappen in:

1. **Belofte:** wat moet iemand na deze pagina begrijpen, voelen of kunnen doen? 2. **Doel van de organisatie:** waarom is die verandering waardevol? 3. **Succescriterium:** welk gemeten cijfer en welke grens bepalen of de afspraak wordt gehaald?

De gratis basis bevat één actieve waardeafspraak per project. Een aangepaste meetinhoud, doelwaarde of meetperiode begint opnieuw vanaf de dag van de wijziging.

Beschikbare succescriteria

De eerste versie gebruikt metingen die Actualign al verzamelt:

• aantal paginaweergaven;
• aantal klikken op een element met data-heatmap-id;
• het aantal klikken op zo'n element per 100 paginaweergaven;
• het percentage paginaweergaven dat een gekozen scrollgrens bereikt.

Registraties, verkopen, omzet en advertentiekosten zijn nog geen automatisch succescriterium. Daarvoor komt later een afzonderlijk resultaatevenement of een koppeling met de bron van dat resultaat.

De vier statussen

• **Nog onvoldoende gegevens:** het ingestelde minimum aantal paginaweergaven is nog niet bereikt.
• **Op koers:** het resultaat ligt dicht genoeg bij het afgesproken tempo of percentage.
• **Aandacht nodig:** het resultaat blijft achter bij de afspraak.
• **Doel bereikt:** de ingestelde doelwaarde is bereikt.

Een status is een aanwijzing, geen verklaring. Actualign kan bijvoorbeeld laten zien dat een knop te weinig wordt aangeklikt, maar bewijst niet waarom mensen dat doen. Gebruik de heatmap en bezoekroutes om mogelijke oorzaken te onderzoeken.

Van account naar meetcode

Deze stappen brengen een nieuwe gebruiker van een leeg account naar de eerste meting.

1. Maak een account

Open https://heatmap-tau-nine.vercel.app/registreren. Kies Doorgaan met Google of maak een account met naam, e-mailadres en een wachtwoord van minimaal acht tekens. Na het aanmelden kom je in Projectbeheer.

Heb je al een account, gebruik dan https://heatmap-tau-nine.vercel.app/inloggen.

2. Maak een project

Vul in Projectbeheer een herkenbare projectnaam en het websiteadres in. Gebruik het openbare adres met protocol, bijvoorbeeld https://voorbeeld.nl. Actualign bewaart de herkomst, dus protocol en domein moeten overeenkomen met de website waarop de meetcode komt.

Maak een afzonderlijk project voor iedere website of webapp die je afzonderlijk wilt meten.

3. Bewaar beide sleutels meteen

Na Project aanmaken toont Actualign twee geheime sleutels en de volledige installatiecode. Dit scherm is de enige keer dat de sleutels leesbaar worden getoond.

• De opnamesleutel begint met hm_ing_. Deze hoort uitsluitend in de meetcode op de website en kan geen metingen lezen.
• De leessleutel begint met hm_read_. Deze opent het losse dashboard of kan serverzijdig de lees-API gebruiken. Plaats hem nooit in openbare browsercode.

Bewaar de sleutels in een wachtwoordbeheerder of geheimenkluis. Deel ze niet in e-mail, chat, schermafbeeldingen, broncode of een openbare repository.

4. Plaats de installatiecode

Kopieer de installatiecode uit Projectbeheer naar alle pagina's van de website. De code bevat de juiste opnamesleutel. Plaats hem met defer in de head of vlak voor </body>.

5. Controleer de eerste meting

Open de website nadat de nieuwe versie is gepubliceerd, bezoek enkele pagina's, klik en scroll. Open daarna het Actualign-dashboard en gebruik de leessleutel wanneer daarom wordt gevraagd. Een nieuwe pagina verschijnt nadat de tracker ten minste een paginaweergave heeft opgeslagen.

6. Koppel eventueel een AI-assistent

Gebruik voor projectmetingen https://heatmap-tau-nine.vercel.app/mcp. Log in, kies precies één project en geef tijdelijke leestoegang. Hiervoor hoef je de leessleutel niet aan de assistent te geven.

Gebruik voor openbare uitleg https://heatmap-tau-nine.vercel.app/mcp/docs. Deze documentatiekoppeling heeft geen aanmelding en geen toegang tot projecten of metingen.

Sleutels en toegang

Ieder project krijgt twee gescheiden sleutels. De opnamesleutel begint met hm_ing_ en mag alleen gebeurtenissen toevoegen. De leessleutel begint met hm_read_ en mag alleen samengevoegde metingen van dat ene project lezen.

Beide sleutels en de volledige installatiecode verschijnen direct na het aanmaken van een project in Projectbeheer. Ze zijn daar eenmalig leesbaar. Bewaar ze daarom meteen in een wachtwoordbeheerder of geheimenkluis.

HTTP-API

Plaats de opnamesleutel in het JSON-veld key van de gebeurtenissenaanvraag. Stuur de leessleutel alleen als Authorization: Bearer hm_read_.... Zet een leessleutel nooit in browsercode of een openbare repository.

AI-koppeling

Voor /mcp hoeft een gebruiker geen sleutel te kopiëren. De browseraanmelding laat de gebruiker één project kiezen en geeft de assistent tijdelijke leestoegang. /mcp/docs is openbaar, omdat die server uitsluitend gepubliceerde uitleg bevat.

Meetcode installeren

Plaats het script één keer in de HTML van alle pagina's, bij voorkeur vlak voor </body> of met defer in de head.

De complete code met de echte opnamesleutel verschijnt direct nadat je in Projectbeheer een project hebt aangemaakt. Zie **Van account naar meetcode** voor de volledige route.

<script defer
  src="https://heatmap-tau-nine.vercel.app/tracker.js"
  data-heatmap-key="hm_ing_JOUW_OPNAMESLEUTEL"></script>

De tracker herkent gewone paginawisselingen en routewisselingen in webapps. Geef belangrijke knoppen of links eventueel een vaste code:

<button data-heatmap-id="account-aanmaken">Account aanmaken</button>

Een nieuwe grote ontwerpvariant kan op het html-element een eigen data-heatmap-version krijgen. Actualign mengt dan geen posities van verschillende ontwerpen.

Gebeurtenissen opnemen

POST /api/v1/events accepteert per aanvraag één tot twintig gebeurtenissen. De aanvraag moet afkomstig zijn van het websiteadres dat bij het project is vastgelegd en mag maximaal 24 kB groot zijn.

{
  "key": "hm_ing_JOUW_OPNAMESLEUTEL",
  "events": [{
    "screenId": "/aanmelden",
    "screenVersion": "1",
    "stateId": "default",
    "type": "click",
    "device": "mobile",
    "orientation": "portrait",
    "viewportWidth": 390,
    "viewportHeight": 844,
    "xRatio": 0.52,
    "yRatio": 0.31,
    "elementId": "account-aanmaken",
    "visitId": "123e4567-e89b-42d3-a456-426614174000",
    "visitSequence": 4,
    "occurredAt": "2026-10-23T08:30:00.000Z"
  }]
}

Een succesvolle aanvraag geeft status 204. Klikposities zijn verhoudingen van 0 tot 1. Scrollgebeurtenissen gebruiken alleen scrollDepth met 25, 50, 75 of 100. Een paginaweergave heeft geen klikpositie of scrollgrens.

visitId en visitSequence zijn samen optioneel voor eigen API-koppelingen. De officiële tracker vult ze automatisch met een willekeurige code per bezoek en een oplopend volgnummer. Een bezoek eindigt na dertig minuten zonder activiteit. De server bewaart niet de aangeleverde code maar een projectgebonden hash en verwijdert de bezoekkoppeling na maximaal zeven dagen.

Gemeten schermen lezen

GET /api/v1/screens geeft de gemeten pagina's en ontwerpversies van één project terug. Gebruik een leessleutel in de Authorization-header.

curl https://heatmap-tau-nine.vercel.app/api/v1/screens \
  -H 'Authorization: Bearer hm_read_JOUW_LEESSLEUTEL'

Iedere schermregel bevat screen_id, screen_version, views en last_seen. Gebruik een screen_id uit dit antwoord als selectie voor de heatmap-API.

Heatmapgegevens lezen

GET /api/v1/heatmap leest de samengevoegde metingen voor één pagina, apparaatklasse en periode.

curl 'https://heatmap-tau-nine.vercel.app/api/v1/heatmap?screenId=%2Faanmelden&device=mobile&days=30' \
  -H 'Authorization: Bearer hm_read_JOUW_LEESSLEUTEL'

device is mobile, tablet of desktop. days is een geheel getal van 1 tot en met 90. Het antwoord bevat views, klikgebieden met posities tussen 0 en 1 en aantallen per scrollgrens. Dit zijn samengevoegde gebeurtenissen, geen unieke personen of sessieopnamen.

Tijdelijke anonieme bezoeken lezen

GET /api/v1/visits verbindt gebeurtenissen tijdelijk tot één anoniem bezoek. Hierdoor kun je zien welke pagina's achter elkaar werden bekeken, hoeveel keer er per pagina werd geklikt, welke vaste elementen werden gebruikt en hoe ver er werd gescrold.

Wat een bezoek betekent

De tracker maakt in één browsertabblad een willekeurige bezoekcode. Na dertig minuten zonder activiteit begint een nieuw bezoek. De code bevat geen naam, e-mailadres, accountnummer of blijvende browseridentiteit en wordt niet in een cookie geplaatst.

Een bezoek is daarom geen herkenbare persoon. Dezelfde persoon krijgt bij een later bezoek een nieuwe code. Bezoeken uit verschillende tabbladen worden niet samengevoegd.

Aanvraag

Gebruik een leessleutel als bearer-token. days mag 1 tot en met 7 zijn, limit 1 tot en met 50. Met device kun je optioneel filteren op mobile, tablet of desktop.

GET /api/v1/visits?days=7&limit=20&device=mobile
Authorization: Bearer hm_read_JOUW_LEESSLEUTEL

Antwoord

Het antwoord bevat een algemene samenvatting en recente bezoeken. Per bezoek worden alleen een tijdelijke verkorte code, op minuten afgeronde begin- en eindtijd, apparaatklasse en samengevat gedrag per pagina teruggegeven. Klikposities worden niet per bezoek teruggegeven. Die blijven alleen in de samengevoegde heatmap beschikbaar.

{
  "days": 7,
  "retentionDays": 7,
  "summary": {
    "visits": 12,
    "multiScreenVisits": 5,
    "averageScreensPerVisit": 1.8
  },
  "visits": [{
    "id": "a4d29fe810c3",
    "device": "mobile",
    "screenCount": 2,
    "eventCount": 9,
    "screens": [{
      "screenId": "/",
      "screenVersion": "1",
      "clicks": 2,
      "clickedElements": ["account-aanmaken"],
      "maxScroll": 75
    }]
  }]
}

Bewaartermijn

De koppeling tussen gebeurtenissen en een bezoek wordt na maximaal zeven dagen dagelijks verwijderd. De losse gebeurtenissen blijven zonder bezoekkoppeling maximaal negentig dagen beschikbaar voor samengevoegde heatmaps.

AI en MCP

Actualign biedt twee MCP-servers met een verschillende grens.

Projectmetingen

Verbind https://heatmap-tau-nine.vercel.app/mcp. De gebruiker meldt zich aan, kiest één project en geeft tijdelijke leestoegang. Deze server kan projectmetingen lezen maar niets wijzigen. Naast schermen, klikpunten en scrollbereik kan hij tijdelijke anonieme bezoeken samenvatten en recente routes met aantallen klikken, vaste elementen en maximale scrollgrenzen lezen. Hij krijgt geen herkenbare personen of sessieopnamen.

Documentatie

Verbind https://heatmap-tau-nine.vercel.app/mcp/docs. Deze openbare server kan documenten zoeken, een document openen, relaties volgen en een API-eindpunt verklaren. De standaardfuncties search en fetch geven ChatGPT citeerbare bronnen. Hij heeft geen projectaanmelding, databaseverbinding of toegang tot broncode.

Een assistent hoort alleen uitspraken te doen die door een teruggegeven document of het OpenAPI-contract worden ondersteund. Ontbreekt het antwoord, dan is de juiste conclusie dat het niet in de gepubliceerde documentatie staat.

Eigen dashboard bouwen

Bewaar de leessleutel uitsluitend op de server van je eigen toepassing. Vraag eerst /api/v1/screens op, laat de gebruiker een screen_id kiezen en vraag daarna /api/v1/heatmap op met pagina, apparaat en periode.

Geef de leessleutel nooit door aan browser-JavaScript. Laat je eigen server alleen de gegevens teruggeven die het scherm nodig heeft. Houd rekening met lege perioden en met een screenVersion die null kan zijn wanneer nog geen meting bestaat.

Foutcodes

• 400: de JSON, selectie of gebeurtenis is ongeldig.
• 401: een leessleutel of aanmelding ontbreekt.
• 403: de sleutel heeft geen toegang of het websiteadres komt niet overeen.
• 413: de gebeurtenissenaanvraag is groter dan 24 kB.
• 503: opslag of metingen zijn tijdelijk niet beschikbaar.

Controleer bij 403 voor opname eerst of het exacte protocol en domein overeenkomen met het ingestelde websiteadres. Toon geheime sleutels nooit in foutmeldingen of logboeken.

Privacy en gegevensgrenzen

Actualign bewaart posities, schermkenmerken, scrollgrenzen en optionele vaste elementcodes. Gebeurtenissen binnen één bezoek kunnen tijdelijk worden verbonden met een willekeurige bezoekcode. Die code staat alleen in het tabbladgeheugen, verloopt na dertig minuten zonder activiteit en wordt op de server projectgebonden gehasht.

De tracker verzamelt geen tekstinvoer, formulierwaarden, e-mailadressen, IP-adressen, cookies of blijvende bezoeker-ID's. Dezelfde persoon wordt bij een later bezoek niet herkend en bezoeken uit verschillende tabbladen worden niet samengevoegd.

Formuliervelden, invoervelden, bewerkbare tekst en elementen met data-heatmap-private worden niet als klikdoel gemeten. De cijfers zijn samengevoegde gebeurtenissen. Een weergave is niet automatisch een unieke persoon en een klik bewijst geen bedoeling.

De bezoekkoppeling wordt na maximaal zeven dagen dagelijks verwijderd. Losse gebeurtenissen blijven daarna zonder bezoekverband maximaal negentig dagen beschikbaar voor samengevoegde heatmaps. Actualign maakt geen sessieopnamen en geeft geen klikposities per bezoek terug.