Installation - BubblaV Documentation

Install BubblaV on any website in minutes. Choose your platform for step-by-step instructions.

Using AI Builders (Lovable, v0, Bolt, Cursor)

Building with an AI-powered tool? Copy the prompt below and paste it directly into your AI builder to integrate BubblaV automatically.

This works with Lovable, v0, Bolt, Cursor, Windsurf, and any other AI coding assistant.

Add the BubblaV AI chatbot widget to this project.

**Option 1: NPM Package (Recommended for React, Vue, Angular)**

Install:
  React:   npm install @bubblav/ai-chatbot-react
  Vue:     npm install @bubblav/ai-chatbot-vue
  Angular: npm install @bubblav/ai-chatbot-angular

Import and add to your root component or layout:

  React — import { BubblaVWidget } from '@bubblav/ai-chatbot-react';
    <BubblaVWidget websiteId="YOUR_WEBSITE_ID" />

  Vue — import { BubblaVWidget } from '@bubblav/ai-chatbot-vue';
    <BubblaVWidget website-id="YOUR_WEBSITE_ID" />

  Angular (standalone) — import { BubblaVWidgetComponent } from '@bubblav/ai-chatbot-angular';
    Add BubblaVWidgetComponent to the component's imports array, then:
    <bubblav-widget websiteId="YOUR_WEBSITE_ID"></bubblav-widget>

IMPORTANT — For Vite-based projects (Lovable, Bolt, v0, plain Vite), add this to
vite.config.ts to prevent duplicate-React conflicts:
  resolve: { dedupe: ['react', 'react-dom'] }

**Option 2: Script Tag (fallback — works with any framework)**

Add this before </body> in your main HTML or layout file:

<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

For Next.js (app/layout.tsx or pages/_app.tsx), use next/script instead:
  import Script from 'next/script';
  <Script src="https://www.bubblav.com/widget.js" data-site-id="YOUR_WEBSITE_ID" strategy="lazyOnload" />

Replace YOUR_WEBSITE_ID with the ID from your BubblaV dashboard at bubblav.com/dashboard.

After the AI applies the change, replace YOUR_WEBSITE_ID with the actual ID from your BubblaV dashboard.

Getting Your Embed Code

Open Dashboard

Go to bubblav.com/dashboard

Select Website

Click on the website you want to install

Go to Installation

Click Installation in the sidebar

Copy Code

Click Copy to copy the embed code to your clipboard

Your Embed Code

<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Your website ID is unique to your account. Never share it publicly, as it identifies your chatbot.

Using NPM Packages

For React, Vue, and Angular applications, you can use our official NPM packages for a better developer experience with type safety and framework integration.

React
Vue
Angular

React Package

Install the package:

npm install @bubblav/ai-chatbot-react
# or
yarn add @bubblav/ai-chatbot-react
# or
pnpm add @bubblav/ai-chatbot-react

Basic usage:

import { BubblaVWidget } from '@bubblav/ai-chatbot-react';

function App() {
  return (
    <BubblaVWidget
      websiteId="your-website-id"
    />
  );
}

With customization:

import { BubblaVWidget } from '@bubblav/ai-chatbot-react';

function App() {
  return (
    <BubblaVWidget
      websiteId="your-website-id"
      bubbleColor="#3b82f6"
      desktopPosition="bottom-right"
    />
  );
}

The React package is strict-mode safe and prevents double initialization. It also provides hooks for programmatic access:

import { useBubblaVWidget } from '@bubblav/ai-chatbot-react';

function SendMessageButton() {
  const widget = useBubblaVWidget();

  const handleClick = () => {
    widget?.sendMessage('Hello, I need help!');
  };

  return <button onClick={handleClick}>Get Help</button>;
}

The React package handles SSR automatically and only loads the widget script in the browser.

Vue Package

Install the package:

npm install @bubblav/ai-chatbot-vue
# or
yarn add @bubblav/ai-chatbot-vue
# or
pnpm add @bubblav/ai-chatbot-vue

Basic usage:

<script setup>
import { BubblaVWidget } from '@bubblav/ai-chatbot-vue';
</script>

<template>
  <BubblaVWidget
    website-id="your-website-id"
  />
</template>

With customization:

<script setup>
import { BubblaVWidget } from '@bubblav/ai-chatbot-vue';
</script>

<template>
  <BubblaVWidget
    website-id="your-website-id"
    bubble-color="#3b82f6"
    desktop-position="bottom-right"
  />
</template>

Using composables:

<script setup>
import { useBubblaVWidget } from '@bubblav/ai-chatbot-vue';

const widget = useBubblaVWidget();

const sendMessage = () => {
  widget.value?.sendMessage('I need help!');
};
</script>

<template>
  <button @click="sendMessage">Get Help</button>
</template>

The Vue package is SSR-safe and works with Vue 3 Composition API.

Angular Package

Install the package:

npm install @bubblav/ai-chatbot-angular
# or
yarn add @bubblav/ai-chatbot-angular
# or
pnpm add @bubblav/ai-chatbot-angular

Basic usage (standalone component):

import { Component } from '@angular/core';
import { BubblaVWidgetComponent } from '@bubblav/ai-chatbot-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [BubblaVWidgetComponent],
  template: `
    <bubblav-widget
      websiteId="your-website-id"
    />
  `
})
export class AppComponent {}

With customization:

<bubblav-widget
  websiteId="your-website-id"
  bubbleColor="#3b82f6"
  desktopPosition="bottom-right">
</bubblav-widget>

Using the service for programmatic access:

import { Component, inject } from '@angular/core';
import { BubblaVWidgetService } from '@bubblav/ai-chatbot-angular';

@Component({
  selector: 'app-support',
  template: `
    <button (click)="openChat()">Open Chat</button>
  `
})
export class SupportComponent {
  private bubblav = inject(BubblaVWidgetService);

  openChat() {
    this.bubblav.open();
  }
}

The Angular package supports Angular 14+ with standalone components and is SSR-safe.

Platform Instructions

Choose your website platform:

WordPress Installation

Option 1: Using BubblaV WordPress Plugin (Recommended)Install our official WordPress plugin for the easiest installation:

Go to Plugins

Search Plugin

Search for “BubblaV Chat” in the WordPress plugin repository

Install Plugin

Click Install Now and then Activate

Configure

Go to BubblaV Chat settings and enter your website ID

Done

The widget is automatically installed on your WordPress site

Option 2: Manual InstallationAlternatively, use a generic plugin:

Install Plugin

Go to Plugins → Add New, search for “Insert Headers and Footers”, and install it

Activate

Click Activate after installation

Open Settings

Go to Settings → Insert Headers and Footers

Paste Code

Paste your BubblaV embed code in the Scripts in Footer section

Save

Click Save to apply changes

Quickbutik Installation

Recommended: Connect with your API keyYou need edit access to a BubblaV website and a Quickbutik store whose owner can generate and use an API key.

Create or select your website

Create or select the BubblaV website for your Quickbutik storefront.

Generate an API key

Have the store owner generate an API key in Quickbutik Control Panel → Settings → API. See Quickbutik’s API authentication documentation.

Connect Quickbutik

Open that website’s Dashboard → Integrations → Quickbutik, click Connect, paste the key into Quickbutik API Key, and submit.

Check connection and installation separately

BubblaV validates the key, provisions product and order tools, and attempts to install the widget automatically. A Connected status alone does not prove that widget installation or tool provisioning succeeded.

Verify your live storefront

Open the live storefront and confirm a single chat bubble. Test a visible product keyword, then a real order number with its matching checkout email. If the widget is missing, follow the manual fallback below. Do not add another snippet over an already working widget.

Manual installation (fallback)

Copy your widget snippet

Copy the snippet from your BubblaV website’s Installation page. If using the example below, replace only YOUR_WEBSITE_ID with your website ID. Never put your API key in the snippet.

<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Back up and open your theme

Back up the Quickbutik theme, then open Utseende → Tema → Kod under huven. See Quickbutik’s template structure documentation.

Add the snippet to the shared layout

Place the snippet before the closing </body> tag of the shared storefront layout. If no shared body or layout is exposed, ask Quickbutik support for theme-specific placement instead of guessing a filename.

Apply and check the storefront

Save and apply the theme change, then check the live storefront for a single chat bubble.

Do not install a duplicate snippet over an already working widget. Manual installation adds chat only; product and order access still requires the API-key connection. Disconnecting attempts to remove API-managed scripts on a best-effort basis, but does not remove manually pasted theme code. Remove that code separately when uninstalling.

See the Quickbutik setup guide for tools, test queries, and troubleshooting.

Shopify Installation

Option 1: Using BubblaV Shopify App (Recommended)

Install the BubblaV app from the Shopify App Store
Connect your BubblaV account during setup
The widget will be automatically installed on your store
Configure the widget appearance from your Shopify admin or this dashboard

Option 2: Manual Installation (Legacy)

Open Theme Editor

Go to Online Store → Themes

Edit Code

Click the … menu on your active theme, then Edit code

Open theme.liquid

In the Layout section, click on theme.liquid

Find Body Tag

Scroll to find the closing </body> tag

Paste Code

Paste your embed code just before </body>

Save

Click Save in the top right

If you’re using a Shopify 2.0 theme, you can also add the code via Online Store → Themes → Customize → Theme settings → Custom code.

Haravan Installation

Haravan uses Liquid templating similar to Shopify. Add the widget through the theme code editor.

Access Theme Editor

Go to your Haravan admin at your-store.myharavan.com, then navigate to Website → Giao diện (Theme)

Edit Theme Code

Click on your active theme, then select Chỉnh sửa code (Edit code)

Open theme.liquid

In the Layouts folder on the left sidebar, click on theme.liquid

Find Body Tag

Scroll to the bottom of the file to find the closing </body> tag (usually around line 142)

Paste Code

Paste your BubblaV embed code just before </body>:

<!-- BubblaV Chat Widget -->
<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Save

Click Save to apply changes

Haravan’s theme structure is very similar to Shopify. The theme.liquid file in the Layouts folder is the main template that wraps all pages, making it the ideal location for the widget script.

If you prefer, you can also add the script to the footer-scripts.liquid snippet (found in the Snippets folder) if your theme uses it. However, theme.liquid is recommended as it ensures the widget loads on all pages.

Framer Installation

Option 1: Using BubblaV Framer Plugin (Recommended)

Install Plugin

In Framer, go to Plugins → Store and search for “BubblaV”

Click Install

Click Install to add the plugin to your project

Click Login & Select Website to sign in and choose your website

Customize

Adjust widget appearance in the plugin panel (optional)

Publish

Publish your site and the chatbot appears automatically

The plugin automatically creates the component in your code and adds it to your canvas with pre-configured settings. No need to copy-paste codes!

Option 2: Manual Installation

Open Site Settings

Open your Framer project and go to Site Settings

General Tab

Click on the General tab

Custom Code

Scroll down to the End of <body> tag section

Paste Code

Paste your BubblaV embed code

Save and Publish

Click Save and then Publish your site

Google Tag Manager Installation

Google Tag Manager (GTM) is one of the most popular ways to add the BubblaV widget without editing your website code. It works on virtually any website and is our recommended method when your platform doesn’t have a dedicated app.

Open Google Tag Manager

Create a New Tag

Go to Tags in the left sidebar, then click New

Configure Tag

Click on Tag Configuration, then choose Custom HTML as the tag type

Paste Widget Code

Paste your BubblaV embed code in the HTML field:

<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  defer
></script>

Set Trigger

Click on Triggering and select All Pages so the widget loads on every page

Name and Save

Name the tag “BubblaV Chat Widget” and click Save

Publish

Click Submit in the top-right corner, then click Publish to make the tag live on your site

After publishing, it may take a few minutes for changes to propagate. Open your site in an incognito window to verify the widget appears.

Make sure the GTM container snippet is installed on your website. If you haven’t set up GTM yet, follow Google’s installation guide first.

For the full step-by-step guide with troubleshooting, see Google Tag Manager.

Joomla Installation

Option 1: Using a Plugin (Recommended)

Install Plugin

Install a “Custom HTML” or “Insert HTML” extension from the Joomla Extensions Directory

Configure Plugin

Go to Extensions → Plugins and configure the plugin

Paste Code

Paste your BubblaV embed code in the footer section

Save

Save and apply changes

Option 2: Editing Template Files

Go to Extensions → Templates → Templates
Select your active template
Open index.php or footer.php
Paste the embed code before </body>
Save & Close

Drupal Installation

Option 1: Using a Module (Recommended)

Install Module

Install the “Add to Head” or similar module

Configure

Go to Configuration → Add to Head

Paste Code

Add your BubblaV embed code to the footer section

Save

Save configuration

Option 2: Editing Theme

Go to Appearance → Themes
Edit your active theme
Open html.html.twig or your template file
Paste the embed code before </body>

Developer Platforms

For custom or developer-built websites:

Static HTML

Add the script tag before the closing </body> tag:

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Your website content -->

  <!-- BubblaV Widget -->
  <script
    src="https://www.bubblav.com/widget.js"
    data-site-id="YOUR_WEBSITE_ID"
    async
  ></script>
</body>
</html>

React / Create React App

Add to your public/index.html:

<!-- In public/index.html, before </body> -->
<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Or use a component approach:

// components/BubblaVWidget.jsx
import { useEffect } from 'react';

export default function BubblaVWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://www.bubblav.com/widget.js';
    script.async = true;
    script.dataset.websiteId = 'YOUR_WEBSITE_ID';
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return null;
}

Then add to your App:

import BubblaVWidget from './components/BubblaVWidget';

function App() {
  return (
    <>
      {/* Your app content */}
      <BubblaVWidget />
    </>
  );
}

Next.js

Option 1: Using next/script (Recommended)

// app/layout.tsx or pages/_app.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://www.bubblav.com/widget.js"
          data-site-id="YOUR_WEBSITE_ID"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

Option 2: Using _document.tsx (Pages Router)

// pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <script
          src="https://www.bubblav.com/widget.js"
          data-site-id="YOUR_WEBSITE_ID"
          async
        />
      </body>
    </Html>
  );
}

Vue.js

Add to your public/index.html:

<!-- In public/index.html, before </body> -->
<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Or create a component:

<!-- components/BubblaVWidget.vue -->
<template>
  <div></div>
</template>

<script>
export default {
  name: 'BubblaVWidget',
  mounted() {
    const script = document.createElement('script');
    script.src = 'https://www.bubblav.com/widget.js';
    script.async = true;
    script.dataset.websiteId = 'YOUR_WEBSITE_ID';
    document.body.appendChild(script);
  },
  beforeUnmount() {
    const script = document.querySelector(
      'script[src="https://www.bubblav.com/widget.js"]'
    );
    if (script) script.remove();
  }
};
</script>

Angular

Option 1: Edit src/index.html (Recommended)

<!-- In src/index.html, before </body> -->
<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Option 2: Using Component

// src/app/bubblav-widget/bubblav-widget.component.ts
import { Component, OnInit, OnDestroy } from '@angular/core';

@Component({
  selector: 'app-bubblav-widget',
  template: ''
})
export class BubblaVWidgetComponent implements OnInit, OnDestroy {
  private scriptElement: HTMLScriptElement | null = null;

  ngOnInit() {
    this.scriptElement = document.createElement('script');
    this.scriptElement.src = 'https://www.bubblav.com/widget.js';
    this.scriptElement.async = true;
    this.scriptElement.setAttribute('data-site-id', 'YOUR_WEBSITE_ID');
    document.body.appendChild(this.scriptElement);
  }

  ngOnDestroy() {
    if (this.scriptElement) {
      document.body.removeChild(this.scriptElement);
    }
  }
}

Svelte

Option 1: Edit src/app.html (SvelteKit)

<!-- In src/app.html, before </body> -->
<script
  src="https://www.bubblav.com/widget.js"
  data-site-id="YOUR_WEBSITE_ID"
  async
></script>

Option 2: Create a Component

<!-- src/lib/BubblaVWidget.svelte -->
<script>
  import { onMount, onDestroy } from 'svelte';

  let scriptElement;

  onMount(() => {
    scriptElement = document.createElement('script');
    scriptElement.src = 'https://www.bubblav.com/widget.js';
    scriptElement.async = true;
    scriptElement.setAttribute('data-site-id', 'YOUR_WEBSITE_ID');
    document.body.appendChild(scriptElement);
  });

  onDestroy(() => {
    if (scriptElement) {
      document.body.removeChild(scriptElement);
    }
  });
</script>

Astro

Option 1: Using Inline Script (Recommended)Add the script directly to your main layout file (e.g., src/layouts/Layout.astro):

---
// Layout.astro
---
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Your Site</title>
  </head>
  <body>
    <slot />

    <!-- BubblaV Widget -->
    <script
      src="https://www.bubblav.com/widget.js"
      data-site-id="YOUR_WEBSITE_ID"
      defer
    ></script>
  </body>
</html>

Option 2: Using Client-Side ScriptFor more control over when the script loads:

---
// In your layout or page
---
<script is:inline>
  (function() {
    const script = document.createElement('script');
    script.src = 'https://www.bubblav.com/widget.js';
    script.setAttribute('data-site-id', 'YOUR_WEBSITE_ID');
    script.defer = true;
    document.body.appendChild(script);
  })();
</script>

Use is:inline to ensure the script runs on the client side without Astro’s bundling.

Advanced Options

Script Attributes

Customize widget behavior with data attributes:

Attribute	Values	Description
`data-site-id`	Your ID	Required. Identifies your chatbot

Excluding Pages

To hide the widget on specific pages, use the Exclude URLs setting in your Widget Design settings:

Go to Design in the sidebar
Expand the Advanced Settings section
Enter the URLs where you want to hide the widget (one per line)
You can use specific paths like https://example.com/checkout or https://example.com/admin

The widget will automatically be hidden on those pages without requiring any code changes.

Verify Installation

After adding the code, verify it’s working:

Clear Cache

Clear your browser cache or open an incognito window

Visit Your Site

Go to your website in a new tab

Look for Widget

The chat bubble should appear in the corner (usually bottom-right)

Test It

Click the bubble and send a test message like “Hello”

Check Response

You should receive a response from your AI assistant

If the widget doesn’t appear immediately, wait 1-2 minutes for caching to clear, then try again.

Troubleshooting

Widget not appearing

Widget appears but doesn't respond

Widget conflicts with other elements

Widget loads slowly

Widget not appearing on mobile

CORS or security errors

Ensure your domain matches BubblaV settings
Check for Content Security Policy restrictions
Verify HTTPS is used on your site

Content Security Policy (CSP)

If your site uses CSP headers, add these directives:

script-src 'self' https://www.bubblav.com;
frame-src 'self' https://www.bubblav.com;

Multiple Websites

If you have multiple websites:

Each website needs its own embed code
Use the unique data-site-id for each site
Install the appropriate code on each website

Using the wrong website ID will cause the widget to load with incorrect knowledge and settings.

​Using AI Builders (Lovable, v0, Bolt, Cursor)

​Getting Your Embed Code

​Your Embed Code

​Using NPM Packages

​React Package

​Vue Package

​Angular Package

​Platform Instructions

​WordPress Installation

​WooCommerce Installation

​BigCommerce Installation

​Zoho Commerce Installation

​Quickbutik Installation

​Shopify Installation

​Haravan Installation

​Wix Installation

​Squarespace Installation

​Webflow Installation

​Framer Installation

​Google Tag Manager Installation

​Joomla Installation

​Drupal Installation

​Developer Platforms

​Static HTML

​React / Create React App

​Next.js

​Vue.js

​Angular

​Svelte

​Astro

​Advanced Options

​Script Attributes

​Excluding Pages

​Verify Installation

​Troubleshooting

​Content Security Policy (CSP)

​Multiple Websites

​Next Steps

Design Your Widget

Test Your Bot

Using AI Builders (Lovable, v0, Bolt, Cursor)

Getting Your Embed Code

Your Embed Code

Using NPM Packages

React Package

Vue Package

Angular Package

Platform Instructions

WordPress Installation

WooCommerce Installation

BigCommerce Installation

Zoho Commerce Installation

Quickbutik Installation

Shopify Installation

Haravan Installation

Wix Installation

Squarespace Installation

Webflow Installation

Framer Installation

Google Tag Manager Installation

Joomla Installation

Drupal Installation

Developer Platforms

Static HTML

React / Create React App

Next.js

Vue.js

Angular

Svelte

Astro

Advanced Options

Script Attributes

Excluding Pages

Verify Installation

Troubleshooting

Content Security Policy (CSP)

Multiple Websites

Next Steps