The Software Development Kit (SDK) enables controlling Noticeable components from your JavaScript code. For instance, it allows rendering Widgets, listening to events, as well as performing actions such as opening, closing, or doing fancy stuff with any Widgets.

Loading the Noticeable JavaScript SDK

In the case you need to get the most recent version of the code snippet, you can copy the content from the following URL (it is not recommended to reference this URL directly as a script) :
https://sdk.noticeable.io/s.js

That snippet loads the Noticeable SDK onto the page asynchronously, so it won’t affect your page load speed. Once the snippet is running on your site, you can interact with the SDK via the global window variable named noticeable.

Available Commands

You can find the list of supported commands here. Each command may support a set of actions:

• noticeable.debug()
• noticeable.destroy(...)
• noticeable.do(...)
• noticeable.identify(...)
• noticeable.is(...)
• noticeable.on(...)
• noticeable.off(...)
• noticeable.ready(...)
• noticeable.render(...)
• noticeable.reset(...)
• noticeable.set(...)

Checking States

Widget Closed

• Asynchronous: Yes.
• Description: Returns a promise resolving to true if the specified widget is closed, false otherwise.
• Code: noticeable.is('widget:closed', widgetId);

Widget Opened

• Asynchronous: Yes.
• Description: Returns a promise resolving to true if the specified widget is opened, false otherwise.
• Code: noticeable.is('widget:opened', widgetId);

Debug

The SDK includes an option to show debug traces: noticeable.debug();. This synchronous command must appear before all others and should not be used in production.

Doing Actions

Close Widget

• Asynchronous: No.
• Description: Close the widget view. For instance, with the popup widget, the popup is closed but the widget trigger remains visible.
• Code: noticeable.do('widget:close', widgetId);

Open Widget

• Asynchronous: No.
• Description: Open the widget view. For instance, with the popup widget, the popup is opened but the trigger view remains untouched.
• Code: noticeable.do('widget:open', widgetId);

Toggle Widget

• Asynchronous: No.
• Description: Open the widget if it is closed or close the widget if it is opened.
• Code: noticeable.do('widget:toggle', widgetId);

Identifying Users

• Asynchronous: Yes.
• Description: Tie a user to their actions and record traits about them. Returns a promise that fulfills when the command completes.
• Code:

noticeable.identify('PROJECT_ID', {
    id: 'a8ONg9xpnGmSg', // your unique user ID
    avatar: 'https://acme.com/john.png', // optional
    name: 'John Doe',  // optional
    email: 'john.doe@acme.com' // optional
});

The first parameter to identify is your project identifier on Noticeable. The second parameter is an object containing user traits. Traits are pieces of information you know about a user. For now, we allow a limited number of trait fields:

• id (required): Unique ID in your database or anonymous ID for a user.
• avatar (optional): URL to an avatar image for the user.
• email (optional): Email address of a user.
• name (optional): User display name.

Listening to Events

Open the dedicated article about how to listen to events with the Noticeable JavaScript SDK.

Rendering Widgets

Render Widget

• Asynchronous: Yes.
• Description: Render the widget with the given identifier. Returns a promise that fulfills when the command completes.
• Code: noticeable.render('widget', widgetId, options);

The options parameter is optional. It's a JavaScript object that allows passing the following options:

• root: An HTML element or shadow root from where the widget selector is searched.
• segments: An array of segment values to enable segmentation.

• Example 1: Render a widget in a web component / custom element: noticeable.render('widget', widgetId, {root: this.shadowRoot});
• Example 2: Render a widget with segment values specific to a user seeing the widget: noticeable.render('widget', widgetId, {segments: ['Plan:Business', 'Role:Editor']});

Destroy Widget

• Asynchronous: Yes.
• Description: Destroy the widget with the specified identifier. This is the opposite operation of render(...). Nothing happens if the specified widget was not rendered. Returns a promise that fulfills when the command completes.
• Code: noticeable.destroy('widget', widgetId);

Resetting

• Asynchronous: Yes.
• Description: Reset states for the specified project identifier. Unlink any previous identify session. Returns a promise that fulfills when the command completes.
• Code: noticeable.reset(projectId);

Setting Values

Set Global Preferences

• Asynchronous: No.
• Description: Configure global SDK preferences such as first-party cookies options.
• Code:

noticeable.set('preferences', {
  firstPartyCookies: {
    localStorage: false, 
    retentionPeriod: 31536000000
  }
});

By default Noticeable uses local storage for some cookies. You can disable its usage with the command above. When disabled, legacy cookies with an expiration time are used instead. The default retention period is set to 1 year. You can customize this period as shown above. The value is a number with millisecond precision.

Set Widget Publication Read

• Asynchronous: Yes.
• Description: Mark the specified publication ID(s) as read. Returns a promise that fulfills when the command completes.
• Code: noticeable.set('widget:publication:read', widgetId, publicationId);

This command also supports an array of publications as third parameter.

Set Widget Publication Seen

• Asynchronous: Yes.
• Description: Mark the specified publication ID(s) as seen. Returns a promise that fulfills when the command completes.
• Code: noticeable.set('widget:publication:seen', widgetId, publicationId);

This command also supports an array of publications as third parameter.

Using noticeable Before It Is Ready

The Noticeable SDK is loaded asynchronously to prevent slowing down your pages. If you need to synchronize commands that return a promise (asynchronous commands), then do it in the Noticeable ready callback:

noticeable.ready(async function() {
    const widgetId = 'twIQzr4qsf7VbCrqTVHx';
    await noticeable.render('widget', widgetId);
    noticeable.do('widget:open', widgetId);
    console.log('Is widget closed? ', await noticeable.is('widget:closed', widgetId));
});

Updated on: 08/26/2022