SDK Reference

Once the Trackelio widget script is loaded, a global window.Trackelio object becomes available. This SDK lets you control the widget programmatically, identify users, listen for events, and customize behavior at runtime.

Methods

identify

window.Trackelio.identify({
  user_id: 'usr_12345',
  email: 'jane@example.com',
  name: 'Jane Smith',
  plan: 'pro',
  company: 'Acme Inc'
});

Sets the current user’s identity. Accepts a UserAttributes object with the following fields:

• user_id — A unique identifier for the user in your system.
• email — The user’s email address.
• name — The user’s display name.
• Any additional custom fields (e.g., plan, company, role) that you want to associate with feedback submissions.

Identified users have their information automatically attached to feedback posts, survey responses, and messenger conversations.

open

// Open the widget panel
window.Trackelio.open();

// Open a specific module
window.Trackelio.open({ module: 'feedback' });

Opens the widget panel. Optionally pass an options object with a module property to open a specific module directly (e.g., 'feedback', 'messenger', 'roadmap', 'changelog').

close

window.Trackelio.close();

Closes the widget panel if it is currently open. The trigger button remains visible.

show

window.Trackelio.show();

Shows the trigger button. Use this to make the widget visible after it has been hidden with hide().

hide

window.Trackelio.hide();

Hides the trigger button and closes the widget panel if it is open. The widget remains loaded in memory but is not visible to the user.

prefill

window.Trackelio.prefill({
  title: 'Login page is slow',
  description: 'The login page takes over 5 seconds to load on mobile.',
  module: 'feedback'
});

Pre-fills form fields in the widget. Accepts an object with the following optional properties:

• title — Pre-fill the feedback title.
• description — Pre-fill the feedback description.
• module — Set the active module when the widget opens.

This is useful for creating contextual feedback buttons that pre-populate information based on where the user is in your application.

setConfig

window.Trackelio.setConfig({
  position: 'bottom-left',
  theme: 'dark',
  language: 'es'
});

Overrides widget configuration at runtime. Accepts a partial WidgetConfig object. Only the specified properties are changed; all other settings remain as configured in the dashboard. This is useful for adapting the widget to different pages or user preferences.

on

window.Trackelio.on('submit', function (data) {
  console.log('Feedback submitted:', data);
});

Subscribes to a widget event. The handler function is called each time the specified event fires. See the Events section for the full list of available events.

off

function handleSubmit(data) {
  console.log('Feedback submitted:', data);
}

// Subscribe
window.Trackelio.on('submit', handleSubmit);

// Unsubscribe
window.Trackelio.off('submit', handleSubmit);

Removes a previously registered event handler. Pass the same function reference that was used with on().

reset

window.Trackelio.reset();

Clears the current user identity and session data. Use this when a user logs out of your application to ensure subsequent feedback is not associated with the previous user.

destroy

window.Trackelio.destroy();

Completely removes the widget from the DOM and cleans up all event listeners and internal state. After calling destroy(), window.Trackelio is no longer functional. To re-initialize the widget, you would need to reload the script.

Events

Subscribe to events using window.Trackelio.on(event, handler).

Widget lifecycle

Event	Description
open	Fired when the widget panel is opened.
close	Fired when the widget panel is closed.
module:change	Fired when the user switches between widget modules.

window.Trackelio.on('open', function () {
  console.log('Widget opened');
});

window.Trackelio.on('module:change', function (data) {
  console.log('Switched to module:', data.module);
});

Feedback

Event	Description
submit	Fired when a feedback post is successfully submitted.
screenshot	Fired when the user captures a screenshot via the visual feedback tool.

window.Trackelio.on('submit', function (data) {
  console.log('Feedback submitted:', data.title);
});

User identity

Event	Description
identify	Fired when identify() is called and user identity is set.
reset	Fired when reset() is called and user data is cleared.

window.Trackelio.on('identify', function (attrs) {
  console.log('User identified:', attrs.email);
});

Messenger

Event	Description
messenger:start	Fired when a new messenger conversation is started.
messenger:message	Fired when a message is sent in a conversation.

window.Trackelio.on('messenger:start', function (data) {
  console.log('Conversation started:', data.conversationId);
});

Surveys and scores

Event	Description
nps:submit	Fired when an NPS response is submitted.
csat:submit	Fired when a CSAT response is submitted.
survey:submit	Fired when a survey response is submitted.

window.Trackelio.on('nps:submit', function (data) {
  console.log('NPS score:', data.score);
});

window.Trackelio.on('survey:submit', function (data) {
  console.log('Survey completed:', data.surveyId);
});