Pass Session Data to a Survey

What the Session Data Schema Does

Your embed supplies the object. Defining a dashboard schema makes Session Data required for that survey. The schema declares the complete set of keys and whether each value is a string, number, or boolean. It helps SenseFolks:

• 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 field must be present with the exact spelling and type. Missing, partial, extra, or incorrectly typed Session Data prevents the survey from loading.

Step 1: Define the Fields and Types

In the survey creation flow, enable Session Data. Add every property your embed will send on every load, using the exact spelling and value type used by your application.

Step 2: Assign Session Data to the Embed

After the custom element exists, assign the complete object to itssessionData JavaScript property, then set the survey key so the initial request includes the data. Do not put JSON in asession-data HTML attribute. HTML attributes are strings, so they cannot preserve typed numbers and booleans.

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

Assign Session Data and then the survey key in an effect so the initial survey request contains the complete object.

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 and assign Session Data before the survey key after mount. Watch the application values if the context 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>

In Angular, Svelte, and Astro, use the same rule: wait for the element's mount or client lifecycle, then assign the complete object toelement.sessionData before settingelement.surveyKey. The dashboard's Embedpanel generates a framework-specific example from your survey's schema.

Step 3: Reassign When Values Change

The component observes property assignment, not mutations inside the existing object. Create and assign a new object when Session Data changes.

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

A meaningful change can reset or reload the current survey, so assign the context before the person starts whenever possible.

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 required data produces SESSION_DATA_REQUIRED. Every other schema validation failure producesSESSION_DATA_SCHEMA_MISMATCH. In either case, the survey configuration is not returned and the survey does not render.

Treat Session Data as Untrusted Analytics Context

Session Data originates in browser code and can be changed by a visitor. Treat it as client-provided analytics context. Do not use it as proof of identity, permissions, billing status, or access rights, and do not pass secrets or sensitive credentials.