Pass Session Data to a Survey

How does the Session Data schema work?

Define a Session Data schema in the dashboard, then supply matching values from your embed. The schema checks:

• reject unexpected keys, spelling mistakes, and incorrect value types;
• keep a field's meaning and type stable across responses;
• make filtering, analysis, and exports consistent; and
• prevent Session Data names from colliding with Survey Fields.

Every declared key must be present with the exact spelling and type. Missing, extra, or mistyped fields block loading.

1. Define the Fields and Types

Enable Session Data during survey creation. Add the keys and types your embed will send on every load.

2. Assign Session Data to the Embed

Assign the complete object to element.sessionData before setting the survey key. Use a JavaScript property; a session-data attribute cannot preserve value types.

HTML and JavaScript

<script type="module" src="https://unpkg.com/@sensefolks/fastpoll"></script>

<sf-fastpoll id="checkout-survey"></sf-fastpoll>

<script type="module">
  await customElements.whenDefined('sf-fastpoll');

  const survey = document.querySelector('#checkout-survey');
  survey.sessionData = {
    plan: 'pro',
    accountAgeDays: 120,
    betaUser: true
  };
  survey.surveyKey = 'your-survey-uuid';
</script>

React

Set Session Data before the key in a mount effect:

import '@sensefolks/fastpoll';
import { useEffect } from 'react';

type SurveyElement = HTMLElement & {
  surveyKey: string;
  sessionData: Record<string, string | number | boolean>;
};

export function CheckoutSurvey({ plan, accountAgeDays, betaUser }) {
  useEffect(() => {
    const survey = document.querySelector<SurveyElement>('#checkout-survey');
    if (!survey) return;

    survey.sessionData = { plan, accountAgeDays, betaUser };
    survey.surveyKey = 'your-survey-uuid';
  }, [plan, accountAgeDays, betaUser]);

  return (
    <sf-fastpoll
      id="checkout-survey"
    ></sf-fastpoll>
  );
}

Vue

Use a template ref after mount. Watch values that can change:

<template>
  <sf-fastpoll
    ref="survey"
  ></sf-fastpoll>
</template>

<script setup lang="ts">
import '@sensefolks/fastpoll';
import { onMounted, ref, watch } from 'vue';

type SurveyElement = HTMLElement & {
  surveyKey: string;
  sessionData: Record<string, string | number | boolean>;
};

const survey = ref<SurveyElement | null>(null);
const plan = ref('pro');
const accountAgeDays = ref(120);
const betaUser = ref(true);

const updateSessionData = () => {
  if (survey.value) {
    survey.value.sessionData = {
      plan: plan.value,
      accountAgeDays: accountAgeDays.value,
      betaUser: betaUser.value
    };
    survey.value.surveyKey = 'your-survey-uuid';
  }
};

onMounted(updateSessionData);
watch([plan, accountAgeDays, betaUser], updateSessionData);
</script>

Use the same order in Angular, Svelte, and Astro: mount the element, set sessionData, then set surveyKey. The dashboard's Embed panel generates examples for your schema.

3. Reassign When Values Change

Assign a new object when values change. Mutating the existing object does not trigger an update.

// Reassign a new object so the component detects the change.
survey.sessionData = {
  ...survey.sessionData,
  plan: 'enterprise'
};

Updates can reset the survey. Set context before the respondent starts.

Validation Rules

• The value must be a plain, one-level object.
• Values may be strings, finite numbers, or booleans.
• Nested objects, arrays, null, and undefined are not supported.
• Use no more than 20 fields.
• Field names must start with a letter and contain only letters, numbers, or underscores.
• When a schema is defined, all keys and types must match it exactly; missing, partial, and extra fields are rejected.
• When no schema is defined, safe Session Data is accepted and stored without schema matching.
• String values may contain up to 500 characters.
• NUL and other non-printing control bytes are rejected.

Missing data returns SESSION_DATA_REQUIRED; other schema failures return SESSION_DATA_SCHEMA_MISMATCH. Both prevent loading.

Can I trust Session Data?

Visitors can alter browser-supplied data. Use Session Data for analytics, never for access control or proof of identity. Do not include credentials.