Getting started
Installing Ybug on your site
Ybug's code is asynchronous and is designed not to slow down your site.
When you create a project in Ybug, you'll be sent an email with code snippet to add to your website. Alternatively you can get your code snippet in your dashboard. Simply copy this code and paste it into your website just above the closing </body>
tag.
Your code should look something like this:
<!-- Ybug code start (https://ybug.io) -->
<script type='text/javascript'>
(function() {
window.ybug_settings = {"id":"XXXXXXXXX"};
var ybug = document.createElement('script'); ybug.type = 'text/javascript'; ybug.async = true;
ybug.src = 'https://widget.ybug.io/button/'+window.ybug_settings.id+'.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ybug, s);
})();
</script>
<!-- Ybug code end -->
Just replace XXXXXXXXX with your project id.
If you're using a JavaScript framework, you can install our Vue, React or Angular npm packages to easily integrate Ybug in your projects.
Looking for instructions for most common web platforms? WordPress, Shopify, Webflow, Bubble .
Browser extensions
If you need pixel perfect screenshots or if you would like to get feedback and bug reports from your testers and team members, our browser extensions are perfect for this use case.
Passing user information
You might want to pass user information to Ybug. It may then help you identify the user who sent feedback. You can pass basically any additional user information you want, it even does not have to be strictly user related.
To add some context, you could for example pass an internal identifier of the application, application build/version, environment (e.g. "DEV", "QA", "PROD"), etc.
window.ybug_settings = {
id:'XXXXXXXXX',
user: {
id: '112233445566',
username: 'john-doe'
// any other info you need to add context
}
};
If you need to change user data (ie when your user logs in), you can call Ybug.setUser()
method.
Ybug.setUser({
id: 'XYZ',
// ...
});
Feedback default values
You can prefill feedback form with some default values:
window.ybug_settings = {
id: 'XXXXXXXXX',
feedback: {
comment: 'Winter is coming...',
rating: 5,
email: '[email protected]',
name: "Jon Snow"
}
};
Sensitive data protection
We take privacy and security very seriously. Ybug automatically anonymizes the following fields to avoid transmitting any personal data to our server:
- Password fields
- Any input field values that look like they contain credit cards (using a basic regular expression)
- Any input fields with the name attribute containing words such as "password", "token", "key", "secret", "card", "cvv" and their variations
To provide more security in addition to automatic anonymization, you can mark any input fields or html elements as sensitive by adding data-ybug-sensitive
attribute to the element in your code.
<div data-ybug-sensitive>
My sensitive information that will be anonymized
</div>
<input type="email" data-ybug-sensitive value="myemail" />
You can also provide a comma separated list of HTML ids/classes to identify elements that contain sensitive data and should be anonymized.
The list can be added as option anonymize_elements
to your ybug_settings object:
window.ybug_settings = {
id: 'XXXXXXXXX',
anonymize_elements: '#my-super-secret, .tokens .api_token', // comma separated list of ids/classes of elements on your page containing sensitive data
};
Anonymization is performed by Javascript in the browser to avoid transmitting any personal data to our servers.
Setting the language
Ybug automatically detects which language to use for current user.
You can however override this behavior simply by adding option language_override
to your ybug_settings object:
window.ybug_settings = {
id:'XXXXXXXXX',
language_override: 'fr' // Replace with preferred language of your user
};
Currently supported languages are:
- Bulgarian (
bg
) - Chinese (
zh
) - Croatian (
hr
) - Czech (
cs
) - Danish (
da
) - English (
en
) - Estonian (
et
) - Finnish (
fi
) - French (
fr
) - German (
de
) - Greek (
el
) - Hungarian (
hu
) - Italian (
it
) - Japanese (
ja
) - Latvian (
lv
) - Lithuanian (
lt
) - Nederlands (
nl
) - Norwegian (
no
) - Polish (
pl
) - Portuguese (Brazilian) (
pt-BR
) - Romanian (
ro
) - Russian (
ru
) - Slovak (
sk
) - Slovenian (
sl
) - Spanish (
es
) - Swedish (
sv
) - Turkish (
tr
) - Ukrainian (
uk
)
Is your language missing from this list? Contact us, we will be happy to add another translation.
Opening Ybug programmatically
Ybug normally opens when someone clicks on the launcher button in the bottom right corner.
If you want to open it on some other event though, you can add a small snippet of code to any element of your project. This way you can implement your own custom launcher button.
With markup
<a href="#" data-ybug="open">Feedback</a>
Example: Your feedback
You can also hide standard Ybug launcher button by passing hide_launcher: true
in the ybug_settings object:
window.ybug_settings = {
id:'XXXXXXXXX',
hide_launcher: true
};
If you need to skip welcome step and open feedback form directly, just pass additional skip_to: 'feedback'
in the ybug_settings
With Javascript
Ybug also provides some simple Javascript API, you can use Ybug.open()
and Ybug.close()
methods to control Ybug widget programmatically.
// Open the widget
Ybug.open();
// Open the feedback form
Ybug.open('feedback');
// Close the widget :-)
Ybug.close();
If you need to open any particular feedback step, just pass additional parameter to open method: Ybug.open('feedback')
.
Example: Open feedback form or even Open annotate tool.
Keyboard shortcut
It is also possible to use a Alt+Y
keyboard shortcut for opening Ybug widget. Shortcut must be enabled by passing shortcut: true
in the ybug_settings object.
window.ybug_settings = {
id:'XXXXXXXXX',
shortcut: true
};
Launcher position
You can position the Ybug launcher button on the bottom right, bottom left and middle right, middle left and top middle sides of the page.
The launcher_position
attribute can have these possible values: bottom-right
(which is the default value), bottom-left
, right-middle
, left-middle
and top-middle
.
window.ybug_settings = {
id:'XXXXXXXXX',
launcher_position: 'bottom-right' // change to bottom-left, right-middle, left-middle or top-middle
};
Widget position
Our Feedback Widget is positioned automatically based on the launcher position. If you set the launcher position to be on the left side of the screen, the widget opens on the left side as well. If you set the launcher position to top-middle
, then the widget opens in the center.
You can change the default behavior and set the widget position yourself using the widget_position
setting.
The widget_position
attribute can have these possible values: right
, left
and center
.
window.ybug_settings = {
id:'XXXXXXXXX',
widget_position: 'center' // change to left, center, right
};
Javascript API
Open widget
As mentioned earlier, you can use Ybug.open()
to open the Feedback Widget.
// Open the default widget screen
Ybug.open();
// Open the feedback form (skipping the welcome screen)
Ybug.open('feedback');
// Open the annotation page
Ybug.open('annotate');
Close widget
To close the widget if it's already open, use Ybug.close()
:
// Close opened widget
Ybug.close();
Hide widget
To hide the widget on certain pages, you can use Ybug.hide()
. If you specify 'launcher'
as the first argument, you can hide only the launcher button.
// Hide the widget or launcher
Ybug.hide();
// Hide launcher (if visible)
Ybug.hide('launcher');
Show widget
To show the widget if you have previously hidden it, use Ybug.show()
. If you specify 'launcher'
as the first argument, you can show only the launcher button.
// Show the widget or launcher
Ybug.show();
// Show launcher (if hidden previously)
Ybug.show('launcher');
Destroy widget
To entirely unmount the widget on certain pages, use Ybug.destroy()
API call. This call destroys both widget and launcher:
// Unmount the Feedback Widget
Ybug.destroy();
Initialize widget
To initialize the Feedback Widget if you have previously unmounted it, please use Ybug.boot()
. There is no need to call this on a usual page load, use it only when you called Ybug.destroy()
before.
// Initialize the widget again
Ybug.boot();
Javascript events
Ybug triggers some lifecycle events, to which you can register listeners easily, either by calling Ybug.on(event, callback)
or directly in your configuration object.
Event | Description |
---|---|
load |
Triggers when Ybug is fully loaded and ready. |
open |
Open event is triggered right after the Feedback widget is opened. |
beforesend |
Beforesend event is triggered before sending the feedback report to Ybug servers. You can use this event to modify submitted report.
A json object with report data is passed to the beforesend event handler.
New If you return a Promise from your event handler, the feedback report will not be sent until the Promise resolves. If the Promise resolves with FALSE, the feedback will not be sent. This way, you can cancel the feedback sending operation if needed. |
aftersend |
Aftersend event is triggered after the feedback report is sent to Ybug servers.
A json object with report data is passed to the aftersend event handler with two additional properties available for the new report - id (report key) and reportUrl for the report detail page in the dashboard.
|
cancel |
Triggers when the Feedback widget is closed without submitting the report (by clicking the Cancel button or pressing ESC). |
close |
Triggers every time the Feedback widget is closed (even when cancelled). |
Register your event listeners in the configuration object:
window.ybug_settings = {
id:'XXXXXXXXX',
onload: function() {
console.log('Ybug loaded and ready');
},
onopen: function () {
console.log('Ybug opened');
},
onbeforesend: function (report) {
console.log('Before report is sent', report);
// You can modify the feedback report here
report.title = 'Modified title: ' + report.title;
// If you need to perform some async actions, you can return a Promise
return new Promise(resolve => {
// Do some async work...
let agreed = confirm('Do you agree to our Terms and Conditions?');
resolve(agreed); // if you resolve with false, the feedback will not be sent
});
},
onaftersend: function(report) {
// Feedback report was sent! We have id and reportUrl available now
console.log(`Feedback with an ID ${report.id} was sent. Go to ${reportUrl} for details!`);
},
oncancel: function () {
console.log('Feedback cancelled');
},
onclose: function () {
console.log('Feedback widget closed');
},
};
Or you can register your event listeners by calling Ybug.on(event, callback)
.
Please note, that you can use Ybug.on
method only after Ybug has successfully loaded. The best place to setup your event listeners, is in the onload function:
window.ybug_settings = {
id:'XXXXXXXXX',
onload: function() {
Ybug.on('open', function() {console.log('opened')});
Ybug.on('beforesend', function(report) {console.log('Before report is sent', report)});
Ybug.on('aftersend', function(report) {console.log('Feedback was sent', report)});
Ybug.on('cancel', function() {console.log('canceled')});
Ybug.on('close', function() {console.log('closed')});
},
};
Console recording BASIC
Ybug automatically captures all unhandled global errors and console output. You can explicitly turn this feature on/off by setting the console_log
option to true/false or from your dashboard:
window.ybug_settings = {
id:'XXXXXXXXX',
console_log: false, // Turn console recorder off
};
Limitations
Because for performance reasons Ybug is loaded asynchronously, it can capture errors and
console output only when it is fully loaded. If performance is not a concern, you can put Ybug's
Javascript snippet into the <head>
section of the page.
For security reasons, capturing unhandled errors is also limited by browsers. If you see "Script error." in your Ybug's console log, it means that the error originates from a Javascript file from a different origin. This is also known as a CORS error. Please refer to our troubleshooting section for more details.
Custom error logging
You can use Ybug's Custom error logging feature to capture any errors that had been handled by your application.
try {
// Some JS code ...
} catch (err) {
if (Ybug) {// Make sure Ybug is loaded
Ybug.log('error', err);
// You can also log a message
Ybug.log('log', 'An error happened...');
}
}
Feedback form customization
Do You need to customize or translate texts in the Ybug launcher button or feedback forms? No problem, it is possible to customize texts in all parts of Ybug app.
Enabling/disabling fields
It is possible customize the feedback form to meet your needs. Currently supported fields are: Feedback type, Comment, Name, E-mail, Phone, Priority, Rating (with stars) and Net Promoter Score®. You can make these fields hidden, optional or required.
Default feedback form settings:
window.ybug_settings = {
id:'XXXXXXXXX',
rating: false, // Rating is disabled by default
rating_required: false,
rating_type: 'emoji', // Possible values: 'stars', 'emoji'
comment: true, // Comment is enabled and required
comment_required: true,
name: false, // Name field is disabled
name_required: false,
email: true, // Email field is enabled and optional
email_required: false,
type: false, // Feedback type (Bug, Improvement, Question, ...)
type_required: false,
title: false, // Feedback title/summary field
title_required: false,
priority: false, // Feedback priority
priority_required: false,
phone: false, // Phone number field
phone_required: false,
nps: false, // Net Promoter Score® field
nps_required: false,
};
Launcher button
To change the label of Ybug launcher button to your own call to action text (for example "Report a problem" instead of default "Send feedback"), just add a translate object with launcherButton.Title
option to your ybug_settings object:
window.ybug_settings = {
id:'XXXXXXXXX',
translate: {
"launcherButton.Title": "Report a problem",
}
};
Additional options
Name | Type | Default | Description |
---|---|---|---|
close_countdown |
int|false | 5 | The countdown total value (in seconds) before the Thank you dialog closes. You can also pass a negative number which will close the Thank you page immediately after submitting the feedback. The countdown timer can also be disabled by passing close_countdown: false |
Translations BASIC
To customize the translations of certain text elements within the widget, you can use the translate
setting. This setting is a JSON object containing key-value pairs where the key is the text element and the value is the translation. To use this setting, simply add it to your ybug_settings object. You can use this as a template:
window.ybug_settings = {
id:'XXXXXXXXX',
translate: {
"launcherButton.Title": "Feedback",
"feedbackTypeForm.Heading": "Feedback",
"feedbackTypeForm.Subheading": "Have you found a bug or do you have any comments\/suggestions about this site?",
"feedbackTypeForm.ButtonSpecific": "Select and comment part of this page",
"feedbackTypeForm.ButtonGeneral": "General feedback about this page",
"feedbackForm.Heading": "Feedback",
"feedbackForm.RatingLabel": "How would you rate your experience?",
"feedbackForm.TextLabel": "Comment",
"feedbackForm.TextPlaceholder": "Write a comment or describe a problem.",
"feedbackForm.TitleLabel": "Title",
"feedbackForm.TitlePlaceholder": "Short feedback summary",
"feedbackForm.EmailLabel": "Your e-mail",
"feedbackForm.EmailPlaceholder": "Your e-mail",
"feedbackForm.EmailError": "Please enter a valid e-mail address",
"feedbackForm.NameLabel": "Your name",
"feedbackForm.PriorityLabel": "Priority",
"feedbackForm.TypeLabel": "Feedback type",
"feedbackForm.Types.1": "Bug",
"feedbackForm.Types.2": "Improvement",
"feedbackForm.Types.3": "Question",
"feedbackForm.Types.4": "Feedback",
"feedbackForm.PhoneLabel": "Your phone number",
"feedbackForm.PhoneError": "Please enter a valid phone number",
"feedbackForm.NpsLabel": "How likely are you to recommend us to a friend or colleague?",
"feedbackForm.Nps.Unlikely": "Not likely at all",
"feedbackForm.Nps.Likely": "Extremely likely",
"feedbackForm.ButtonSubmit": "Submit feedback",
"feedbackForm.ButtonCancel": "Back",
"feedbackForm.RequiredError": "This field is required",
"feedbackForm.OptionalText": "(optional)",
"feedbackForm.AddScreenshot": "Add screenshot",
"feedbackForm.EditScreenshot": "Edit screenshot",
"feedbackForm.AddVideoClip": "Record video clip",
"feedbackForm.PreviewVideoClip": "Preview video clip",
"feedbackForm.Consent.Label": "I agree to the {tos}",
"feedbackForm.Consent.TosUrl": "https:\/\/ybug.io\/terms",
"feedbackForm.Consent.TosLabel": "Terms of Service",
"feedbackForm.MaxLengthError": "This text is too long. Maximum is {max} characters",
"feedbackForm.BeforeUnload": "Are you sure you want to exit? Any feedback left will not be saved.",
"screenRecorder.Start": "Start recording",
"screenRecorder.Stop": "Stop recording",
"screenRecorder.Audio.Mute": "Mute",
"screenRecorder.Audio.Unmute": "Unmute",
"screenRecorder.Audio.NotSupported": "Audio not supported",
"videoPreview.RecordAgain": "Record again",
"videoPreview.Done": "Done",
"highlighter.Cancel": "Cancel",
"highlighter.Undo": "Undo",
"highlighter.tools.Pencil": "Pencil",
"highlighter.tools.Interact": "Interact",
"highlighter.tools.Arrow": "Arrow",
"highlighter.tools.Rectangle": "Rectangle",
"highlighter.tools.ColorPicker": "Color picker",
"highlighter.tools.Obfuscate": "Obfuscate",
"highlighter.tools.Text": "Add a comment",
"highlighter.tools.Text.Placeholder": "Type a comment",
"highlighter.tools.Text.Save": "Save comment",
"highlighter.Done": "Done",
"thankYouModal.Heading": "Thank You",
"thankYouModal.Text": "Your feedback has been sent successfully. Thank you.",
"thankYouModal.Button": "Close",
"processingModal.Heading": "Processing",
"privacyTour.Title": "Privacy tip",
"privacyTour.Ok": "Got it",
"privacyTour.Obfuscate": "Use this tool to obfuscate any personal information before sending your feedback."
}};
Note that any text elements that are not defined in this setting will use the default texts.
Multi-language setup
To set up multiple languages at once, you can use the translations
setting.
It is again a JSON object where each key is a language code (e.g. 'cs', 'en', 'de', 'it', ...) and the value is another JSON object containing key-value pairs for the different text elements in that language. The keys are the same as in the translate
setting mentioned above.
To use this setting, simply add it to your ybug_settings object like this:
window.ybug_settings = {
id: 'XXXXXXXXX',
translations: {
'en': {
"launcherButton.Title": "Feedback button",
"feedbackTypeForm.Heading": "Feedback please!"
},
'de': {
"launcherButton.Title": "Feedback",
"feedbackTypeForm.Heading": "Feedback bitte!"
}
}
};
Please keep in mind that the translate
setting takes precedence over the translations
setting,
meaning that any text elements defined in the translate
setting will override the corresponding text elements in the translations
setting for any language.
Do you have any questions?
Contact us in case you have any questions or feedback.
We will be happy to help.