*feedback.tools
Sign InFree setup helpGet started
Jump to

Introduction

InitializationCustom variablesEventsMethods
  2. Docs
  3. SDK
  4. SDK: Initialization

SDK: Initialization

ftools('init', options)

Initializes a survey. Asynchronous — returns a Promise, but the call itself can be made before the SDK script loads (it will be queued and replayed once ready).

ftools('init', { surveyId: '__SURVEY_ID__', publishableKey: '__PUBLISHABLE_KEY__' });
ftools('init', { surveyId: '__SURVEY_ID__', publishableKey: '__PUBLISHABLE_KEY__', root: '#container' });

Parameters

Comparison table
ParameterTypeDescription
options.surveyIdstringSurvey ID from the dashboard.
options.publishableKeystringPublishable API key (pk_...) from the dashboard.
options.rootstring | HTMLElementContainer for embed mode — a CSS selector or an element reference. Omit for popup mode.
options.metadataobjectCustom data attached to the survey response. See Custom variables.
options.channelstringOverride the channel (web-popup, web-inline, ...). Defaults to web-popup, or web-inline when root is set.
options.userIdstringOptional identifier for the current user, attached to the session.
options.userEmailstringOptional email for the current user, attached to the session.

userId/userEmail identify the respondent on the session — separate from metadata, which is attached to the response instead:

ftools('init', {
  surveyId: '__SURVEY_ID__',
  publishableKey: '__PUBLISHABLE_KEY__',
  userId: 'user_123',
  userEmail: 'jane@example.com'
});
  • A known userEmail skips the survey's contact-collection screen, if enabled. A known userId alone does not.
  • If the survey doesn't allow multiple responses, a known userId is used to recognize a returning respondent across sessions (a fresh page load gets a new session, but the same userId is still recognized); without it, the check is limited to the current session.
  • Both are read once, at init() time — there's no separate command to attach them to a session afterward.
ftools('init', {
  surveyId: '__SURVEY_ID__',
  publishableKey: '__PUBLISHABLE_KEY__'
});

The survey shows automatically based on the triggers configured in the dashboard, or manually via open().

Embed mode

Pass root to render the survey inline inside a container you provide:

// CSS selector
ftools('init', {
  surveyId: '__SURVEY_ID__',
  publishableKey: '__PUBLISHABLE_KEY__',
  root: '#my-container'
});

// HTMLElement reference
ftools('init', {
  surveyId: '__SURVEY_ID__',
  publishableKey: '__PUBLISHABLE_KEY__',
  root: document.getElementById('my-container')
});

root accepts either a CSS selector string or a direct HTMLElement reference. Use an element reference if the container lives inside a Shadow DOM — document.querySelector cannot traverse into Shadow DOM from the main document.

See Survey modes for the full behavior differences between popup and embed.

On this page
ftools('init', options)ParametersPopup modeEmbed mode