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 use Vue or React, you can install our Vue 3 npm package or React npm package to easily integrate Ybug in your projects.

Looking for instructions for most common web platforms? Shopify (More to come :-))

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
};

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

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');

To close the widget if it's already open, use Ybug.close():

// Close opened widget
Ybug.close();

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');

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');

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();

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).

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.

Getting started

Installing Ybug on your site

Browser extensions

Passing user information

Feedback default values

Sensitive data protection

Setting the language

Opening Ybug programmatically

With markup

With Javascript

Keyboard shortcut

Launcher position

Widget position

Javascript API

Open widget

Close widget

Hide widget

Show widget

Destroy widget

Initialize widget

Javascript events

Console recording BASIC

Limitations

Custom error logging

Feedback form customization

Enabling/disabling fields

Launcher button

Additional options

Translations BASIC

Multi-language setup

Do you have any questions?

What's New

Getting started

Installing Ybug on your site

Browser extensions

Passing user information

Feedback default values

Sensitive data protection

Setting the language

Opening Ybug programmatically

With markup

With Javascript

Keyboard shortcut

Launcher position

Widget position

Javascript API

Open widget

Close widget

Hide widget

Show widget

Destroy widget

Initialize widget

Javascript events

Console recording BASIC

Limitations

Custom error logging

Feedback form customization

Enabling/disabling fields

Launcher button

Additional options

Translations BASIC

Multi-language setup

Do you have any questions?