Install the in-app feedback widget in your web application (Advanced plan)

With the in-app feedback widget, you can collect feedback from users in your application and gather that feedback in your Aha! Ideas account.

You can manage multiple feedback widgets to get separate feedback on different pages in your application. Application users can leave feedback or interact with you and each other in threaded feedback conversations.

You can choose the page or pages of your web application where you would like each feedback widget to appear on your site and start or stop feedback collection without relying on a developer.

This article discusses how to install the feedback widget on your site. Installation requires adding some custom code. Your Aha! Ideas page gives you the code snippet you need to pass on to your developers.

Dashboard widget

Note: This article discusses a feature that is exclusively available on the Ideas Advanced plan.

Click any of the following links to skip ahead:

Requirements

Before you get started with the installation, there are a few things to keep in mind about how the in-app feedback widget works.

  • You need to install the widget in a web application. The feedback widget requires JavaScript to be enabled by users.

  • Currently, you can install the feedback widget in one web application per Aha! Ideas account. However, the feedback widget code snippet supports many separate widgets and the code only needs to be installed once.

  • Your users will need to be logged into your website to leave feedback. This is important in order to mitigate the risk of spam or inappropriate feedback.

  • The feedback widget has fixed dimensions at 375px wide by 700px tall.

We also have a few recommendations for how to use the feedback widget once it is installed:

  • Each feedback widget should be configured with the URLs where users should see that particular widget. We will discuss how to do this later in the article.

  • You should display your users' real names whenever possible and appropriate. This encourages users to post feedback that they are happy to be associated with.

  • We recommend installing the feedback widget securely any time you are using it to collect feedback. We will discuss how to do this later in the article.

Note: You will likely require a developer's help to install the in-app feedback widget on your application. But do not worry! We will give you all the tools you need to help them.

Top

Create a feedback widget in Aha! Ideas

To install a feedback widget in your web application, first create a feedback widget in your Aha! Ideas account. Navigate to Empathy → In-app feedback to get started. You will need to be a contributor or workspace owner to navigate to and create feedback widget records.

Click + on the top-left corner of your screen to Add a new feedback widget. Give it a Title, Target URL where you would like your widget to appear, and optional Subtitle and branded Color, then click Add widget to create the feedback widget.

Top

Install the feedback widget

We will first talk about how to install the feedback widget on your site and direct it to your Target URLs. But to make this installation secure, be sure to read the following section of this article on using the feedback widget securely in a production environment.

In the upper-left corner of the feedback widgets list, click the Widget code button. You will pass the JavaScript code snippet here to a developer (if a developer is helping you install this widget in your own application) once.

Support Ideas in-app code snippet

The developer should add the code snippet to your application in such a way that it executes on every page — or at least every page that you might gather feedback on. That way, you will be able to use Aha! Ideas to select for yourself what page(s) on your site should have the widget on them.

Note: The JavaScript can be added to the very end of the page <body> element so that it runs after the rest of the page has loaded. This way, the feedback widget will have no negative impact on page load times.

The Code snippet you see will look something like this:

<script>
(function(w, d, s, o, f, js, fjs) {
w['aha-widget'] = o;w[o] = w[o] || function() {(w[o].q = w[o].q || []).push(arguments);};
js = d.createElement(s);fjs = d.getElementsByTagName(s)[0];js.id = o;js.src = f;js.async = 1;fjs.parentNode.insertBefore(js, fjs);
})(window,document,'script','aha',"https://yourdomain.aha.io/assets/feedback/feedback.js");

aha('initialize', {
account: 'ACCOUNT_DOMAIN',
user: {
id: 'UNIQUE_USER_IDENTIFICATION',
name: 'USER_NAME',
email: 'USER_EMAIL_ADDRESS'
},
});
</script>

Your developer will need to modify this Code snippet in three ways:

  • UNIQUE_USER_IDENTIFICATION: You should replace this value with a persistent unique identifier for the user who is viewing the current page. The identifier should not be the user's name or email address. A database ID for the user is usually best. That way, if the user's name or email address changes, they will still be associated with the feedback that they have left. The id field will accept any string value with no limitation on allowed characters.

  • USER_NAME: You should replace this value with the name of the user who is viewing the current page. It will be displayed in the feedback widget user interface on your site so it is clear who has left the feedback.

  • USER_EMAIL_ADDRESS: This is an optional value that you can replace with the email address of the user who is viewing the current page. It is not currently in use, but in the future it may be used to send the user an email notification when there is a response to their comment in a feedback conversation. It will not be used for any other purpose.

Once you have installed the Code snippet successfully, the page in your web application should load without any visible change and without any error messages in the developer console.

Add Target URLs

To connect the feedback widget you just installed in your website to the feedback widget record in your Aha! Ideas account, you need to create Target URLs. To do this, navigate to the feedback widget record in Aha!, then select the Customization tab.

In the Target URLs field, you will list the pages in your application that will show the feedback widget.

So you do not have to list every page in your application, you can use asterisks * as wildcards in any location (or multiple locations) in a URL:

  • You can use wildcards to display the feedback widget on every page in your web application. The Target URL here, https://www.example.com/*, for example, will display the feedback widget on every page.

  • You can use wildcards to show the feedback widget on all like pages. For example, if your URLs contain portions that are specific to a record, like record IDs, then the Target URL here, https://www.example.com/records/*/page would display the feedback widget on every page that follows this structure.

You can use the Active toggle to select whether the feedback widget should display or be hidden on your site.

Top

Add a JWT secret to make your installation secure

Now that you have installed and targeted the feedback widget, it is time to make it secure. Without this step in the process, users who are not authenticated in your application could eavesdrop on your feedback conversations. So these next steps are important.

The feedback widget code is associated with a secret. This secret can be used to secure the communication between your web application and Aha! Ideas. The secret must be carefully protected and must not be in the front-end JavaScript code of your web application. To use the secret effectively you will need server-side code in your application to construct a JSON Web Token (JWT). This JWT is then used in the front-end JavaScript code to pass the user identity to Aha! Ideas.

To use the JWT, the Code snippet should be modified to look like this:

  aha('initialize', {
account: 'ACCOUNT_DOMAIN',
jwt: 'JWT_VALUE',
});

You should replace the JWT_VALUE with the value of the JWT which was generated on the server side.

For development environments where web pages are rendered by the server, this can all be done inside the page rendering on the server. For example, this code for Ruby on Rails can be used directly in an ERB view:

<%= javascript_tag do %>
aha('initialize', {
account: 'ACCOUNT_DOMAIN',
jwt: JWT.encode(
{
user: {
id: 'UNIQUE_USER_IDENTIFICATION',
name: 'USER_NAME',
email: 'USER_EMAIL_ADDRESS'
},
iat: Time.now.utc.to_i
},
'JWT_SECRET', 'HS256'
),
});
<% end %>

Note: The iat field must contain the current time as an integer in seconds since January 1, 1970.

This website provides links to many different JWT implementations for different programming environments.

Once you have successfully configured your JWT secret, click the Widget code button in Aha! Ideas, place it in your code to sign it, and check the Require JWT Secret checkbox.

Top

Install the feedback widget on single-page applications

Single-page applications (and some other techniques like Turbolinks) navigate from page to page without reloading the JavaScript context. In these cases, the widget should be unloaded from the page before making the page transition, and then initialized again once the new page content is loaded. After it is initialized each time, the widget will read window.location.href to get the URL and will determine again whether the trigger button should be displayed for that URL.

An existing widget can be unloaded by calling: aha('destroy').

Top

Troubleshoot your installation

If you get stuck during this process, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds within two hours.

Top

Aha! Roadmaps
Aha! Ideas
Ideas
      Announcements
      © 2020 Aha! Labs Inc.All rights reserved