Installation via NPM package

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

Using Product Fruits NPM package

First, install the package:

npm install product-fruits --save

Second, you have to find the right place where you should initialize Product Fruits. Requirements for this place:

• You should have the current user information available. You will need at least the username, but if you plan to pass more properties to Product Fruits, initialize PF after you have all information available.
• You can initialize Product Fruits only once. If your application is a single-page application, you should initialize Product Fruits outside of your router.

When you found the right place, initialize Product Fruits.

import { productFruits } from 'product-fruits';

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

To make a successful initialization, you need:

• Workspace code - you will find it in the Installation section in the Product Fruits administration or if you are creating a new workspace, you will find it in the installation wizard.
• Language code - it has to be an ISO 2-letter code, it has to match one of the languages you set as a Supported language in the workspace settings
• User information object - you have to identify the current user. Pass an object with the user information. The username field is required. You pass more properties, read this.

Single-page applications

Product Fruits work great for single-page applications. There are things you have to check, though.

We try to detect location changes automatically. But it doesn't work with all different routers. If Product Fruits cannot detect new locations (for instance, multi-page tours don't run properly), you can disable the detection and send a signal to Product Fruits manually when routes change. Please, only enable this option if you experience problems. In most cases, it won't be needed.

Disable the default location change detection

Add the disableLocationChangeDetection option to the init call. Change the initialization call to this:

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

Send signal to Product Fruits when location changed

Then, send the signal to Product Fruits when the location changed. It depends on the router you use, but the signal must be sent after the route was changed (the location.href is updated).

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

Helper methods

The NPM package currently exports another method that will help you interact with Product Fruits.

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. It will ensure Product Fruits is ready.

Configuration object

Optionally, you can pass a configuration object as the last parameter of the init method. The following properties can be set:

• disableBannersAutoMargin - when using banner announcements, this can disable the automatic page layout shift
• disableLocationChangeDetection - disables the default location change detection, you have to send signals about page changes manually