Installation via NPM package

Using the NPM package is an easy way to install Product Fruits into your application. It supports browser-based environments.

Using the Product Fruits NPM package

First, install the package:

npm install product-fruits --save

Second, determine the appropriate location in your code to initialize Product Fruits. The requirements for this are:

• The current user's information should be available. You will need at least the username (user identifier), but if you plan to pass more properties to Product Fruits, initialize Product Fruits after you have all necessary information available.
• Product Fruits should be initialized only once to prevent re-renders. If your application is a single-page application, initialize Product Fruits outside of the router, typically in a main application file or a component that is not frequently re-mounted. 

Depending on the framework, the right location could be in the main entry point file, or a file or component that has access to all pages that you want to use Product Fruits with. Typically, this would also be a file or component that runs after user authentication.

When you have determined the right location, initialize Product Fruits like this:

import { productFruits } from 'product-fruits';

// later in the code
productFruits.init('<<YOUR WORKSPACE CODE>>', '<<LANGUAGE CODE>>', { username: '<<REPLACE>>' });

To initialize Product Fruits successfully, the following information needs to be included:

• Workspace code - you can find it in the Installation section in the Product Fruits administration, or if you are creating a new workspace, you can find it in the installation wizard. The workspace code of the current workspace is also a part of every URL path in the Product Fruits administration.
• Language code - it has to be a lowercase ISO 2-letter code, and it must match one of the languages you set as a supported language in the workspace settings. Please note that Product Fruits can only be initialized with one language at a time. If language switching is needed, the Product Fruits instance should be destroyed with window.productFruits.services.destroy() and then re-initialized with a new language code.
• User information object - this object serves to identify the current user. It must have at least the username property, every other property is optional. More information on user properties can be found here.

Single-page applications

Product Fruits works great for single-page applications, but extra attention can be needed for route changes.

We try to detect location changes automatically, but this may not work with all routers. If Product Fruits does not seem to be able to detect location changes (e.g., multi-page tours aren't running properly), you can try disabling the default route change detection and instead manually send a signal to Product Fruits when routes change. 

Please enable this option only if you experience problems. In most cases, it won't be necessary.

1. Disable the default location change detection

Add the disableLocationChangeDetection option to the init call. The initialization call would then look something like this:

productFruits.init(
	'<<YOUR WORKSPACE CODE>>', 
	'<<LANGUAGE CODE>>', 
	{ 
		username: '<<REPLACE>>' 
	},
	{
		disableLocationChangeDetection: true
	}
);

2. Send a signal to Product Fruits when the location changes

Send the signal to Product Fruits when the location changes. This must be done after the route was changed (after location.href is updated).

$productFruits.push(['pageChanged']); // should be called in the safe context, see safeExec()

Helper methods

The NPM package exports a helper method to help you interact with the Product Fruits API.

safeExec()

import { productFruits } from 'product-fruits';

productFruits.safeExec(($productFruits) => {
	// This callback is called if/when Product Fruits is ready.
	// It is safe to use Product Fruits API calls here.
});

Use this method to execute Product Fruits API methods safely only after the API is ready.

Configuration object

Optionally, you can pass a configuration object as the last parameter of the init method. Some available properties are:

• disableBannersAutoMargin: When using banner announcements, this option can disable the automatic page layout shift.
• disableLocationChangeDetection: Disables the default location change detection, requiring manual signals for page changes.

A few more options and detailed information for each option can be found here.