Package Exports

@thatsnu/browser-sdk
@thatsnu/browser-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@thatsnu/browser-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Thatsnu!

Announce your customers about features you just launched!

📦 Install

npm install --save-dev @thatsnu/browser-sdk

🪄 Basic usage

Define an indicator next to an existing element(s) on your page

<span
    data-tnu-id="customers"
    data-tnu-text"New!"
    data-tnu-tooltip="New features inside, Check it out!"></span>

Initialize the SDK:

import thatsnu from '@thatsnu/browser-sdk';

await thatsnu.init({
    defaultColor: '#462a68'
});

Watch the results:

When a user clicks on the New icon, it disappears, and next time s.he won't see it anymore.

⚙️ Options

SDK options

Here are the options you can provide the SDK init function (thatsnu.init(...) above):

Name	Type	Description	Default value
defaultColor	string	a valid CSS color (hexa, rga, rgba, string) that will apply by default to all the indicators on page	#462a68
indicators	Array<IndicatorOption>	an array of objects that alternatively can describe the indicator's options from the table below instead of using HTMl attributes. When provide this array, you have to provide `id` property for each object and make sure it has a correspondence HTML element with similar `data-thatsnu-id`, the rest of the properties will define the element instead of doing it via HTML attributes. If an HTML attribute will be provided in addition, it has more power than the object property, and it'll override it.
onClick	Function (id: string) => boolean	a callback function that will invoke when a user clicks one of indicators. You'll receive the id (aka: `data-tnu-id`) of the clicked element and then you need to return a boolean value than tells the SDK if this user's click considered - so next time the user won't see this indicator - or not.
initialState	Array<string>	an initial state of identifiers you want to initiate the SDK with. When provide this state to the SDK, it considered as the user already clicked the elements with such ID and won't see it again. Required to use if you're managing the persistence layer by yourself.
getState	Function () => Array<string>	A method that return all indicators ID's the user clicked so far. Required to use if you're managing the persistence layer by yourself.
debugTooltip	boolean	a boolean that prevent mouse-out event from an indicator to leave the tooltip open and let the developer design it.	false

Indicator options

Here are the options of a particular indicator's, they can be provided via HTML attributes or inside each object in the indicators array that sent to the SDK above.

JS property	HTML attribute	Description	Mandatory	Default value
id	data-tnu-id	a unique identifier for an element, the library search and watch on these attributes and generates an indicator next to it Note: this is the essential part of the library, the bare minimum is to define this as an attribute on an HTML element like in the example above, all the rest are optional.	yes, as an HTMl attribute!
text	data-tnu-text	the text that will present on the indicator, on this mode the indicator will be squared with the text inside, leave the text empty or omit it, will show a circle indicator	no
className	data-tnu-class-name	a class-name that will be added to the indicator to help you to apply your own design	no
styles	data-tnu-styles	a JSON string of css rules to override the indicator's styles, all CSS rules are valid here	no
color	data-tnu-color	define a color for the indicator, this override the defaultColor value on the SDK initiation	no	SDK.defaultColor
expiration	data-tnu-expiration	the date that this identifier is not valid anymore, in such a case the library won't generate an indicator next to it, this is useful when u know the due date of the feature promotion in advanced, and you don't want the user to see it after automatically. When an HTML attribute in use, this value must be provided as a valid date's string that Date constructor knows to parse. When a JS property in use, you can provide a regular JS date object.	no
tooltipText	data-tnu-tooltip-text	a text for the indicator's tooltip	no	"New!"
tooltipClassName	data-tnu-tooltip-class-name	a class-name that will be added to the indicator's tooltip for your conform to apply a custom design	no
tooltipStyles	data-tnu-tooltip-styles	a JSON string of css rules to override the indicator's tooltip styles that appear on user's mouse hover, all CSS rules are valid here	no

🏆 Example

General

Worth to invest 5 minutes to read!

The library has two parts, HTML declaration of the elements you want to indicate and a javascript SDK that once initiated, search and generates indicators next to the HTML elements you declared.

Each HTML element has to have an identifier that defines via the data-tnu-id attribute, this value should be unique across your system to prevent conflicts with other elements and to be able to understand whether the user already clicked/saw it or not and hide it later.

New feature introduction

For example, assume you added a new reports system for your customers, probably you're going to have a new menu item on the left, that you want the user to be aware of, and stop shows it when use clicked on it or after a while when users got used to it.

To do so, add the following attributes to your exists menu item element belong to the nre Reports:

<div 
    data-tnu-id="reports" 
    data-tnu-tooltip="Introducing new reporting system!" 
    data-tnu-expiration='2022-11-15T23:59:59.728Z'>
  Reports
</div>

This code will generate an indicator next to the Reports menu item:

And it'll be visible until 2022-11-15, end of day, or if the user will click it.

Later, you added few new reports to the list, and you want to make sure the user is aware of them, you can add the following to each:

Example in React.js

const ReportsComponent = () => {
    const reports = [{ id: 1, name: 'All customers'}, { id: 2, name: 'Youth customers' }];
    
    return (
        <table>
            <tr>
                <th>ID</th>
                <th>Name</th>
            </tr>
            { reports.map(report => {
                if (report.isNew) {
                    <td
                        data-tnu-id={`reports.${report.id}`}
                        data-tnu-text='New!'
                        data-tnu-tooltip={`New report added: ${report.name}`}>
                        {report.id}
                    </td>
                } else {
                    <td>{report.id}</td>
                }
                <td>{report.name}</td>
            })}
        </table>
    );
}

This code will generate an indicator next to each new report:

Later, you added a new feature to let user share a report with others, inside a report page there will be a Share button, and you can use this code to make the users aware of it:

<div>
  <button>
    Share
  </button>
  <span data-tnu-id="reports.share"
        data-tnu-tooltip="New! share this report with others"></span>
</div>

The code will generate an indicator next to the share button:

Persistence

TBH!