Skip to main content

Client SDK

By default the Produktly script includes a client SDK, that you can use with Javascript to more granularly control certain behaviors. For example, to start product tour on a custom button click.

Useful for:​

  • Identifying users and enabling user segmentation
  • Starting e.g. product tours with code based on e.g. button click, or any custom event
  • More granular control when widgets are shown
  • Implementing complex filters and product specific behaviors
  • Configuring redirect behavior

Available methods​

Common Parameters​

Many of the SDK methods that open or start widgets support an optional ignorePublish parameter:

  • ignorePublish?: boolean - When true, the widget will be shown regardless of its publishing status on the Produktly dashboard. When false, the SDK will respect the publishing status and only show published widgets. Defaults to true for backwards compatibility.

Produktly.configure​

Configure the SDK. You can set your token here (as an alternative to passing it via the script tag), customize redirect behavior for single page apps, and defer widget initialization until you've identified the current user.

Available params:

type ConfigureParams = {
  token?: string; // Your Produktly token (optional if already set via the script tag)
  redirect?: (url: string) => void; // Custom redirect for SPAs
  waitForUser?: boolean; // When true, the SDK waits for identifyUser before fetching widgets
};

Basic SPA redirect example:

window.Produktly.configure({
  redirect: (url) => {
    yourRedirectFunction(url);
  },
});

Defer widget initialization until the user is identified:

window.Produktly.configure({
  waitForUser: true,
});

// Later, once your app knows who the user is:
window.Produktly.identifyUser(userId, { plan: "startup" });

Produktly.identifyUser​

Used to identify the current user for Produktly, so that you can use your own custom attributes to filter on Produktly.com. Also to track checklist or changelog progress for the user.

Available params:

window.Produktly.identifyUser(
  userId: string, // String or number, that uniquely identifies the current user, e.g. primary key
  metadata: Record<string, string | number>, // This should be an object
  options?: {
    hash?: string; // HMAC-SHA256 hash for identity verification (optional)
  }
);

Example:

window.Produktly.identifyUser(
  7182, // String or number, that uniquely identifies the current user, e.g. primary key
  {
    plan: "startup",
    companyId: 771,
    createdAt: "2021-10-26T12:33:52Z",
    isOnTrial: false,
  } // This should be an object
);

With identity verification:

window.Produktly.identifyUser(7182, { plan: "startup" }, {
  hash: "a1b2c3..." // HMAC-SHA256 hash generated on your backend
});

Produktly.clearCurrentUser​

Clear the currently identified user. Useful when a user logs out of your app, so that Produktly stops associating subsequent activity with that user.

This removes the stored external user id and resets the local user state. After calling this, Produktly will treat the visitor as anonymous until you call identifyUser again.

Example:

// On logout
window.Produktly.clearCurrentUser();

Produktly.startTour​

Start tour manually using Javascript, all you need is the tour id.

Available params:

type StartTourParams = {
  tourId: number;
  stepIndex?: number; // Optional, if you want to start at a specific step. Note that index is 0 based
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
  respectAllTourSettings?: boolean; // Optional. When true, honors targeting rules, frequency, and other tour settings even when started manually
  clearProgress?: boolean; // Optional. When true, resets any previous progress for this tour and starts from step 0
  refreshToken?: string | number; // Optional. Change this between calls to force the same tour to re-trigger
};

Example:

window.Produktly.startTour({
  tourId: 1,
});

or with stepIndex

window.Produktly.startTour({
  tourId: 1,
  stepIndex: 1,
});

Restart a tour from the beginning, clearing any prior progress:

window.Produktly.startTour({
  tourId: 1,
  clearProgress: true,
});

Produktly.closeTour​

Close the currently running tour.

Available params:

type CloseTourParams = {
  id: number;
};

Example:

window.Produktly.closeTour({
  id: 1,
});

Produktly.startChecklist​

Start checklist with Javascript, all you need is the checklist id.

Available params:

type StartChecklistParams = {
  checklistId: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.startChecklist({
  checklistId: 1,
});

Produktly.markChecklistStepCompleted​

Mark specific checklist step as completed checklist with Javascript. This can be useful for building very customized checklist experiences, that are not possible with the default Produktly checklist widget.

You can find the step id by going to edit the checklist in Produktly, then selecting the step, and then scrolling to the bottom you will see "Step Id: ...".

Available params:

type MarkChecklistStepCompletedParams = {
  checklistId: number;
  stepId: string; // uuid
};

Example:

window.Produktly.markChecklistStepCompleted({
  checklistId: 1,
  stepId: "4d3ad847-8348-42a3-bcc1-2b516759e9ff",
});

Produktly.openChangelog​

Open a changelog with Javascript, all you need is the changelog id.

Available params:

type OpenChangelogParams = {
  id: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.openChangelog({
  id: 1,
});

Produktly.getChangelogUnreadCount​

Get the unread count for a given changelog, i.e. how many posts for the changelog the user hasn't read yet

Note that this returns a Promise, since it requires an api call, so you should either use await or Promise chaining i.e. .then.

Available params:

type GetChangelogUnreadCountParams = {
  id: number;
};

Returns: Promise<number>

Example:

const unreadCount = await window.Produktly.getChangelogUnreadCount({
  id: 1,
});

Produktly.openSmartTip​

Open a smart tip with Javascript, all you need is the smart tip id.

Available params:

type OpenSmartTipParams = {
  id: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.openSmartTip({
  id: 1,
});

Produktly.openFeedback​

Open a feedback widget with Javascript, all you need is the feedback widget id.

Available params:

type OpenFeedbackParams = {
  id: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.openFeedback({
  id: 1,
});

Produktly.openAnnouncement​

Open an announcement with Javascript, all you need is the announcement id.

Available params:

type OpenAnnouncementParams = {
  id: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.openAnnouncement({
  id: 1,
});

Produktly.openNpsWidget​

Open an NPS widget with Javascript, all you need is the NPS widget id.

Available params:

type OpenNpsWidgetParams = {
  id: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.openNpsWidget({
  id: 1,
});

Produktly.openMicroSurvey​

Open a micro survey with Javascript, all you need is the micro survey id.

Available params:

type OpenMicroSurveyParams = {
  id: number;
  ignorePublish?: boolean; // Optional, defaults to true. When true, ignores publishing status
};

Example:

window.Produktly.openMicroSurvey({
  id: 1,
});

Produktly.closeChecklist​

Close the currently open checklist widget.

Available params:

type CloseChecklistParams = {
  id: number;
};

Example:

window.Produktly.closeChecklist({
  id: 1,
});

Produktly.closeChangelog​

Close the currently open changelog widget.

Available params:

type CloseChangelogParams = {
  id: number;
};

Example:

window.Produktly.closeChangelog({
  id: 1,
});

Produktly.closeSmartTip​

Close the currently open smart tip widget.

Available params:

type CloseSmartTipParams = {
  id: number;
};

Example:

window.Produktly.closeSmartTip({
  id: 1,
});

Produktly.closeFeedback​

Close the currently open feedback widget.

Available params:

type CloseFeedbackParams = {
  id: number;
};

Example:

window.Produktly.closeFeedback({
  id: 1,
});

Produktly.closeAnnouncement​

Close the currently open announcement widget.

Available params:

type CloseAnnouncementParams = {
  id: number;
};

Example:

window.Produktly.closeAnnouncement({
  id: 1,
});

Produktly.closeNpsWidget​

Close the currently open NPS widget.

Available params:

type CloseNpsWidgetParams = {
  id: number;
};

Example:

window.Produktly.closeNpsWidget({
  id: 1,
});

Produktly.closeMicroSurvey​

Close the currently open micro survey widget.

Available params:

type CloseMicroSurveyParams = {
  id: number;
};

Example:

window.Produktly.closeMicroSurvey({
  id: 1,
});

Produktly.closeAll​

Close all currently open Produktly widgets at once. This is useful when you want to clear all widgets from the screen.

Example:

window.Produktly.closeAll();

Produktly.setLanguage​

Override the language used by Produktly widgets at runtime. Pass a language code (e.g. "en", "fi", "de") and Produktly will load and render the matching localized content for tours, checklists, changelogs, and other widgets that have translations configured.

This is useful when your app lets users switch languages without a full page reload.

Available params:

window.Produktly.setLanguage(lang: string);

Example:

window.Produktly.setLanguage("fi");

Produktly.getLanguage​

Get the language currently used by Produktly widgets. Returns the active language code as a string.

Returns: string

Example:

const currentLanguage = window.Produktly.getLanguage();