Passing Session Data into a Survey Embed

Why Define a Schema?

The Session Data object is supplied by your embed code. Defining its schema in the SenseFolks dashboard declares which keys are accepted and whether each value is a string, number, or boolean. SenseFolks uses the schema to:

• reject unexpected keys, misspellings, 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.

Declared fields are optional on an individual response. For example, you can declare plan and betaUser while only sending plan for visitors whose beta status is unknown.

Step 1: Define the Object Shape

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

Step 2: Assign Session Data to the Embed

Assign the object to the web component's sessionData JavaScript property after the element exists. Do not put JSON in a session-data HTML attribute: attributes are strings and cannot preserve typed numbers and booleans.

HTML and JavaScript

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

<sf-fastpoll
  id="checkout-survey"
  survey-key="your-survey-uuid">
</sf-fastpoll>

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

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

React

Assign the property in an effect so the custom element has mounted.

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

type SurveyElement = HTMLElement & {
  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 };
  }, [plan, accountAgeDays, betaUser]);

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

Vue

Use a template ref and assign the property after mount. Watch the application values if the context can change.

<template>
  <sf-fastpoll
    ref="survey"
    survey-key="your-survey-uuid"
  ></sf-fastpoll>
</template>

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

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

const survey = ref<SurveyElement | null>(null);
const plan = ref('pro');

const updateSessionData = () => {
  if (survey.value) {
    survey.value.sessionData = { plan: plan.value };
  }
};

onMounted(updateSessionData);
watch(plan, updateSessionData);
</script>

In Angular, Svelte, and Astro, use the same rule: wait for the element's mount or client lifecycle, then assign an object to element.sessionData. The dashboard's Embed panel 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 an in-progress survey, so set the context before the respondent 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.
• Field names and casing must exactly match the dashboard schema.
• String values may contain up to 500 characters.

Use Session Data for Analysis, Not Authorization

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.