Docs
Initialization Options
Configure advanced options when loading the Heyo widget.
When using the JS SDK, you can pass additional options to the init() function to control how the widget loads.
Available options
You can pass these options when initializing Heyo:
// Use either import style
import { HEYO } from '@heyo.so/js'; // or: import HEYO from '@heyo.so/js'
HEYO.init({
projectId: 'YOUR_PROJECT_ID',
hidden: true,
});
projectId
string
Your project ID. Required for localhost development, optional in production.
hidden
boolean
Start with the widget hidden. You can show it later with
HEYO.show().
Default is falselogs
string
Control the logging level for debug purposes. Options:
debug, minimal, or none.
Default is minimalProject ID
The projectId is essential for development:
HEYO.init({
projectId: '665b12a3b4c5d6e7f8g9h0i1',
});
In production, Heyo can often detect your project automatically from your domain. However, it's good practice to always include the projectId for consistency.
Hidden by default
Sometimes you want to load the widget but not show it immediately:
HEYO.init({
projectId: 'YOUR_PROJECT_ID',
hidden: true,
});
// Show it later when needed
setTimeout(() => {
HEYO.show();
}, 5000);
Logging levels
Control the amount of debug information shown in the browser console:
HEYO.init({
projectId: 'YOUR_PROJECT_ID',
logs: 'debug', // Options: 'debug', 'minimal', 'none'
});
debug: Shows all debug messages, useful for developmentminimal: Shows only important messages (default)none: Suppresses all console messages
This is particularly helpful when debugging integration issues during development.
HTML Script Attributes
If you're using the HTML script tag instead of the JS SDK, you can set these options as data attributes:
<!-- Hidden by default -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-hidden="true"></script>
<!-- With debug logging -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-logs="debug"></script>
<!-- Multiple options -->
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID" data-hidden="true" data-logs="none"></script>
Real-World Examples
Show widget only to logged-in users:
// Initialize but keep hidden
HEYO.init({
projectId: 'YOUR_PROJECT_ID',
hidden: true,
});
// Check authentication
if (user.isAuthenticated) {
HEYO.show();
HEYO.identify({
userId: user.id,
email: user.email,
name: user.name,
});
}
Different behavior for development vs production:
const isDevelopment = window.location.hostname === 'localhost';
HEYO.init({
projectId: isDevelopment ? 'YOUR_PROJECT_ID' : undefined,
hidden: isDevelopment, // Hide in development
});
Tip: The
hidden option is great for controlling when the widget appears based on user actions, page type, or authentication status.That's all the initialization options available. Use them to fine-tune how and when Heyo loads on your site.