API Reference

Complete reference for all SDK methods, options, and events.

Configuration Options

Pass these options to FitSignal.init().

Option	Type	Default	Description
apiKey	string	required	Your API key from the dashboard (starts with `fs_live_` or `fs_test_`)
apiUrl	string	`https://www.fitsignal.com/api/widget`	Custom API URL (for self-hosted or testing)
surveyId	string	—	Specific survey ID to show. If omitted, shows the first eligible survey.
position	string	`bottom-right`	Widget position: `bottom-right`, `bottom-left`, or `center`
zIndex	number	`9999`	CSS z-index for the widget container
debug	boolean	`false`	Enable debug logging to the console

Example

FitSignal.init({
  apiKey: 'fs_live_abc123',
  surveyId: 'surv_xyz789',      // optional
  position: 'bottom-right',     // optional
  zIndex: 10000,                // optional
  debug: true                   // optional
});

Methods

`FitSignal.init(options)`

Initialize the SDK. Must be called before any other methods.

Parameters

options — Configuration options (see above)

Returns

void

FitSignal.init({
  apiKey: 'fs_live_abc123'
});

`FitSignal.identify(user)`

Identify the current user. This checks eligibility and may auto-show a survey.

Parameters

user — User data object (see User Data section)

Returns

Promise<void>

await FitSignal.identify({
  email: 'user@example.com',
  name: 'John Doe',
  externalId: 'user_123',
  attributes: {
    plan: 'pro',
    company: 'Acme Inc'
  }
});

`FitSignal.show(surveyId?)`

Manually show the survey widget.

Parameters

surveyId (optional) — Survey ID to show. Uses the ID from init() if not provided.

Returns

Promise<void>

// Show default survey
await FitSignal.show();

// Show specific survey
await FitSignal.show('surv_xyz789');

`FitSignal.hide()`

Hide the survey widget.

Returns

void

FitSignal.hide();

`FitSignal.isEligible(surveyId?)`

Check if the current user is eligible for a survey.

Parameters

surveyId (optional) — Survey ID to check. Uses the ID from init() if not provided.

Returns

Promise<boolean>

const eligible = await FitSignal.isEligible();
if (eligible) {
  console.log('User can take the survey');
}

`FitSignal.reset()`

Clear all stored state (customer ID, dismissed surveys). Call when the user logs out.

Returns

void

// When user logs out
function handleLogout() {
  FitSignal.reset();
  // ... rest of logout logic
}

`FitSignal.on(event, callback)`

Subscribe to SDK events.

Parameters

event — Event name (see Events section)
callback — Function to call when event fires

Returns

void

FitSignal.on('complete', (data) => {
  console.log('Survey completed:', data.surveyId);
  // Track in analytics, show thank you message, etc.
});

`FitSignal.off(event, callback?)`

Unsubscribe from SDK events.

Parameters

event — Event name
callback (optional) — Specific callback to remove. Removes all listeners if omitted.

Returns

void

// Remove specific listener
const handler = (data) => console.log(data);
FitSignal.on('complete', handler);
FitSignal.off('complete', handler);

// Remove all listeners for an event
FitSignal.off('complete');

Events

Subscribe to these events using FitSignal.on().

Event	Data	Description
ready	—	SDK initialized and ready
identify	`{ customerId }`	User identified successfully
eligible	`{ surveyId }`	User is eligible for a survey
show	`{ surveyId }`	Survey widget displayed
close	—	Widget closed (any reason)
complete	`{ surveyId }`	Survey completed by user
dismiss	`{ surveyId }`	Survey dismissed by user
error	`{ type, error }`	An error occurred

Example: Tracking survey events

// Track all survey events in your analytics
FitSignal.on('show', (data) => {
  analytics.track('Survey Shown', { surveyId: data.surveyId });
});

FitSignal.on('complete', (data) => {
  analytics.track('Survey Completed', { surveyId: data.surveyId });
});

FitSignal.on('dismiss', (data) => {
  analytics.track('Survey Dismissed', { surveyId: data.surveyId });
});

FitSignal.on('error', (data) => {
  console.error('FitSignal error:', data.type, data.error);
});

User Data

Data passed to FitSignal.identify().

Property	Type	Required	Description
email	string	Yes	User's email address
externalId	string	No	Your internal user ID
name	string	No	User's display name
attributes	object	No	Custom attributes (plan, company, etc.)

Example with all fields

FitSignal.identify({
  // Required
  email: 'john@acme.com',

  // Optional
  externalId: 'usr_abc123',
  name: 'John Doe',
  attributes: {
    plan: 'enterprise',
    company: 'Acme Inc',
    role: 'admin',
    signupDate: '2024-01-15'
  }
});