Help Me Choose Widget

The Help Me Choose widget adds a Help me choose tab to the right-hand edge of your product pages. When a customer clicks it, the Genius Chat Widget opens with a message about the product they're viewing, such as I'd like to talk about Trail Runner 2, so Purchase AI can pick up the conversation.

The tab shimmers once when it appears so customers notice it, and can be set to shimmer again on an interval.

The widget can also be shown as a floating button at the bottom of the screen instead of a tab.

Prerequisites

• Your DigitalGenius widget ID.
• Your region: eu or us.
• The Genius Chat Widget on the same page. The widget opens the chat to send its message. See Integrating Genius Chat Widget.
• A Purchase AI flow that responds to conversations started from the widget. See Conversation starter.
• Access to edit the HTML of the page the widget is displayed on.

Installation

Add the following code to your product page, after the Genius Chat Widget. Replace your-widget-id with your widget ID, update env to match your region if required, and replace the product name with the one output by your page template.

<script>
  window.DG_SDK_CONFIG = {
    components: [
      {
        widgetId: 'your-widget-id',
        env: 'eu',
        type: 'helpMeChoose',
        config: {
          productName: 'Trail Runner 2',
        },
      },
    ],
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

The tab is docked to the right-hand edge of the page, so it doesn't need a container. targetDOMNode isn't used.

Configuration

The following properties are set on each entry in components.

Providing the product name

retrievalMethod controls where the product name comes from.

Example: value in the configuration

With retrievalMethod set to 'config' (the default), productName is the product name itself. Use this when your page template can output the product name into the script:

<script>
  window.DG_SDK_CONFIG = {
    components: [
      {
        widgetId: 'your-widget-id',
        env: 'eu',
        type: 'helpMeChoose',
        config: {
          retrievalMethod: 'config',
          // replace with the product name output by your page template
          productName: 'Trail Runner 2',
        },
      },
    ],
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

Example: value read from the page

With retrievalMethod set to 'selector', productName is a CSS selector for an element already on the page, and the widget reads the product name from it. Use this when the product name is displayed on the page but can't easily be added to the script:

<h1 class="product-title">Trail Runner 2</h1>

<script>
  window.DG_SDK_CONFIG = {
    components: [
      {
        widgetId: 'your-widget-id',
        env: 'eu',
        type: 'helpMeChoose',
        config: {
          retrievalMethod: 'selector',
          productName: '.product-title',
        },
      },
    ],
  };
</script>
<script src="https://chat.digitalgenius.com/init-sdk.js"></script>

The product name is read when the customer clicks the tab, so elements rendered after the widget loads, or changed when a customer picks a different variant, are supported. For form fields (input, select and textarea) the field's value is used; for other elements, their text content is used, with surrounding spaces removed.

Leaving out hidden text

Some product name elements contain extra text for screen readers that isn't shown on screen, for example:

<h1 class="product-name">
  <span class="accessibility-hidden">details about product:</span>
  Pure Linen Polo - Olive
</h1>

The widget reads all the text in the element, so set productNameExclude to a CSS selector for the elements inside it to leave out:

config: {
  retrievalMethod: 'selector',
  productName: 'h1.product-name',
  productNameExclude: '.accessibility-hidden',
},

The product name read is then Pure Linen Polo - Olive. Line breaks and repeated spaces in the element's text are always collapsed into single spaces.

Localisation

The widget is displayed in British English by default. To change the language, set locale in your configuration:

window.DG_SDK_CONFIG = {
  locale: 'fr-FR',
  components: [
    {
      widgetId: 'your-widget-id',
      env: 'eu',
      type: 'helpMeChoose',
      config: {
        productName: 'Trail Runner 2',
      },
    },
  ],
};

The following locales are supported: cs-CZ, da-DK, de-DE, en-GB, en-LU, en-US, es-ES, et-EE, fi-FI, fr-FR, it-IT, ja-JP, ko-KR, lt-LT, lv-LV, nl-NL, no-NO, pl-PL, pt-PT, ro-RO, sk-SK, sv-SE, zh-CN and zh-TW. Unsupported locales fall back to British English.

Customising text

The text listed below can be customised using a lang object in the app's config. Only the properties you specify are overridden; all other text uses the default wording for the selected locale.

window.DG_SDK_CONFIG = {
  components: [
    {
      widgetId: 'your-widget-id',
      env: 'eu',
      type: 'helpMeChoose',
      config: {
        productName: 'Trail Runner 2',
        lang: {
          buttonLabel: 'Need a hand?',
          message: 'Can you help me decide on the',
        },
      },
    },
  ],
};

For example, with the configuration above, the customer's first message is Can you help me decide on the Trail Runner 2. Your Purchase AI flow doesn't need to recognise this wording. The conversation opens with a conversation_starter chat event with source set to help_me_choose and action set to product_enquiry, and the product name in data.productName when one is set, so branch on those instead:

{
  "from": "customer",
  "type": "chat_event",
  "payload": {
    "name": "conversation_starter",
    "source": "help_me_choose",
    "action": "product_enquiry",
    "text": "Can you help me decide on the Trail Runner 2",
    "data": { "productName": "Trail Runner 2" }
  }
}

Floating button

Set mode to 'floating' to show the widget as a button at the bottom centre of the screen instead of a tab. It appears as a circle, the sparkles pulse and spin, then it opens out to show its text. It has a 2px border, set with style.borderColor. Once the button is open, a highlight sweeps across the border, then again every 6 seconds, or on shimmerInterval if set. When a customer hovers over it, the sparkles spin and a sheen sweeps across the button.

productName is optional in floating mode, so the button can be used on any page. If it's set, it's added to the message in the same way as the tab.

To cycle the button's text, set floatingLabels in config.lang. Each label is shown for labelInterval milliseconds.

window.DG_SDK_CONFIG = {
  components: [
    {
      widgetId: 'your-widget-id',
      env: 'eu',
      type: 'helpMeChoose',
      config: {
        mode: 'floating',
        lang: {
          floatingLabels: ['Help me choose', 'Shop with AI'],
        },
        style: {
          backgroundColor: '#000000',
          textColor: '#ffffff',
          borderColor: '#333333',
          bottom: '2em',
        },
      },
    },
  ],
};

Make sure the button doesn't cover the Genius Chat Widget launcher or other fixed elements at the bottom of your page. Use style.bottom to move it up if needed.

Shimmer

The tab shimmers once, with a highlight that sweeps along it and the sparkles twinkling, when it first appears. To keep drawing customers' attention to it, set shimmerInterval so it shimmers again on a regular interval:

config: {
  productName: 'Trail Runner 2',
  // shimmer every 15 seconds
  shimmerInterval: 15000,
},

If a customer's device is set to reduce motion, the tab doesn't shimmer or slide in. The floating button starts open, without animation or hover effects, and its labels change without a transition.

Behaviour

• Product name: if productName isn't set, the tab isn't shown and a warning is logged to the browser console. The floating button is still shown and sends message on its own.
• Loading: the tab slides in from the right-hand edge of the page as soon as the widget loads. If it's clicked before the Genius Chat Widget has loaded, nothing happens and a warning is logged to the browser console.
• Clicking the tab: opens the chat widget and sends the message as the customer's first message. If the chat is already open, clicking the tab has no effect.
• Position: the tab stays in place as the customer scrolls, and appears behind the chat widget when it's open.

Styling

The widget renders inside a shadow DOM, so the styles on your page don't affect it directly. By default it inherits your page's font, and uses your page's text colour as its background and your page's background colour as its text, so it stands out while matching your colours. Sizes are set in em, so the tab scales with your page's font size.

To change the colours, position, or corner radius, use config.style:

config: {
  productName: 'Trail Runner 2',
  style: {
    backgroundColor: '#1f3d2b',
    textColor: '#ffffff',
    shimmerColor: 'rgba(255, 215, 120, 0.6)',
    top: '40%',
    radius: '0',
  },
},

Troubleshooting

If the tab does not appear, check that:

• type is set to 'helpMeChoose'.
• productName is set and isn't empty.
• widgetId is correct and env matches your region.

If clicking the tab or button does nothing, check that the Genius Chat Widget is on the page and loads without errors. A warning is logged to the browser console when it isn't available.

If the message doesn't include the product name, check the browser console. When retrievalMethod is 'selector', an error is logged if the selector doesn't match an element on the page.