BadgerFy.ai Docs

Installation Guide

Add BadgerFy.ai to your website in minutes. Choose your platform below for step-by-step instructions. You'll find your Project ID in the BadgerFy.ai dashboard under your project settings.

ℹī¸ Note: Replace YOUR_PROJECT_ID in all examples with your actual Project ID from the BadgerFy.ai dashboard.

Static Website / Manual Installation

For static HTML websites, simply add our script tag to your pages. This works with any HTML-based website including custom builds, WordPress, and other CMS platforms.

Basic Installation

Add this script tag just before the closing </body> tag on every page where you want BadgerFy.ai to appear:

<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>

Full HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <!-- Your website content -->
  <h1>Welcome to my store</h1>


  <!-- BadgerFy.ai Script - Add before </body> -->
  <script
    src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
    data-project-id="YOUR_PROJECT_ID"
    async
  ></script>
</body>
</html>

Next.js Installation

For Next.js applications, use the built-in Script component for optimal loading performance. This approach ensures the script loads after the page becomes interactive, improving your Core Web Vitals.

Create a BadgerFy Component

Create a new component file (e.g., components/BadgerfyEmbed.js):

import Script from 'next/script';


export default function BadgerfyEmbed() {
  return (
    <Script
      src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
      data-project-id="YOUR_PROJECT_ID"
      strategy="afterInteractive"
    />
  );
}

Add to Your Layout

Import and add the component to your root layout or any page layout:

import BadgerfyEmbed from '../components/BadgerfyEmbed';


export default function Layout({ children }) {
  return (
    <>
      <header>{/* Your header */}</header>
      
      <main>{children}</main>
      
      <footer>{/* Your footer */}</footer>
      
      {/* BadgerFy.ai Embed */}
      <BadgerfyEmbed />
    </>
  );
}
💡 Tip: Using strategy="afterInteractive" ensures the script loads after the page becomes interactive, which is recommended for third-party scripts.

Shopify Installation

Add BadgerFy.ai to your Shopify store through the theme editor.

Installation Steps

  1. Log in to your Shopify admin panel
  2. Go to Online Store → Themes
  3. Click Actions → Edit code on your current theme
  4. In the Layout folder, click on theme.liquid
  5. Find the closing </body> tag
  6. Paste the following code just before it:
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
  1. Click Save
  2. Visit your storefront to verify the agent appears

BigCommerce Installation

Add BadgerFy.ai to your BigCommerce store using Script Manager or direct file editing.

Option A: Using Script Manager (Recommended)

  1. Go to Storefront → Script Manager
  2. Click Create a Script
  3. Fill in the details:
    • Name: BadgerFy.ai
    • Location: Footer
    • Pages: All Pages (or select specific pages)
    • Script type: Script
  4. Paste the script code:
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
  1. Save your changes

Option B: Edit Theme Files

  1. Go to Storefront → Themes → Advanced → Edit Theme Files
  2. Navigate to templates/layout/base.html
  3. Add the script before the closing </body> tag
  4. Save the file

Adobe Commerce / Magento Installation

Add BadgerFy.ai to Adobe Commerce (Magento) through the admin panel or theme files.

Option A: Using Admin Panel (Recommended)

  1. Log in to your Magento Admin Panel
  2. Navigate to Content → Design → Configuration
  3. Select your store view and click Edit
  4. Expand the Footer section
  5. In the Miscellaneous Scripts field, paste:
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
  1. Save the configuration
  2. Clear the cache: System → Cache Management → Flush Magento Cache

Option B: Edit Theme Template

For more control, add the script to your theme's template file:

  1. Navigate to your theme folder: app/design/frontend/[Vendor]/[Theme]/
  2. Create or edit Magento_Theme/templates/html/scripts.phtml
  3. Add the script code
  4. Update your layout XML to include the template before </body>
  5. Clear cache and deploy static content
⚠ī¸ Important: Always clear Magento's cache after making changes. Run bin/magento cache:flush from the command line.

WooCommerce Installation

Add BadgerFy.ai to your WooCommerce store through your WordPress theme or using a plugin.

Option A: Edit Theme (Recommended)

  1. Log in to your WordPress admin panel
  2. Go to Appearance → Theme File Editor
  3. Select your active theme and find footer.php
  4. Add the following code just before the closing </body> tag (or before <?php wp_footer(); ?>):
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
  1. Click Update File

Option B: Using functions.php

For a more robust solution that survives theme updates, add the script via your theme's functions.php:

// Add BadgerFy.ai script to footer
function add_badgerfy_script() {
    ?>
    <script
      src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
      data-project-id="YOUR_PROJECT_ID"
      async
    ></script>
    <?php
}
add_action('wp_footer', 'add_badgerfy_script');

Option C: Using a Plugin

If you prefer not to edit theme files, you can use a plugin like Insert Headers and Footers or WPCode:

  1. Install and activate a code snippet plugin (e.g., WPCode)
  2. Create a new snippet and set it to run in the Footer
  3. Paste the BadgerFy.ai script code
  4. Save and activate the snippet
💡 Child Theme: If you're editing theme files directly, consider using a child theme to preserve your changes during theme updates.

Wix Installation

Add BadgerFy.ai to your Wix website using the Custom Code feature in site settings.

Installation Steps

  1. Log in to your Wix account and open your site editor
  2. Click Settings in the left sidebar
  3. Select Custom Code under Advanced Settings
  4. Click + Add Custom Code
  5. Paste the following code:
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
  1. Configure the code placement:
    • Name: BadgerFy.ai
    • Add Code to Pages: All pages (or select specific pages)
    • Place Code in: Body - end
  2. Click Apply
  3. Publish your site to see the changes
ℹī¸ Premium Required: Adding custom code on Wix requires a Premium plan. The feature is not available on free Wix sites.

Squarespace Installation

Add BadgerFy.ai to your Squarespace site using Code Injection in your site settings.

Installation Steps

  1. Log in to your Squarespace account
  2. Go to Settings → Advanced → Code Injection
  3. In the Footer section, paste the following code:
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
  1. Click Save
  2. Visit your live site to verify the installation

Page-Specific Installation

To add BadgerFy.ai to specific pages only:

  1. Edit the page where you want BadgerFy.ai to appear
  2. Click the gear icon to open Page Settings
  3. Go to the Advanced tab
  4. Paste the script in the Page Header Code Injection field (it will still load in the correct position)
  5. Save the page settings
ℹī¸ Business Plan Required: Code Injection on Squarespace requires a Business plan or higher. It's not available on Personal plans.

Verifying Your Installation

After installing the script, verify it's working correctly:

  1. Visit your website in a browser
  2. Open the browser's Developer Tools (F12 or right-click → Inspect)
  3. Go to the Network tab and filter by "badgerfy"
  4. Refresh the page and confirm the script loads successfully
  5. If you have an enabled agent configured for that page, it should appear
💡 Test Mode: For local testing, add data-test-mode="true" to your script tag. This enables test mode which loads disabled agents and provides detailed console logging.
⚠ī¸ Test Mode Limitations:
  • Test mode only works on localhost — it will not function on production or staging servers.
  • Performance may be slower due to uncached data lookups.
  • AI generations in test mode will consume tokens from your plan allocation.

Lifecycle Callbacks

BadgerFy.ai provides optional lifecycle callbacks that you can use to integrate with your application's logic. Define these in your configuration before the script loads.

onLoad Callback

The onLoad callback fires when BadgerFy.ai has fully loaded and initialized. Use this to trigger actions that depend on BadgerFy.ai being ready.

<script>
  window.badgerfyaiConfig = {
    onLoad: () => {
      console.log('BadgerFy.ai is ready!');
      
      // Access the BadgerFy.ai API
      const agents = window.badgerfyai.getAgents();
      console.log('Active agents:', agents);
    }
  };
</script>


<!-- BadgerFy.ai Script - Load AFTER config -->
<script
  src="https://app.badgerfy.ai/embeds/badgerfy.min.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>

onEngagement Callback

The onEngagement callback fires whenever a user engagement is recorded. This allows you to react to engagements in real-time, such as sending data to your analytics platform or triggering custom logic.

window.badgerfyaiConfig = {
  onEngagement: ({ agentId, agentType, engagementAction, pagePath }) => {
    console.log('User engaged!', { agentId, agentType, engagementAction });
    
    // Example: Send to Google Analytics 4
    gtag('event', 'badgerfy_engagement', {
      agent_id: agentId,
      agent_type: agentType,
      engagement_action: engagementAction,
      page_path: pagePath
    });
  }
};

The onEngagement callback receives an object with the following properties:

  • agentId - The unique identifier of the agent
  • agentType - The type of agent (assistant, quiz, nudge, recommendation-strip)
  • engagementAction - The action that triggered the engagement (e.g., chat-engagement, quiz-completed, nudge-cta-click, product-clicked)
  • pagePath - The page path where the engagement occurred
ℹī¸ Learn More: For detailed information about engagement tracking and conversion attribution, see the Conversion Tracking guide.