Lumi Survey

Kartleggingsresultat

Etter kartleggingen bør du ha svar på disse — de styrer resten av integrasjonen:

Bruk disse funnene aktivt i de neste fasene — de bestemmer hvilke maler og konfigurasjoner som genereres.

Fase 2: Kravinnhenting

Før du genererer kode, avklar det som trengs. Bruk kartleggingen fra Fase 1 til å besvare så mye som mulig automatisk — spør bare utvikleren om det du ikke kan utlede.

Autentisering (detekter automatisk)

Les NAIS-manifestet fra Fase 1 og bestem auth-type:

Hvis auth-type er entydig, ikke spør — informer utvikleren om hva du fant: "Jeg ser at appen bruker TokenX. Bruker det for Lumi-integrasjonen."

Spør kun hvis det er tvetydig eller mangler.

Spørsmål 1: Type undersøkelse

Spør: "Hva slags tilbakemelding vil du samle inn?"

Presenter alternativer med anbefalinger:

Hvis utvikleren er usikker, anbefal Rating med emoji-variant — det er det mest utprøvde mønsteret i Nav.

Spørsmål 2: Oppfølgingsspørsmål (kun for Rating)

Hvis utvikleren valgte en rating-survey, spør: "Vil du ha et oppfølgingsspørsmål ved lav score? (anbefalt: ja — fritekstfelt ved score ≤ 2)"

Anbefaling: Ja — fritekst ved lav rating gir handlingsbar innsikt med minimal brukerbelastning. DEFAULT_SURVEY_RATING har dette innebygd.

For andre survey-typer (Discovery, Top Tasks, etc.) har de innebygde oppfølgingsspørsmål allerede — ikke spør.

Fase 3: Installasjon

3a. Konfigurer GitHub Packages-registry

Sjekk om .npmrc allerede har GitHub Packages-konfig. Hvis ikke:

@navikt:registry=https://npm.pkg.github.com

3b. Installer pakken

npm install @navikt/lumi-survey

Peer-avhengigheter (@navikt/ds-react, @navikt/ds-css) er vanligvis allerede installert i Nav-apper. Hvis ikke:

npm install @navikt/ds-react @navikt/ds-css

3c. Importer stiler

I appens globale stil-entry point (identifisert i Fase 1), sørg for denne importrekkefølgen:

import "@navikt/ds-css";                  // Må komme først
import "@navikt/lumi-survey/styles.css";  // Deretter lumi-survey

Viktig: @navikt/ds-css MÅ importeres før @navikt/lumi-survey/styles.css.

Fase 4: Survey-komponent

4a. Opprett survey-konfigurasjon

Lag en egen fil for survey-konfigurasjonen (f.eks. survey.ts eller lumiSurvey.ts). Bruk satisfies LumiSurveyConfig for typesikkerhet.

Guiding: Basert på survey-typen valgt i Fase 2, hjelp utvikleren med å bygge opp konfigurasjonen steg for steg. Tilpass spørsmålstekster til tjenesten — bruk norsk og vær konkret.

Rating-survey

import type { LumiSurveyConfig } from "@navikt/lumi-survey";

export const survey = {
  type: "rating",
  questions: [
    {
      id: "inntrykk",
      type: "rating",
      variant: "emoji",       // "emoji" | "thumbs" | "stars" | "nps"
      prompt: "Hva er ditt inntrykk av tjenesten?",
      required: true,
    },
    {
      id: "innspill",
      type: "text",
      prompt: "Har du noen kommentarer eller innspill?",
      maxLength: 1000,
      visibleIf: {
        field: "ANSWER",
        questionId: "inntrykk",
        operator: "EXISTS",
      },
    },
  ],
} satisfies LumiSurveyConfig;

Tilpass til tjenesten:

• Endre prompt-tekster til noe som passer appen (f.eks. "Hvordan var det å søke om sykepenger?")
• Juster visibleIf — vis oppfølging kun ved lav score (operator: "LT", value: 3) eller alltid (operator: "EXISTS")
• Legg til flere spørsmål ved behov (se spørsmålstyper under)

Discovery-survey

import type { LumiSurveyConfig } from "@navikt/lumi-survey";

export const survey = {
  type: "discovery",
  questions: [
    {
      id: "oppgave",
      type: "text",
      prompt: "Hva prøvde du å gjøre i dag?",
      maxLength: 500,
      required: true,
    },
    {
      id: "fullfort",
      type: "singleChoice",
      prompt: "Fikk du gjort det du kom for?",
      options: [
        { value: "ja", label: "Ja" },
        { value: "delvis", label: "Delvis" },
        { value: "nei", label: "Nei" },
      ],
      required: true,
    },
    {
      id: "blokkering",
      type: "text",
      prompt: "Hva hindret deg?",
      maxLength: 1000,
      visibleIf: {
        field: "ANSWER",
        questionId: "fullfort",
        operator: "EQ",
        value: "nei",
      },
    },
  ],
} satisfies LumiSurveyConfig;

Top Tasks-survey

import type { LumiSurveyConfig } from "@navikt/lumi-survey";

export const survey = {
  type: "topTasks",
  questions: [
    {
      id: "oppgave",
      type: "singleChoice",
      prompt: "Hva kom du hit for å gjøre?",
      options: [
        { value: "soke", label: "Søke om ytelse" },
        { value: "status", label: "Sjekke status på søknad" },
        { value: "dokument", label: "Sende inn dokumentasjon" },
        { value: "annet", label: "Annet" },
      ],
      randomize: true,
      required: true,
    },
    {
      id: "fullfort",
      type: "singleChoice",
      prompt: "Fikk du gjort det?",
      options: [
        { value: "ja", label: "Ja" },
        { value: "delvis", label: "Delvis" },
        { value: "nei", label: "Nei" },
      ],
      required: true,
    },
    {
      id: "blokkering",
      type: "text",
      prompt: "Hva hindret deg?",
      maxLength: 1000,
      visibleIf: {
        field: "ANSWER",
        questionId: "fullfort",
        operator: "NEQ",
        value: "ja",
      },
    },
  ],
} satisfies LumiSurveyConfig;

Task Priority-survey

import type { LumiSurveyConfig } from "@navikt/lumi-survey";

export const survey = {
  type: "taskPriority",
  questions: [
    {
      id: "viktigst",
      type: "multiChoice",
      variant: "checkbox",
      prompt: "Hvilke oppgaver er viktigst for deg? (velg inntil 5)",
      maxSelections: 5,
      randomize: true,
      options: [
        { value: "soke", label: "Søke om ytelse" },
        { value: "status", label: "Sjekke status" },
        { value: "dokument", label: "Sende dokumentasjon" },
        { value: "endring", label: "Melde endring" },
        { value: "utbetaling", label: "Se utbetalinger" },
        // Legg til 15-40 oppgaver for robust Long Neck-analyse
      ],
      required: true,
    },
  ],
} satisfies LumiSurveyConfig;

Anbefaling: Inkluder 20-50 oppgaver for god Long Neck-analyse. Bruk randomize: true for å unngå rekkefølgebias.

Tilgjengelige spørsmålstyper

Betinget visning med visibleIf

Vis spørsmål basert på tidligere svar:

4b. Implementer transporten

Transporten kobler widgeten til ditt backend-endepunkt:

import type { LumiSurveyTransport } from "@navikt/lumi-survey";

const transport: LumiSurveyTransport = {
  async submit(submission) {
    const response = await fetch("/api/lumi/feedback", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(submission.transportPayload),
    });
    if (!response.ok) {
      throw new Error(`Lumi feedback-innsending feilet: ${response.status}`);
    }
  },
};

4c. Render widgeten

import { LumiSurveyDock } from "@navikt/lumi-survey";
import { survey } from "./survey";

<LumiSurveyDock
  surveyId="<app-navn>-feedback"
  survey={survey}
  transport={transport}
/>

Velg en unik surveyId — bruk appnavnet som prefiks (f.eks. "sykepengesoknad-feedback", "modia-satisfaction"). Denne ID-en identifiserer surveyen i Lumi-dashboardet.

4d. Valgfritt: Kontekst-tags for segmentering

Send med metadata for å muliggjøre filtrering i Lumi-dashboardet:

<LumiSurveyDock
  surveyId="<app-navn>-feedback"
  survey={survey}
  transport={transport}
  context={{
    tags: {
      // Lav kardinalitet — disse blir filterdimensjoner i dashboardet
      feature: "new-ui",
      role: "employer",
    },
  }}
/>

Regler for kontekst:

• tags: Kun verdier med lav kardinalitet (A/B-testgrupper, roller, features)
• debug: Høy kardinalitet tillatt (sesjons-ID-er, request-ID-er)
• Aldri inkluder personopplysninger (personnummer, e-post, navn)

4e. Lagringsstrategi

For offentlige sider med Nav-dekoratøren (nav.no): standard consent-strategi fungerer automatisk.

For interne apper (Modia, admin-verktøy) uten dekoratøren:

<LumiSurveyDock
  behavior={{ storageStrategy: "localStorage" }}
  {...otherProps}
/>

Merk: localStorage brukes kun for ikke-sensitiv survey UX-state (f.eks. om brukeren har sett/lukket undersøkelsen). Aldri lagre tokens, PII eller sensitiv data i localStorage.

Fase 5: Backend-endepunkt

Se references/backend-transport.md for komplette backend-maler (Node.js og Kotlin).

Fase 6: NAIS-konfigurasjon

Se references/nais-konfigurasjon.md for NAIS-manifest og accessPolicy-oppsett.

Fase 7: Validering

Etter implementasjon, verifiser hele flyten:

• @navikt/lumi-survey installert og stiler importert (ds-css FØR lumi-survey)
• Aksel v8+ bekreftet (@navikt/ds-react ≥ 8.0.0)
• LumiSurveyDock rendres i appen med en unik surveyId
• Survey-konfigurasjon bruker satisfies LumiSurveyConfig
• Transport sin submit-funksjon kaller ditt backend-endepunkt
• Backend-endepunkt utveksler token og videresender til Lumi API via LUMI_FEEDBACK_PATH
• NAIS-manifest har LUMI_API_HOST, LUMI_AUDIENCE, LUMI_FEEDBACK_PATH og accessPolicy
• Auth-type og endepunkt matcher (TokenX → /api/tokenx/..., AzureAD → /api/azure/...)
• Inbound access-policy bestilt hos Team eSyfo
• Ingen personopplysninger i kontekst-tags
• Lagringsstrategi matcher app-type (consent for offentlige, localStorage for interne)
• Surveyen dukker opp i riktig Lumi-dashboard etter testinnsending (dev: https://lumi-dashboard.ansatt.dev.nav.no, prod: https://lumi-dashboard.ansatt.nav.no/)

Hurtigstart: Forhåndsdefinerte surveys

Hvis du bare vil komme raskt i gang uten skreddersøm, finnes det ferdige presets:

import { LumiSurveyDock, DEFAULT_SURVEY_RATING } from "@navikt/lumi-survey";

<LumiSurveyDock surveyId="<app-navn>-feedback" survey={DEFAULT_SURVEY_RATING} transport={transport} />

Anbefaling: Bruk presets kun for rask prototyping. For produksjon, lag en skreddersydd konfigurasjon (Fase 4a) med spørsmålstekster tilpasset tjenesten.

Avansert konfigurasjon

Se references/avansert-konfigurasjon.md for forgreningslogikk, events og øvrige avanserte tilpasninger.