Using the NPM package is an easy way to install Product Fruits into your application. It supports browser-based environments.
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:
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 succesfully, the following information needs to be included:
window.productFruits.services.destroy()
and then re-initialized with a new language code.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.
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
}
);
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()
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.
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.