Custom variables

Use the metadata option to attach arbitrary custom data to a survey response — a user ID, plan name, order value, or any other attribute you want to see alongside the response later. metadata is a flat object of string | number | boolean values.

metadata is accepted by both init() and open():

With init()

ftools('init', {
  surveyId: 'SURVEY_ID',
  publishableKey: 'API_KEY',
  metadata: {
    plan: 'pro',
    accountAgeDays: 42,
    isTrial: false
  }
});

With open()

When manually opening a popup survey, pass metadata at the moment you have the most context (e.g. right after a checkout completes):

ftools('open', 'SURVEY_ID', {
  metadata: {
    orderId: 'ord_123',
    orderValue: 89.99
  }
});

If both init() and a later open() call provide metadata, the open() call's metadata is the one attached to that response — the two are not merged.

Reserved key: page_url

page_url is reserved by the SDK. It is always set to the current page URL when the response is submitted, overwriting any value you pass in metadata.page_url — a warning is logged to the console if you do.

Type

type MetadataValue = string | number | boolean;
type Metadata = Record<string, MetadataValue>;

Nested objects and arrays are not supported — keep values flat.