Oppsett og bruk av Amplitude

Hvordan får jeg tilgang til Amplitude

  1. Gå til https://account.activedirectory.windowsazure.com/r#/applications
skjermbilde av myapps og alternativet for å legge til self-service apps
  1. Trykk på ikonet som ser ut som 3 punktum -> ...
  2. Trykk på Add self-service apps
  3. Legg til appen som heter Amplitude
  4. Nå skal du ha tilgang via din NAV-epost på SSO. Logg inn på https://analytics.amplitude.com/nav

Hva bør vi logge

Produkt-team har frihet og ansvar for å bestemme hva dere skal logge og hvordan. Du kan lære av andre team også, og vi har et internt miljø for å hjelpe hverandre og dele. Se #amplitude på Slack.

NAV har en taksonomi som er under utvikling. Denne kan man både bruke eksempler fra og bidra til her: Amplitude taxonomy

Teamet har også ansvar for å vurdere sikkerheten i sin applikasjon og personvernet til brukerne. Ta kontakt i Slack på #tryggnok om dere trenger en ROS-analyse og PVK for dataene dere ønsker å lagre.

Hvordan installere Amplitude i din app og logge events

Om teamet ditt ikke bruker NAIS så ta kontakt i #amplitude-internal kanalen på slack så oppretter vi et unntak i reglene for vår proxy.

Team som bruker NAIS slipper å gjøre dette.

De fleste bruker amplitude-js pakken fra npm

Ta kontakt om dere trenger å bruke en annen pakke som HTTP APIet.

Apper på eksterne sider

Denne guiden gjelder apper på *nav.no som www.nav.no, arbeidsplassen.nav.no og andre eksterne domener.

Installér Amplitude med npm install amplitude-js

Lag en fil som heter amplitude.js i appen for å lagre innstillinger. Deretter kaller vi denne når vi skal logge events i kildekoden til appen.

Start Amplitude i ditt prosjekt slik

const amplitude = require('amplitude-js') : () => null;
export const initAmplitude = () => {
    if (amplitude) {
        amplitude.getInstance().init('default', '', {
            apiEndpoint: 'amplitude.nav.no/collect-auto',
            saveEvents: false,
            includeUtm: true,
            includeReferrer: true,
            platform: window.location.toString(),
        });
    }
};

Her henter vi amplitude-js biblioteket, setter opp innstillinger for logging og starter Amplitude-innsamleren med initAmplitude.

På endepunktet tar Amplitude-proxy over og sjekker om dataene kan sendes til Amplitude.com, og beriker de med noen data om hvilket team eier applikasjonen og dataene som sendes inn.

Du kan også eksportere din egen funksjon for å forkorte den vanlige loggefunksjonen, med mulighet for å berike alle event-data fra din app:

export function logAmplitudeEvent(eventName: string, eventData?: any): void {
    setTimeout(() => {
        try {
            if (amplitude) {
                amplitude.getInstance().logEvent(eventName, eventData);
            }
        } catch (error) {
            console.error(error);
        }
    }
}

Her får vi en gjenbrukbar funksjon logAmplitudeEvent for å logge events som er kortere enn varianten i dokumentasjonen til Amplitude.

Til sammenligning, her er den vanlige funksjonen logEvent:

amplitude.getInstance().logEvent(eventName, eventData);

Når du skal logge events

import { initAmplitude, logAmplitudeEvent } from "./amplitude.js";

// før du logger, husk å starte Amplitude
// initAmplitude

// logg at brukeren gjør noe relevant i et skjema for eksempel
function userSubmitAnswer() {
  // brukeren svarer på et spørsmål
  logAmplitudeEvent("navn på event", {
    mittFelt: "litt data",
  });
}

Datastrukturer i events

Amplitude tar imot fullstendige JSON-objekter med key-value pairs og arrays. For eksempel

logAmplitudeEvent("åpne sak", {
  app: "søknadsappen",
  team: "søknadsteamet",
});

Denne hendelsen vil hete "åpne sak" i Amplitude sitt GUI og du kan skille det fra andre apper og team som bruker samme navn på sitt event ved å filtrere på attributtene app og team.

I tillegg berikes sidevisning-eventet med URL, hostname og pagepath som attributter av proxyen. Dette lar dere finne data fra deres egen app og skille de fra andre team.

Om din app har komplekse bruksmønstre så kan arrays være en fin ting å ta med. For eksempel om brukere er i flere situasjoner, og når situasjonen endrer seg

logAmplitudeEvent("bruker oppdaterer status", {
  status: ["foreldrepenger", "jobbsøker"],
});

Her får vi både med oss at brukeren har foreldrepenger hos NAV og er jobbsøker. Amplitude logger også datoen for hendelsen i timestamp så vi kan spore endringer for grupper av brukere.

Dette kan være nyttig info å ha for å sammenligne om brukere i denne komplekse situasjonen har det vanskeligere når de bruker NAV-tjenester enn andre som har en enklere situasjon. For eksempel i traktanalyser der man sammenligner brukergrupper med mer enn én ytelse fra NAV med de som kun har én eller ingen fra før av.

Testing og feilsøking lokalt, i test og prod

Når du skal teste om dine events blir sendt til Amplitude via proxyen så har du flere måter å kontrollere med.

  • Sjekk kall i network-fanen i developer tools via nettleseren
  • Søk på device_id for din bruker i User Look-up i Amplitude GUI
  • Lage en graf i Amplitude med event_type for event du ser etter

Dataene blir videresendt til ulike prosjekter basert på app-ingress og URL. Du må huske å søke i riktig prosjekt for å finne dine data.

Amplitude prosjektEksempelBeskrivelse
NAV Default - Prodwww.nav.no familie.nav.noom dataene er fra produksjon
NAV Default - Testwww-q1.nav.noom dataene er fra testmiljøet i selvbetjeningssonen
NAV Default - Preprodom dataene er fra testmiljøet i GCP
NAV Default - Localhost - Testlocalhost:8088/dekoratorenom dataene er fra localhost

Når du tester lokalt så vil proxyen videresende data fra domenet localhost til Amplitude-prosjektet NAV Default - Localhost - Test.

Du kan teste om dataene når proxyen via developer tools i nettleseren. Gå til network-fanen og søk etter kall som heter collect-auto. Sjekk om kallene når endepunktet amplitude.nav.no/collect-auto og svarer med 200 OK.

skjermbilde av developer tools med 200 OK fra amplitude

Om du får en feilmelding så er det sannsynligvis en feil i innstillingene for oppsett av Amplitude og prosjektet du logger til.

Du kan også se hvilke data ble sendt til Amplitude ved å scrolle til form data.

Her er event_type-feltet navn på event som blir sendt inn. Bruk dette til å verifisere at du har sendt inn dine events slik du ønsket.

Når appen er i test- og prodmiljø så har du flere alternativer for å sjekke at dataene ble sendt inn riktig.

skjermbilde av developer tools med data for en sidevisning

Du kan også lage en graf og søke etter navn på event du har sendt inn for å se at de har blitt mottatt, eller søke på en bruker-ID.

For å lage en graf, logg inn på Amplitude og velg New > Chart > SegmentationSelect event for å søke på event-navn.

skjermbilde av å lage en graf i Amplitude ved å søke på event-navn

Du kan også bruke device_id fra payload for å finne ut hvor dataene endte opp i Amplitude. Denne bruker-IDen er knyttet til en cookie satt i nettleseren til sluttbrukeren.

Gå til User Look-up og søk på bruker-IDen. Bytt Amplitude-prosjekt til du finner dataene dine for bruker-IDen du har søkt på.

skjermbilde av oppslag i Amplitude via User lookup funksjonen

Apper på interne sider og saksbehandlingstjenester (Under arbeid)

Denne guiden gjelder apper på adeo.no som barnetrygd.nav.no og andre saksbehandlingstjenester.