Skip to main content

Advanced widget customization

Updated

In some cases, website developers may require more control over which campaign is associated with a user. The Salespeak widget offers flexible JavaScript-based options to fine-tune the widget’s behavior and campaign targeting.

1. Dynamic Campaign ID Setting via Cookie

🧩 Overview

The Salespeak widget supports dynamic campaign ID setting via browser cookies. This allows developers to control which campaign is displayed, without editing the widget configuration.

⚙️ Configuration

Default Behavior

  • The widget checks for a cookie named salespeak_dynamic_campaign_id.

  • The cookie value is treated as the campaign ID to use.

Custom Cookie Name

You can override the default cookie name by setting the data-dynamic-campaign-cookie-name attribute in the script tag:

 
<script
  src="https://app.salespeak.ai/widget.js"
  data-org-id="[your_org_id]"
  data-dynamic-campaign-cookie-name="your_custom_cookie_name">
</script>

💡 Implementation Notes

  • Cookies must not be marked as HTTP-only (they need to be accessible via JavaScript).

  • When the cookie is detected, it overrides any other campaign configuration.

  • The widget ignores deployment settings if a valid campaign cookie is found.

🧪 Example

 
// Set the campaign cookie
document.cookie = "salespeak_dynamic_campaign_id=your_campaign_id";

// Using a custom cookie name
document.cookie = "your_custom_cookie_name=your_campaign_id";

2. External JavaScript Integration

🧩 Overview

The Salespeak widget exposes an interactive module under window.salespeakLaunchersScript, allowing advanced programmatic control.

Widget Script and Launchers Builder

<script src="https://app.salespeak.ai/widget.js" data-org-id="8c832abd-50fc-4814-bedd-0285203e8bd9" data-campaign-id="8f7b7eb9-cafe-4c14-9474-532598470b96"></script>

Attributes

  • src:

  • description: Organization internal ID
  • type: string
  • required

  • data-campaign-id:

  • description: Campaign internal ID
  • type: string
  • required

  • data-launcher:

  • description: It describes which launcher will use the script to present the brain
  • type: string
  • default: inline
  • one of:
    • dynamic-launcher // To use website deployment feature
    • floating-input // Inline search bar
    • floating-mascot // Chat icon
    • inline // AI Window - No launcher
    • sidebar // Sidebar
    • sticky-input // Sticky bar
    • summarize-button // Summarize blog
    • tracking // tracking only (no launcher)
    • box-launcher // Box Launcher
    • inline-button // Inline button
    • inline-cards // Inline cards

  • data-selector:

  • description: It describes the HTML element where the launcher should be rendered
  • type: string
  • default: current element
  • one of:
    • ID selector of the element
    • body tag selector

  • data-brain-url:

  • description: session internal ID
  • type: string
  • default: ''

  • data-header-selector:

  • description: HTML element selector where the header is located
  • type: string
  • default: header tag selector

  • data-fixed-height:

  • description: If launcher = floating-input and data-floating-input-action = inline, it describes how much height the brain frame will take on the screen
  • type: string
  • default: '90vh'
  • one of:
    • PX number
    • numbers with units

  • data-reset-on-page-change

  • description: If 'true', the launcher and the brain will be reset with every history change in SPAs
  • type: string
  • default: 'true'
  • one of:
    • 'false'
    • 'true'

  • data-auto-init

  • description: If 'false', the script won't build a launcher automatically
  • type: string
  • default: 'true'
  • one of:
    • 'false'
    • 'true'

  • data-user-info

  • description: Describes the user information to be passed as context to the brain
  • type: string
  • default: ''
  • structure: JSON.stringify({ city?: string, company?: string, country?: string, email?: string, name?: string, phone?: string, role?: string, metadata?: { [key: string]?: value: string } })

Events within the script

This script fires some events to the window scope so you can track the progress of building the launcher

window.addEventListener('salespeakLaunchersScript_ready', () => { /* handler ready status */ });
 

  • salespeakLaunchersScript_ready

  • description: It gets fired once the script is fully loaded in the page

  • salespeakLaunchersScript_pending

  • description: It gets fired once the instance to create a launcher has all the needed info and config and it is ready to start

  • salespeakLaunchersScript_initialized

  • description: It gets fired once the instance starts creating a new launcher

  • salespeakLaunchersScript_rendered

  • description: It gets fired once the instance has created a new launcher

  • salespeakLaunchersScript_removed

  • description: It gets fired once an instance gets removed (the current launcher is no longer in the page)

  • salespeakLaunchersScript_reset

  • description: It gets fired once an instance resets the created launcher

  • salespeakLaunchersScript_configChanged

  • description: It gets fired once a config gets changed

Script module

This script exposes a module and some methods so you can interact with the config and the instance of the launcher created. This module is available once the status of the script is ready salespeakLaunchersScript_ready and is located in the window scope window.salespeakLaunchersScript

window.salespeakLaunchersScript.then((salespeakLaunchersScriptModule) => {
    salespeakLaunchersScript.<<method>>();
});
 

  • config

  • description: This method can change any config of the current instance with set or get the config value with get. The changes will be visible the next time the instance is reset. The config values are defined by default with the data-<<name>> value at the script definition or the widget config
  • params: none
  • return: { get: (configName: string) => void, set: (configName: string, configValue: string) => void }
  • config names
    • autoInit => data-auto-init
    • brainURL => data-brain-url
    • campaignId => data-campaign-id
    • height => data-fixed-height + units
    • launcher => data-launcher
    • orgId => data-org-id
    • resetOnPageChange => data-reset-on-page-change
    • selector => data-selector
    • sessionId => data-session-id
    • settingsURL => data-settings-url
    • userInfo => data-user-info // no need reset
  • window.salespeakLaunchersScript.then((salespeakLaunchersScriptModule) => {
    salespeakLaunchersScript.config.set('userInfo', '{"email":"example@acme.com"}');
    
    console.log(salespeakLaunchersScript.config.get('userInfo'));

    salespeakLaunchersScript.reset();
});
     

  • destroy

  • description: Removes the launcher, the instance, and removes the script from the page
  • params: none
  • return: async () => void

  • init

  • description: Creates a new instance (if not autoInit) and builds the launcher
  • params: none
  • return: async () => void

  • remove

  • description: Removes the launcher built within the current instance
  • params: none
  • return: async () => void

  • reset

  • description: Resets the launcher built within the current instance
  • params: none
  • return: async () => void

 

If you have any questions or encounter issues while implementing these controls, feel free to contact our support team.

Related articles