@commercetools-frontend/userguiding

This is a package used internally for Merchant Center applications. We do not provide any guarantees or support for the functionality.

This package provides an easy-to-use integration with UserGuiding that initializes UserGuiding scripts as methods on the window object.

This is achieved by initializing a UserGuiding container. The official documentation for UserGuiding's container workflow can be found here.

Once a UserGuiding container is initialized, the UserGuiding javascript API is made available as methods on window, as documented in their UserGuiding "JS API" documentation.

Installation

$ npm install --save @commercetools-frontend/userguiding

Usage

Initialization

You will first need to initialize the userguiding provider by instantiating it at the preferred root component of your application.

Configuiration via Custom Application configuration file

If you are developing a Custom Application for the Merchant Center, we recommend adding a USERGUIDING_CONTAINER_KEY value to your environment.

The environment variable should then be exposed by adding a userGuidingContainerKey property to the additionalEnv field of your Custom Application's configuration file.

additionalEnv: {
    userGuidingContainerKey: '${env:USERGUIDING_CONTAINER_KEY}',
},

You will need to specify whether or not to disable UserGuiding using the disabled param.

import { initializeUserGuiding } from '@commercetools-frontend/userguiding';

initializeUserGuiding({
  disabled: false,
});

In order for the module to be able to connect with UserGuiding's APIs you have to extend the headers.csp property of your Custom Application config to contain the following properties:

import { CONTENT_SECURITY_POLICIES as USERGUIDING_CONTENT_SECURITY_POLICIES } from '@commercetools-frontend/userguiding/constants';

headers: {
    csp: {
        'connect-src': [...USERGUIDING_CONTENT_SECURITY_POLICIES.CONNECT_SRC],
        'script-src': [...USERGUIDING_CONTENT_SECURITY_POLICIES.SCRIPT_SRC],
        'font-src': [...USERGUIDING_CONTENT_SECURITY_POLICIES.FONT_SRC],
    },
},

Configuration without Custom Application configuration

If you are not building a Custom Application or prefer not to configure UserGuiding using the Custom Application's configuration, you will need to pass a containerKey for the UserGuiding container you wish to initialize to the initializeUserGuiding method. The containerKey is the last param specified in the IIFE code snippet UserGuiding provides in the container settings page, as documented here.

import { initializeUserGuiding } from '@commercetools-frontend/userguiding';

initializeUserGuiding({
  containerKey: '<your-container-key>',
  disabled: false,
});

Please also make sure that the connect-src, script-src, and font-src Content Security Policies allow UserGuiding to connect with their services. If needed you can use the provided constants from @commercetools-frontend/userguiding/constants exported as CONTENT_SECURITY_POLICIES.

Setting up the tracking effect

In order to provide UserGuiding with data necessary to be able to target specific segments of users with custom user guides, you must call the useTrackingEffect react hook in the entry point of your application. This method is meant to be used with the commercetools-frontend ApplicationShell component and must be rendered as a child of ApplicationShell because it depends on its react context.

import { useTrackingEffect as useUserGuidingTrackingEffect } from '@commercetools-frontend/userguiding';

function EntryPoint() {
    useUserGuidingTrackingEffect();

    return <>
        <Application>
    </>
}

1. If you intend to send additional user variables you can pass them using the additionalUserVars object
2. If you intend to disable UserGuiding entirely (e.g. based on a feature flag), use the disable flag
   • Note that you can only disable until you initialized once.

FAQ

Question: I want to disable UserGuiding in a specific environment

Answer: Unset or do not set the USERGUIDING_CONTAINER_KEY on that environment's .env file.

Question: I want to test UserGuiding locally

Answer:

1. Set the USERGUIDING_CONTAINER_KEY on the .env.local file.
2. Find the useUserGuidingTrackingEffect hook in your application's entry point and set the disabled flag to false.
3. Finally, set initializeUserGuiding's disabled flag to false in the root-level component of your application.
4. Restart the application to test your changes.