@W-20975885 New launch agent location in header component

[sf-tejas-nadkarni]

Adds a configurable header button to launch the shopper agent, refactors shopper agent utilities for simplicity, and includes unit tests

Description

1. Header Component - Agent Button Integration
   File: app/components/header/index.jsx
   Description: Added conditional rendering of the SparkleIcon button in the header based on the enableLaunchAgentFromHeader configuration flag. The button triggers the shopper agent chat when clicked. Integrated with getCommerceAgentConfig utility for centralized configuration management.

2. Configuration Utility Enhancement
   File: app/utils/config-utils.js
   Description: Added getCommerceAgentConfig() utility function to centralize access to commerce agent configuration settings. Added enableLaunchAgentFromHeader to the default configuration options, providing a single source of truth for commerce agent settings across the application.

3. App Component - Agent Click Handler
   File: app/components/_app/index.jsx
   Description: Added onAgentClick handler that calls openShopperAgent() to programmatically open the shopper agent chat window when the header button is clicked.

Types of Changes

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change (could cause existing functionality to not work as expected)
• Other changes (non-breaking changes that does not fit any of the above)

Breaking changes include:

• Removing a public function or component or prop
• Adding a required argument to a function
• Changing the data type of a function parameter or return value
• Adding a new peer dependency to package.json

Changes

• Header Component - Agent Button Integration
• Configuration Utility Enhancement
• App Component - Agent Click Handler

How to Test-Drive This PR

Header.Launch.Location.mov

Checklists

General

• Changes are covered by test cases
• CHANGELOG.md updated with a short description of changes (not required for documentation updates)

Accessibility Compliance

You must check off all items in one of the follow two lists:

• There are no changes to UI

or...

• Changes were tested with a Screen Reader (iOS VoiceOver or Android Talkback) and had no issues
• Changes comply with WCAG 2.0 guidelines levels A and AA
• Changes to common UI patterns and interactions comply with WAI-ARIA best practices

Localization

• Changes include a UI text update in the Retail React App (which requires translation)

[cc-prodsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[sf-jhalak-maheshwari]

Looks good. @sf-tejas-nadkarni qq: will we be adding settings for customer, in the case they want to hide the agent on load and clicking on icon in header only opens it?

[sf-tejas-nadkarni]

@sf-jhalak-maheshwari yes that will be a seperate feature with a new feature flag.

[kevinxh]

It appears the code style is slightly inconsistent, most of the component access the global config object via getConfig().xxxxxx, and it seems shopper agent introduced its own utility getCommerceAgentConfig. I wonder if we want to be consistent, either create utilities for all other features (not just shopper agent), otherwise it looks inconsistent coding style

    const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? STORE_LOCATOR_IS_ENABLED
    const commerceAgentConfig = getCommerceAgentConfig()

[sf-tejas-nadkarni]

Thats a good point, this is where they decided to change it into utility functions, #3230

[kevinxh]

any idea why the booleans are implemented as strings? I understand this is already there before your change but I'm curious to know if you happen to know the answer.

[sf-tejas-nadkarni]

Aggreed its cleaner to use boolean, I'm not sure why the API/Config design uses strings for flags.
I just opted for consistency

this is the official help doc Shopper Agent documentation.

[kevinxh]

Have you considered to make this a React hook? There are many React hooks in this code base and it 's more consistent with the style and the technologies we used. something like below.

import { useCallback } from 'react'

declare global {
    interface Window {
        embeddedservice_bootstrap?: {
            utilAPI: {
                launchChat: () => void
            }
        }
    }
}

/**
 * Hook for launching the Salesforce Embedded Service chat
 */
export function useShopperAgent() {
    const openChat = useCallback(() => {
        if (typeof window === 'undefined') return

        try {
            window.embeddedservice_bootstrap?.utilAPI.launchChat()
        } catch (error) {
            console.error('Shopper Agent: Error launching chat', error)
        }
    }, [])

    return { openChat }
}

usage example

function ChatButton() {
    const { openChat } = useShopperAgent()

    return <button onClick={openChat}>Chat with us</button>
}

[kevinxh]

Overall looks good, left a few comments. thank you

[kevinxh]

I would encourage to update the function signature to make it more generic and return a collection of actions related to shopper agent rather than having "Open" in the hook's name and return a single function, this isn't extendable for future. Imagine we want to add a couple of more functionalities, with this design, we would have to either making a breaking change in terms of the function signature, or create more hooks like useActionOneShopperAgent , useActionTwoShopperAgent , useActionThreeShopperAgent etc.

export function useShopperAgent() {
    const open = useCallback(() => {
        launchChat()
    }, [])
    
    const actions = {
      open,
      // future proof and DRY the implementation
      // this hook can be extended with new functionalities.
    }

    return actions
}

Thoughts?

[sf-tejas-nadkarni]

Thats a good pracitce in react, i dont see it happening for this functionality but i can update it to make it simple

[kevinxh]

It doesn't look like we need to separate functions?

the only thing openShopperAgent does is to call launchChat, can we remove one of them and simplify the code?

[sf-tejas-nadkarni]

There are more feature coming in the next patch where we will need to add more conditions before launchChat thats why i have created it as seperate function

[kevinxh]

I don't think you need the key "actions" because it's already an extensible object.

Suggested change

	return {actions: {open}}
	return { open }

This way you can directly deconstruct it, usage example

const {open} = useShopperAgent()

i'm just nitpicking.

[sf-tejas-nadkarni]

I'd prefer to keep the actions wrapper to add explicit namespace for executable functions. What you think?

[sf-jhalak-maheshwari]

Do we need both launchChat and openShopperAgent function?
We can remove openShopperAgent and just have launchChat. Post that, renaming launchChat maybe a good option too

[sf-tejas-nadkarni]

openShopperAgent will have more conditions once we introduce flag to hide the FAB icon thats why added two seperate functions

[sf-jhalak-maheshwari]

Do we want to add translations for other files as well or is there an automated process?

[sf-tejas-nadkarni]

translation command should have added more labels, let me look into that