In-app feedback widgets help you collect feedback from users in your application and gather that feedback in your Aha! Ideas account.
The community feedback widget collects feedback from your users in threaded conversations. You can manage multiple feedback widgets to get separate feedback on different pages in your application, and install separate feedback widgets on multiple applications. Application users can leave feedback or interact with you and each other in realtime.
The ideas submission widget collects feedback from your users as ideas, which it then submits using your portal's idea submission form. Your users never have to leave your application to submit ideas, and you can review their feedback (along with ideas you collect through other channels) in one central location.
The polls widget enables a poll in your application. Users do not have to leave your product or sign in to an ideas portal to respond — they can complete the poll in your application, then continue using your app.
You can use both types of widget, choose the page (or pages!) where you would like each widget to appear, and activate or deactivate the widgets yourself, without relying on a developer.
The widget code snippet installation is the only part of the process that will require help from your developers, since it requires adding some custom code — but the code only needs to be installed once. Your Aha! Ideas or Aha! Roadmaps page gives you the code snippet you need to pass on to your developers.
Click any of the following links to skip ahead:
Best practices
Before you get started with the installation, there are a few things to keep in mind.
The widget code snippet supports any widget you create in Aha! Ideas or Aha! Roadmaps, and the code only needs to be installed once.
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.
Each widget can be customized in Aha! Ideas or Aha! Roadmaps with the URLs that determine where widget should be displayed in your application. These are called Target URLs, and we will discuss how to configure them later in the article.
Requirements
You need to install the widget in a web application. The feedback widget requires JavaScript to be enabled by users.
If you want to gather feedback over multiple applications, you can create multiple applications in Aha! Ideas or Aha! Roadmaps, and separate widgets for each application.
Your users will need to be logged into your website to leave feedback or to submit ideas. This is important in order to mitigate the risk of spam or inappropriate feedback.
Recommendations
If you are using the community feedback widget, 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.
Either feedback widget will display when someone views your web application on a mobile device, but the widgets are not optimized for a mobile experience. Because of this, we recommend that when developers install the widget code snippet in your application, they only enable it for desktop users.
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.
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.
Create a community feedback widget
To install a feedback widget in your web application, first create a feedback widget in your Aha! Ideas account. Navigate to Research → 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, Application, and branded Color, then click Add widget to create the feedback widget.
When you first add it, your widget is Disabled by default, so that you can customize it. Then, Activate it to preview your users' experience interacting with you and each other..
Create an ideas submission widget
Ideas submission widgets start with an ideas portal. So first, open the ideas portal where you would like to receive ideas submitted through the widget, and then open the portal's settings. You will need to be an administrator with customizations permissions to configure an ideas portal.
From your account settings, click the name of the ideas portal you wish to edit.
From Ideas → Overview, click the pencil icon by the name of the ideas portal you wish to edit.
You can add ideas submission widgets to any public or submit-only ideas portal that uses the new (October 2020) portal design. If the ideas submission widget is not compatible with your portal, you can always create another portal for the same workspace. You will still be able to review all ideas from all portals in that same workspace.
In your ideas portal settings, navigate to Widgets then click + Add widget. Give it a Title, Target URL(s) where you would like your widget to appear, and optional Subtitle, Application, and branded Color, then click Add widget to create the feedback widget.
When you first add it, your widget is Disabled by default, so that you can customize it and preview your users' idea submission experience.
Create a polls widget
You can create a polls widget from any poll you have created in your Aha! Ideas account. A poll does not have to be published to your ideas portal to be displayed in in your application, and participants do not have to be users of your ideas portal.
Once you have created your poll, navigate to its Widget tab. You will need to be an administrator with customizations permissions to display a polls widget within your application.
From the Widget tab of your poll, add the Target URLs where you want your poll to appear in your application.
In the Branding section, add a Header and select a Color and an Accent Color.
-
Select a Position for your widget.
Select Lower left or Lower right to add a thumbs up and thumbs down icon to the bottom of the page. Users will click the icon to access your poll and participate.
Select Side left or Side right to add the widget to the side of your page. When you select a side position, you can add custom text for the button that users will click to access your poll. By default, the button will say Feedback.
Select Custom to create a custom trigger that will open the widget.
Click Preview to see what your widget will look like in your application.
Use the Active toggle to enable the widget in your application.
Once the polls widget is active, users will be able to respond to your poll. Poll participants will not be able to see poll results. If a participant is not a user of your ideas portal, your software will create a Contact record for them along with their poll response. Once a participant answers your poll, the poll will disappear and any other widgets on the page will reappear.
You can view the poll's results from its Results tab.
Install the feedback widget
We will first talk about how to install the feedback widget on your site. 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 community feedback widgets list, or in the ideas submission widget details page, 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.
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 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 customize each widget in Aha! Roadmaps or Aha! Ideas yourself and specify the pages (Target URLs) of your application where it should be visible.
Either feedback widget will display when someone views your web application on a mobile device, but the widgets are not optimized for a mobile experience. Because of this, we recommend that when developers install the widget code snippet in your application, they only enable it for desktop users.
The Widget 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://cdn.aha.io:443/assets/feedback/feedback.js');
aha('initialize', {
account: 'fredwin-technologies',
applicationId: '6878652530101593449',
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 community feedback widget user interface on your site so it is clear who has left the feedback.
-
USER_EMAIL_ADDRESS:
Replace with the email address of the user who is viewing the current page. It is used to match the person with an existing contact or to create a contact if one does not exist. It is not shown in the widget.
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
Now that you have installed the widget code in your web application, you can use Target URLs to display feedback widgets on specific pages in your application. To do this:
For community feedback widgets, navigate to the feedback widget record, then select the Customization tab.
For ideas submission widgets, open the widget details page in your ideas portal settings, then scroll to the Visibility tab.
For the polls widget, navigate to a poll's Widget tab and add Target URLs in the Visibility section.
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 wildcards to display the feedback widget on every page in your application where the widget code is installed. For example, you may want the ideas submission widget to be available everywhere (you likely want to reserve the community feedback widget for more focused feedback). Enter * for the widget to display on every available page.
You can use the Active toggle to select whether the feedback widget should display or be hidden on your site.
Install a custom trigger
On every page included in your Target URLs, people can access your widget using a standard button in the lower right or left corners of their screen. You can customize this to create custom triggers that open the widget. For example, you could add a link in your help menu to launch an idea submission widget, or a chat icon next to a new feature to open a specific community feedback widget.
To create a custom trigger for your widgets:
-
Navigate to the Position field in your widget settings.
For in-app feedback widgets, this is on the Customizations tab of your settings.
For idea submission widgets, this is in your ideas portal settings under Widgets → Design.
Change the Position field to Custom.
Once you change the Position to Custom, you will see a sample script that will help your developers create a custom trigger for your widget, which includes your widget's unique ID. Share this sample script with your developers and discuss with them how you would like your custom button or link to work.
It is a good idea to set your widget as Active so that you can test your new button.
If a widget has a Custom position, it will not display the standard button, and it will not use your Target URLs. But by using custom triggers, you can have as many widgets on a page as you would like, and if you have another active widget that does use a standard Position, that widget will still display the standard button.
Add a JWT secret to make your installation secure
Before you Activate your installed widget, you should make sure it is secure. Without using a JWT secret, unintended people may be able to gain access to your feedback widgets and see feedback that is shared. 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 or Aha! Roadmaps. 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 Widget code 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: 'reallybigaha',
applicationId: '6930351653394748499',
jwt: <%= raw JWT.encode(
{
user: {
id: 'UNIQUE_USER_IDENTIFICATION',
name: 'USER_NAME',
email: 'USER_EMAIL_ADDRESS',
},
iat: Time.now.to_i
},
'JWT_SECRET', 'HS256'
).to_s.to_json %>
});
<% end %>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 or Aha! Roadmaps, place it in your code to sign it, and check the Require JWT Secret checkbox.
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.
To do this, run the feedback widget snippet (the <script> tag used to load the feedback.js file from Aha! servers) dynamically whenever the specific page(s) are loaded in your application. So, instead of adding the <script> tag to the raw HTML, execute the code in that script whenever you open the specific page(s).
The next step is to call the destroy handler, and reset window.aha, whenever the page is unloaded. Your code might look something like this:
function loadFeedbackWidget() {
(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://cdn.aha.io:443/assets/feedback/feedback.js');
aha('initialize', {
account: 'crowe2',
applicationId: '1234',
user: {
// ...
},
});
}
function unloadFeedbackWidget() {
aha('destroy');
delete window.aha
}
$(document).on('page:change', unloadFeedbackWidget);This will allow an Aha! user to control where a widget shows in the application, using these pseudo-URLs as the widget's Target URLs. Make sure to share the pseudo-URLs that you have implemented with the Aha! Ideas or Aha! Roadmaps user.
An existing widget can be unloaded by calling: aha('destroy').
Install the feedback widget on multiple applications
You may have multiple applications where you would like to install the in-app feedback widget. If so, you will want to ensure that users in one application cannot gain access to feedback from another application.
To do this, you can create separate applications in Aha! Ideas for each installation.
Click Widget code to open the widget code window.
Click the Application dropdown, then Create a new application.
Click Application name to give your application a unique name.
Make sure to enable JWT and generate a secret key for each application by checking the box beside Require JWT secret key.
Finally, install the application's code snippet in your desired product, using the unique application id and secret key.
When a user in your Aha! Ideas or Aha! Roadmaps account creates feedback widgets, they can then choose which application it should display in.
Troubleshoot your installation
If a widget is not appearing as expected in your application, please check the following in Aha! Ideas or Aha! Roadmaps:
On the community feedback widget's Customization tab, or the ideas submission widget's Visibility card:
Make sure it is Active.
Confirm the Target URLs (e.g. https://*.example.io/dashboard/*). Compare the Target URLs to an actual example URL where the widget should be displayed (e.g. https://customer.example.io/dashboard/123).
If you have created multiple Applications, confirm that the correct one is selected.
In the Widget code modal:
Check the Installation status field to see if any successful requests have been received from your installation.
In your application, make sure that the Widget code is installed on the pages with the Target URLs.
Go to a page where the in-app feedback widget is expected to display.
Open the browser developer tools.
-
Check the network tab:
Is there a request for feedback.js that looks like https://cdn.aha.io/assets/feedback/feedback.js?
If yes, look at the feedback request and check the response for an error.
If no, the Widget code has not been successfully installed for this page.