Web applications (legacy script)

This tutorial is for the legacy script only. If you installed Product Fruits before June 3th, 2022, it is for you.

You can also migrate to the newer installation type.

Product Fruits works by adding a short JavaScript code to your web application. This script loads when users load the page. It uses the user attributes you provide us to determine which users should see what content. Content editing and publishing happen in Product Fruits administration.

You can get the snippet in the administration. Sign in to Product Fruits, go to a workspace you wish to install, open the workspace dropdown (click on the workspace name on the top right corner) and click on the Installation item. Copy and paste it into your web application. The best position is close to the </body> closing tag.

Identifying users

Product Fruits needs to identify users to work properly. For instance, we have to know which tours or announcements the particular user was interacting with. If we didn't know this, we could show Product Fruits content multiple times. This is usually not the expected behavior.

User information is transferred through the JavaScript snippet. The only required attribute is username. This must be a unique identifier of the user. It can be the username, e-mail, ID or any unique immutable value assigned to this user. If you don't want to transfer real usernames to Product Fruits, hash them (i.e. MD5, SHA1).

Do not forget to update <<REPLACE>> placeholders and pass the right values. You can omit fields that you don't need. Only the username is required. Product Fruits won't work properly if you don't provide it.

window.productFruitsUser = { username: '<<REPLACE>>', // REQUIRED, must be unique 
                             email: '<<REPLACE>>',
                             firstname: '<<REPLACE>>',
                             lastname: '<<REPLACE>>',
                             signUpAt: '<<REPLACE>>', // Sign up date (yyyy-mm-ddThh:mm:ss) 
                             role: '<<REPLACE>>',
                             props: { customProp1: '<<REPLACE>>' } };

Custom attributes

You can also provide custom attributes to Product Fruits. They can be useful for more precise segmentation. Provide them into the snippet as props subobject. For example:

window.productFruitsUser = { username: '<<REPLACE>>',
                             props: {
                                 yourCustomProp: 'value',
                                 yourCustomProp2: 'value2'
                             }
                           };

Dynamic user information changes

If user information changes dynamically (i.e. single-page applications), you have to notify us. A simple change to the original productFruitsUser object won't work.

When the change occurs, call the window.productFruits.identifyUser(...) method. This method takes a user information object as the first parameter.

Localization and language settings

If your application uses localization and you plan to localize Product Fruits content, don't forget to set the selected language. You need to provide a valid lowercase ISO 639-1 code. The language parameter is the last one on the last row of the script. See the example:

<script type="text/javascript">
window.productFruitsUser = { username: '<<REPLACE>>' };
(function(w,d,u,c,l){
        w.productFruits=w.productFruits||{};
        w.productFruits.language=l;w.productFruits.code=c;
        var a=d.getElementsByTagName('head')[0];
        var r=d.createElement('script');r.async=1;
        r.src=u+'?c='+c;
        a.appendChild(r);
})(window,document,'https://app.productfruits.com/static/script.js','xxxxxxxxx','HERE COMES THE LANGUAGE CODE'); // language = ISO 2 letter
</script>

Single-page applications

Usually, Product Fruits integration doesn't need to be adjusted for single-page application frameworks. We try to detect new elements, page changes, etc. However, some router components can cause issues with detecting URL changes. Typically, you'll see tours stopping randomly on page change events. If this is your case, take these steps:

  1. Disable Product Fruits page change detection: window.pfDisableUrlChangeDetection = true
    You must set this object variable before the original JavaScript snippet is executed. 
  2. In your router, call window.productFruits.pageChanged() after every page change. Make sure, you call this method after the page content is properly generated.

Disposing Product Fruits

If you need to remove Product Fruits from your web application, call window.productFruits.services.destroy(). The typical use case is destroying Product Fruits from login pages in single-page applications.

If you want to initialize Product Fruits again, call window.productFruitsInit().