Datakontrakt

Datakontrakten definerer strukturen på payloaden som sendes fra Lumi Survey-widgeten til Lumi API.

Transport payload

Widgeten samler inn svar og sender en strukturert JSON-payload til backend. Payloaden har disse hoveddelene:

Felt	Påkrevd	Beskrivelse
schemaVersion	✅	Nåværende widget sender alltid 2. Backend godtar også 1 i en overgangsperiode mens eldre widget-versjoner fases ut
submittedAt	✅	ISO 8601 tidsstempel for innsending
surveyId	✅	Unik survey-identifikator
surveyType	✅	En av: "rating", "topTasks", "discovery", "taskPriority", "custom"
deduplicationKey	✅	Genereres av widgeten og gjør nytt forsøk etter transportfeil trygt
definition	✅	Alle spørsmålene i surveyen, også de som ikke er besvart
answers	✅	Strukturert array med svar (se under)
context	Anbefalt	Nettleser-/brukerkontekst for segmentering

Når skal du endre surveyId?

Bruk ny surveyId når du legger til, fjerner, endrer navn på eller endrer type/options for spørsmål. Da unngår du å blande ulike datastrukturer i samme analyse og 409-feil fra backend.

Deduplication

Du trenger ikke sette deduplicationKey selv når du bruker widgeten. Den samme nøkkelen brukes når en innsending feiler og brukeren prøver på nytt. Etter vellykket innsending, reset eller ny sidevisning får neste innsending en ny nøkkel.

Answers-arrayet

Hvert element i answers følger dette skjemaet:

interface TransportAnswer {
  fieldId: string;       // Unik spørsmåls-ID (f.eks. "task", "feedback")
  fieldType: string;     // En av: "RATING", "TEXT", "SINGLE_CHOICE", "MULTI_CHOICE"
  value: AnswerValue;    // Selve svaret
  question: {
    label: string;       // Spørsmålsteksten vist til bruker
    description?: string;
    options?: Array<{ id: string; label: string }>;  // Påkrevd for valg-typer (for label-oppslag)
  };
}

Svartyper

AnswerValue er en union med fire varianter:

// Fritekst
{ type: "text", text: "Veldig bra!" }

// Rating (tallverdi)
{ type: "rating", rating: 5, ratingVariant: "emoji", ratingScale: 5 }

// Enkeltvalg
{ type: "singleChoice", selectedOptionId: "opt_1" }

// Flervalg
{ type: "multiChoice", selectedOptionIds: ["opt_1", "opt_2"] }

Context-objektet

Widgeten samler automatisk nettleserkontekst og slår sammen med bruker-definert segmenteringsdata:

interface LumiContext {
  // Auto-samlet av widgeten
  deviceType?: DeviceType;   // "mobile" | "tablet" | "desktop"
  viewport?: { width: number; height: number };
  userAgent?: string;

  // Opt-in (krever collectLocation: true)
  url?: string;              // Gjeldende side-URL
  pathname?: string;         // URL pathname

  // Segmentering (LAV KARDINALITET → dashboard-grafer)
  tags?: Record<string, string | number | boolean>;

  // Debugging (HØY KARDINALITET → kun i detaljvisning)
  debug?: Record<string, unknown>;
}

Tags vs. debug

Felt	Kardinalitet	Bruksområde	Eksempel
tags	Lav (< 10 verdier)	Grafer, segmentering	{ abTest: "A", rolle: "arbeidsgiver" }
debug	Høy (OK)	Inspeksjon av enkeltinnslag	{ sessionId: "abc-123", behandlingId: "..." }

Ikke legg høy-kardinalitet i tags

Tags med mange unike verdier (f.eks. bruker-IDer) gir ubrukelige grafer i dashboardet. Bruk debug-feltet for slike verdier.

Survey-typer

Backend mapper surveyType-strenger til enums:

Widget-verdi	Backend-enum
"rating"	SurveyType.RATING
"topTasks"	SurveyType.TOP_TASKS
"discovery"	SurveyType.DISCOVERY
"taskPriority"	SurveyType.TASK_PRIORITY
Alt annet	SurveyType.CUSTOM

Komplett eksempel

{
  "schemaVersion": 2,
  "submittedAt": "2024-12-03T14:22:00.000Z",
  "surveyId": "sykepenger-rating",
  "surveyType": "rating",
  "deduplicationKey": "retryable-submit:sykepenger-rating:abc123",
  "definition": {
    "surveyType": "rating",
    "fields": [
      {
        "fieldId": "rating",
        "fieldType": "RATING",
        "ratingVariant": "emoji",
        "ratingScale": 5
      },
      {
        "fieldId": "feedback",
        "fieldType": "TEXT"
      }
    ]
  },
  "context": {
    "url": "https://nav.no/sykepenger",
    "pathname": "/sykepenger",
    "deviceType": "mobile",
    "tags": {
      "abTest": "A",
      "rolle": "bruker"
    }
  },
  "answers": [
    {
      "fieldId": "rating",
      "fieldType": "RATING",
      "question": { "label": "Hvordan var opplevelsen din?" },
      "value": {
        "type": "rating",
        "rating": 4,
        "ratingVariant": "emoji",
        "ratingScale": 5
      }
    },
    {
      "fieldId": "feedback",
      "fieldType": "TEXT",
      "question": { "label": "Har du andre tilbakemeldinger?" },
      "value": { "type": "text", "text": "Veldig bra!" }
    }
  ]
}

Se også

• API-endepunkter — endepunktene som mottar denne payloaden
• Context & tags — hvordan du konfigurerer context i widgeten