How to Install Bubblegum: Web Manager Guide (Cloudflare Edition)

If you have any questions throughout this set up process, feel free to book a meeting here, message us in slack (or join our slack), or email us at [email protected].

---

Introduction

Modern AI tools like ChatGPT, Perplexity, and Claude are becoming key discovery engines — crawling, interpreting, and recommending brand content. To ensure these tools interpret your site accurately, Bubblegum offers a lightweight middleware solution built on Cloudflare.

This comprehensive guide covers the complete setup and deployment process for Bubblgum Middleware. This solution leverages Cloudflare's edge computing capabilities to seamlessly direct AI agent traffic to structured, machine-readable content while maintaining normal user experiences.

---

What is Middleware?

AI agents are now an important segment of web traffic, discovering, indexing, and interacting with your digital content. This middleware acts as an intelligent router – seamlessly directing recognized AI bot traffic to AI-optimized, relevant pages while serving regular visitors as normal.

For e-commerce brands, this middleware integrates with Shopify's Cloudflare O2O (Online-to-Offline) capability, enabling advanced traffic management and optimization.

What are the key benefits?

• AI Traffic Middleware: Detects AI bots using advanced user-agent filtering and pattern recognition

• Seamless Routing: AI or LLM bot requests are routed to special "AI-ready" content (Markdown, structured data endpoints, etc.) set by your team

• Multi-model Ready: Routes can be adapted or extended for different bot types (OpenAI, GoogleBot-AI, Perplexity, Claude, social/chat bots, etc.)

• No Impact on UX or SEO: Human visitors and standard search engine crawlers are unaffected.

• Comprehensive Logging: All routes, bot hits, and errors are logged for analytics

---

How It Works

1

Interception

The Cloudflare Worker sits between your domain and all incoming traffic

2

Bot Detection

Each request's user-agent (and optionally headers) are checked against a curated list of bot patterns, including major LLMs, scrapers, and headless browsers

3

Dynamic Routing

• AI bot requests: Redirected to an AI-ready version of the content (e.g., /about becomes /about.md)

• Non-bot traffic: Served as usual with no disruption or latency

4

Custom Patterns

Easily extend detection rules for emerging bots or proprietary assistants

5

Technical Stack

• Deployed as a Cloudflare Worker (via Wrangler CLI)

• Handles GET, POST, and all HTTP verbs

---

Setup Instructions

Please note that if you do not yet use Cloudflare, you'll need to set up an account to set up Bubblegum middleware.

Phase 1: Initial Cloudflare Account Setup

If you already use Cloudflare to manage your domain, you can SKIP to Phase 2

Before beginning the setup process, ensure you have:

• Access to your domain's DNS management

• Administrative access to create or manage Cloudflare account

• Understanding of nameserver configuration

• Basic familiarity with DNS concepts

Step 1: Setup Cloudflare Account

Cloudflare provides the foundation for Bubblegum's middleware deployment. The account setup process involves domain registration, plan selection, and initial configuration.

Start by creating an account if you don’t have one - or log into existing account if you already manage your domain in Cloudflare.

Why We Ask You to Move Nameservers to Cloudflare

To unlock all the performance, protection, and AI-routing benefits of Bubblegum, your site’s nameservers need to be pointed to Cloudflare. This is a one-time setup that allows Cloudflare to securely manage how traffic reaches your site — including helpful traffic like shoppers or search engines, as well as newer visitors like AI bots.

Simple Explanation: What’s a Nameserver?

Nameservers are like the internet’s GPS — they tell browsers where to find your website.

When you point your nameservers to Cloudflare, you’re allowing Cloudflare to help direct that traffic safely and intelligently.

What Your Shoppers Will Notice:

Nothing changes on the outside. Your website will look and work the same as always — just with better speed, security, and visibility for AI shoppers.

Please note that your DNS settings will now be managed through Cloudflare rather than your original domain provider so please save your login information.

Your domain annual auto-renewal will still be managed in your original provider.

Step 2: Add Domain to Cloudflare

Once logged in you can click on the Add button in the top right → Connect a domain

This process will scan your existing DNS records and prepare them for migration to Cloudflare's infrastructure.

1. Enter domain in the first text input box

2. Keep the default selected option: Quick Scan for DNS records

3. Select “Do not block (off)” AI training bots

4. Click on continue

Step 3: Select Workers Paid Plan

While the free plan can technically support smaller sites, it’s very likely the limits would be exceeded quickly. If that happens, the middleware would just show the human version of the page to AI visitors by default - which we don’t want to happen.

Step 4: Domain Activation Process

After plan selection, you'll need to activate your domain by updating nameservers. This is a critical step that transfers DNS management to Cloudflare.

Important: Before moving to domain activation, confirm all DNS records and ensure you do not enable proxying (the orange cloud) for any records that need to be verified by third-party providers. (For example: CNAME records required by Attentive, Klaviyo, SendGrid, and similar ESP providers).

These records must remain “DNS only” (grey cloud) until their verification process completes. Proxying these records during verification may result in blocked validation.

Why: Cloudflare’s proxy can obscure DNS records, preventing third-party platforms from properly verifying domain ownership or email sending. Making this check before activating the domain will avoid delays and ensure all necessary integrations are successful.

Step 5: Nameserver Configuration

Update nameservers at your domain registrar to point to Cloudflare's nameservers.

This step is crucial for middleware functionality. You'll need to:

1. Follow on-screen instructions for your specific domain provider

2. Use provider-specific guides: Consult the official nameserver update documentation for detailed instructions

How to Set This Up If You Use GoDaddy

• Go to my products from the user menu in the top right

• Scroll to your domain and click DNS

  

• Click on domain settings

  

How to Set This Up If You Use Another Provider

• You can find provider specific instructions in the links in the dropdown under “Your domain uses a different registrar”.

1. Verify propagation using DNS checking tools

   1. Important: DNS propagation can take up to 24-48 hours. The middleware cannot function until nameservers are fully propagated.

Your DNS settings will be managed through Cloudflare going forward rather than your original domain provider so please save your Cloudflare login information (easiest to login with your email provider like Gmail).

Other software platforms often ask you to edit DNS records, so you'll need access to do so in the future.

Your domain annual auto-renewal will still be managed in your original provider.

Step 6: Verification and Confirmation

Once nameserver changes are made:

1. Click "Continue" in the Cloudflare dashboard

2. Use the "Check nameservers" function

3. Wait for confirmation that changes have propagated

4. Verify that your domain is "Active" in Cloudflare

If you have any questions throughout this set up process, feel free to book a meeting here, message us in slack (or join our slack), or email us at [email protected].

---

Phase 2: API Token Creation and Configuration

Understanding API Tokens vs API Keys

Cloudflare API tokens provide more granular security than legacy API keys. Tokens can be scoped to specific resources and operations, following the principle of least privilege.

Step 1: Access API Token Management

Navigate to Account API Tokens in your Cloudflare dashboard.

Step 2: Token Template Selection

For middleware deployment, use the "Edit Cloudflare Workers" template, which provides the necessary permissions:

No changes are needed to the permissions of this template.

Step 3: Zone Specification

Configure the token to be scoped to your specific domain zone. This enhances security by limiting the token's scope to only the necessary resources.

Zone Configuration:

• Include: Specific zone (your domain)

• Resource scope: Limited to target domain only

• IP address filtering: Optional but recommended for enhanced security

Once done, click on continue and then send the token to [email protected] or in our shared slack channel.

Step 4: Account ID Retrieval

The Account ID is required for Worker deployment. You can find it in your Cloudflare dashboard URL:

<https://dash.cloudflare.com/{ACCOUNT_ID}/home/domains>

Send the Account ID to [email protected] or in our shared slack channel.

Step 5: Add Bubblegum to Cloudflare Account

1. Log in to the Cloudflare dashboard.

2. Select your account.

3. Go to Manage Account → Members.

4. Click Invite.

5. Enter [email protected]

6. Select access scope (recommended: choose the specific domain/zone if possible).

7. Assign the Super Administrator role, which allows:

   • Deploying/managing Workers

   • Editing routing rules, middleware, and settings

   • Managing DNS records

8. Continue to summary and complete the invite.

If you want to give Bubblegum a more limited role, you must allow at least the following

Required permissions:

• Zone: Settings: Edit

• Zone: Read

• DNS: Edit

• Account: Cloudflare Workers: Edit

---

Phase 3: DNS Configuration for Middleware

Understanding DNS Routing for Middleware

Proper DNS configuration is essential for middleware functionality. The middleware intercepts traffic at the edge before it reaches your origin server.

DNS Record Configuration

Set up CNAME records in Cloudflare DNS management:

For E-commerce/Shopify Integration:

• Root/apex domain: example.com → shops.myshopify.com (Proxied: ON)

• WWW subdomain: www.example.com → shops.myshopify.com (Proxied: ON)

Important Notes:

• Proxy Status: Must be set to "Proxied" (orange cloud) for middleware to function

• Existing Records: You do not need to remove existing Shopify-created DNS records

• Precedence: Cloudflare's proxy will handle routing appropriately

Verification Steps

1. DNS Propagation Check: Use tools like dig or online DNS checkers

2. Proxy Status Verification: Ensure orange cloud icon is active

3. SSL Certificate: Verify SSL/TLS is properly configured

4. Origin Connectivity: Test that your origin server is reachable

These setup instructions are based on the official Cloudflare for Shopify O2O documentation.

To learn more about the Shopify and Cloudflare integration, or to explore additional options and guidance, please refer to the official documentation.

If you have any questions throughout this set up process, feel free to book a meeting here, message us in slack (or join our slack), or email us at [email protected].

---

Frequently Asked Questions:

Q: Can I customize bot traffic destinations?

A: Yes. The middleware is fully configurable. You can define which AI-ready content (like Markdown files or structured endpoints) each AI bot should be routed to, allowing for granular control by page or bot type.

Q: How does the new markdown content work with our existing website and code?

A: You don’t need to change your site or code. We use something called “middleware” that runs through Cloudflare. It simply detects if a request is coming from a bot (like ChatGPT or Perplexity) and, if so, shows them your AI-optimized content. Regular visitors still see your usual site.

Q: Can I see which AI bots are visiting my storefront and what pages they access?

A: Yes. All bot hits and route matches are logged by the middleware. You can use this data to analyze AI bot traffic patterns, page-level access, and even export this for analytics dashboards.

Q: How do I test the routing for different types of AI bots before going live?

A: You can simulate bot traffic by using tools like curl or Postman and setting the User-Agent header to match known AI bots (e.g., ChatGPT, Claude, PerplexityBot). This allows you to verify detection and routing without deploying to production.

Q: Can I segment analytics to see where AI-driven purchases or conversions originate?

A: Yes, if you integrate the middleware logs with downstream analytics tools (e.g., Segment, GA4, or custom attribution systems), you can isolate AI-sourced traffic and measure downstream conversions or revenue impact.

Q: What happens if a bot is misidentified or a legitimate customer is mistaken for an AI bot?

A: The bot detection logic is carefully curated and updated to minimize false positives. In the rare case of misidentification, fallback behavior is non-disruptive—most misrouted users would still see product content, just via the AI-ready page.

Q: How does this work with my existing CDN, headless commerce platform, or CMS?

A: The middleware runs at the Cloudflare edge, before any request reaches your origin or CMS. This means it is compatible with any platform (e.g. Shopify, Contentful, Sanity, BigCommerce) without needing backend changes.

Q: Are there risks to privacy or customer data when directing bot traffic?

A: No. The middleware only affects bots—it does not expose any private customer data or session-specific content. AI-ready pages are typically static or structured summaries, ensuring privacy is maintained.