Troubleshooting

Common issues and solutions when integrating the Cueflow embed script.

Script Not Loading

Check the Loader Script

Verify the loader script is correct:

<!-- Correct -->
<script>
(function(w,d,i){
  w.Cueflow=w.Cueflow||{q:[],
    init:function(u){this.q.push(['init',u])},
    update:function(u){this.q.push(['update',u])},
    track:function(e,p){this.q.push(['track',e,p])},
    check:function(){this.q.push(['check'])},
    shutdown:function(){this.q.push(['shutdown'])}
  };
  var s=d.createElement('script');s.async=1;
  s.src='https://script.cueflow.so/embed/cueflow.js';
  s.setAttribute('data-workspace-id',i);
  d.head.appendChild(s);
})(window,document,'YOUR_WORKSPACE_ID');
</script>

Verify Workspace ID

1. Go to the Developer Guide page in the Cueflow dashboard

2. Copy the Workspace ID from the embed script code

3. Make sure it matches data-workspace-id exactly

Check Console Errors

Open browser DevTools (F12) and check the Console tab for errors:

Error	Cause
404 Not Found	Script URL is incorrect
CORS error	Script blocked by browser security
workspace-id not found	Missing data-workspace-id attribute

---

Messages Not Showing

1. Verify Initialization

Make sure init() is called with a valid user ID:

// Check in console
console.log(window.Cueflow); // Should exist

// Initialize
Cueflow.init({
  id: 'user-123',  // Required!
  email: '[email protected]'
});

2. Check Targeting Rules

Messages only show when targeting rules match:

1. Go to your message in the Cueflow dashboard

2. Check the Targeting tab

3. Verify the current user matches the rules

Common issues:

• Message targeting plan equals "pro" but user has plan: "free"

• Page targeting /dashboard but user is on /home

• Event targeting feature_used has done but event wasn't tracked

3. Verify Message Status

Only Published messages are shown:

1. Go to the message in the dashboard

2. Check status is "Published" (not "Draft" or "Archived")

4. Check Dismissals

If a user dismissed a message, it won't show again:

• For testing, use a different user ID

• Or create a new message

5. Test with Minimal Targeting

Create a test message with no targeting rules to verify the embed works:

1. Create a new banner

2. Leave targeting rules empty (shows to everyone)

3. Publish the message

4. Refresh your page

---

"Already initialized" Warning

You're calling init() more than once:

// Wrong - called twice
Cueflow.init({ id: 'user-123' });
Cueflow.init({ id: 'user-123' }); // Warning!

// Correct - call init once, use update for changes
Cueflow.init({ id: 'user-123', plan: 'free' });
Cueflow.update({ plan: 'pro' }); // Update later

SPA Page Transitions

If you're reinitializing on page transitions, restructure your code:

// Wrong - in a component that remounts
useEffect(() => {
  Cueflow.init({ id: user.id }); // Called on every mount
}, []);

// Correct - at app root, runs once
// _app.js or layout.js
useEffect(() => {
  if (user) {
    Cueflow.init({ id: user.id });
  }
  return () => Cueflow.shutdown();
}, [user?.id]);

---

"Not initialized" Warning

You're calling methods before init():

// Wrong - track before init
Cueflow.track('page_view');
Cueflow.init({ id: 'user-123' });

// Correct - init first
Cueflow.init({ id: 'user-123' });
Cueflow.track('page_view');

track() calls made immediately after init() are queued automatically. The warning appears if you call other methods like update() or check() before init.

---

Messages Not Updating on Navigation

SPA Navigation

Cueflow listens for pushState, replaceState, and popstate. If your router uses a different mechanism:

// After custom navigation
customRouter.navigate('/new-page');
Cueflow.check(); // Manually trigger check

Hash Routing

For hash-based routing:

window.addEventListener('hashchange', () => {
  Cueflow.check();
});

---

Styling Issues

Messages Behind Other Elements

Cueflow uses high z-index values, but your app might have higher ones:

/* If needed, increase z-index in your CSS */
.cueflow-banner { z-index: 99999 !important; }
.cueflow-modal-overlay { z-index: 99999 !important; }

Styles Not Applied

Check if you have CSS resets affecting Cueflow:

/* Aggressive reset affecting Cueflow */
* {
  all: unset; /* This breaks Cueflow styles */
}

/* Better - exclude Cueflow elements */
*:not([class^="cueflow-"]) {
  /* your reset */
}

Modal/Banner Size Issues

Cueflow respects box-sizing. If you have global box-sizing rules, they may affect message dimensions.

---

Events Not Tracking

Verify Event is Being Called

// Add logging to verify
console.log('Tracking event...');
Cueflow.track('feature_used', { feature: 'export' });

Check Network Tab

1. Open DevTools > Network

2. Filter by "cueflow" or "track"

3. Look for the POST request

4. Check response status (should be 200/201)

Verify Event Key

Event keys are case-sensitive and should match exactly:

// In your code
Cueflow.track('Feature_Used'); // Wrong case

// In targeting rules
// Event "feature_used" has done  // Won't match!

---

TypeScript Errors

Window.Cueflow Type

Add type declarations:

// types/cueflow.d.ts
interface CueflowUser {
  id: string;
  email?: string;
  name?: string;
  [key: string]: unknown;
}

interface CueflowAPI {
  init(user: CueflowUser): void;
  update(data: Partial<CueflowUser>): void;
  track(event: string, properties?: Record<string, unknown>): void;
  check(): void;
  shutdown(): void;
}

declare global {
  interface Window {
    Cueflow: CueflowAPI;
  }
}

export {};

Script Tag in React/Next.js

// Add to layout.tsx (runs once)
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script id="cueflow" strategy="afterInteractive">
          {`(function(w,d,i){
            w.Cueflow=w.Cueflow||{q:[],
              init:function(u){this.q.push(['init',u])},
              update:function(u){this.q.push(['update',u])},
              track:function(e,p){this.q.push(['track',e,p])},
              check:function(){this.q.push(['check'])},
              shutdown:function(){this.q.push(['shutdown'])}
            };
            var s=d.createElement('script');s.async=1;
            s.src='https://script.cueflow.so/embed/cueflow.js';
            s.setAttribute('data-workspace-id',i);
            d.head.appendChild(s);
          })(window,document,'YOUR_WORKSPACE_ID');`}
        </Script>
      </body>
    </html>
  );
}

---

Testing Tips

Use Different User IDs

For testing dismissed messages or fresh state:

// Use a new test ID
Cueflow.init({
  id: `test-${Date.now()}`,
  email: '[email protected]'
});

Test Specific Targeting

Target a message to your email for testing:

1. Add rule: email equals "[email protected]"

2. Test the message

3. Remove the rule before going live

Console Debugging

// Check if Cueflow is loaded
console.log('Cueflow available:', !!window.Cueflow);

// Check initialization status (internal)
// Note: Not all internal state is exposed

---

Getting Help

If you're still having issues:

1. Check browser console for specific error messages

2. Check network tab for failed API requests

3. Verify workspace ID matches your dashboard

4. Test with a simple message (no targeting rules)

Contact support with:

• Browser and version

• Framework (React, Vue, etc.)

• Console errors (screenshots)

• Network request failures