In-app widgets connect your application users to your product team. You can collect ideas, run polls, recruit research participants, and provide knowledge base content without asking users to leave your product.
The ideas submission widget (available in Aha! Ideas Advanced) lets users submit ideas through your portal's idea submission form within your application. You can review these ideas alongside feedback from other channels.
The polls widget (available in Aha! Ideas Advanced) lets users answer a poll within your application without signing in to an ideas portal.
The recruiting widget (available in Aha! Discovery Advanced) asks users whether they want to participate in interviews about a specific topic. You can review a list of people who said they are interested and send them an invitation.
The knowledge base widget (available in Aha! Knowledge Advanced) brings support content into your application. Users can search articles, ask questions, and read AI summaries without leaving the page.
You can choose where each widget appears and turn it on or off in your Aha! account.
A developer installs the shared widget code once in each application where you want widgets to appear. You can then manage your widgets without reinstalling the code. JSON Web Token (JWT) and custom triggers can require additional development work.
Click any of the following links to skip ahead:
Best practices
Before installation, check the requirements for your application and the widgets you want to use.
The widget code snippet supports any widget you create in Aha! Ideas, Aha! Discovery, or Aha! Knowledge, and the code only needs to be installed once.
Each widget can be customized in Aha! Ideas, Aha! Discovery, or Aha! Knowledge with the URLs that determine where the 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
Install the widget code in a web application where users have JavaScript enabled.
Check that your plan includes the widget you want to use and that you have permission to configure it.
If you use widgets in multiple applications, create a separate Application configuration for each installation.
Configure JWT for private knowledge base content. Public knowledge base access does not require JWT.
Recommendations
Install the feedback widget securely with JWT any time you are using it to collect feedback or recruit research participants.
Preview each widget before making it active. Check its placement and test the user experience.
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 widget
Ideas submission widget (Aha! Ideas Advanced)
You can create an ideas submission widget in any public or submit-only ideas portal that uses the new portal design. You need to be an administrator with customization permissions to configure the widget.
In your ideas portal settings, select Widgets, then + Add widget. Add the details that control where the widget appears and how it looks. For complete instructions, see Idea submission widget.
Polls widget (Aha! Ideas Advanced)
You can create a polls widget for any poll in Aha! Ideas. The poll does not need to be published to your ideas portal, and people can respond without signing in to an ideas portal. You need to be an administrator with customization permissions to configure the widget.
Open the poll's Widget tab to choose where the widget appears, customize its design, preview it, and activate it. For complete instructions, see Polls widget.
Recruiting widget (Aha! Discovery Advanced)
In-app recruiting is available with Aha! Discovery Advanced. Create a recruiting widget for a study to ask users whether they want to participate. When someone selects Yes, Aha! Discovery adds them as a participant with a status of Not invited. Invitations are not sent automatically.
Open the study's Participants page. In the In-app recruiting section, click Create to customize the invitation and choose where the widget appears. For complete instructions, see In-app recruiting widget.
Knowledge base widget (Aha! Knowledge Advanced)
Workspace owners can create and manage widgets in their knowledge base settings.
In your knowledge base settings, open the Widgets tab to create a widget and choose where it appears. For complete instructions, see In-app knowledge base widget.
Install the widget code
Copy the widget code from your Aha! account and share it with a developer.
Open the widget settings in your Aha! account.
Click </> Widget code.
Select the Application where you want to install the widgets.
Click Copy code snippet.
Share the snippet with the developer who manages your application.
Ask your developer to place the JavaScript snippet at the end of the page's <body> element and run it on every page where you want widgets to appear. You can then use Target URLs in your Aha! account to control where each widget appears.
Widgets will display when someone views your web application on a mobile device, but they 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 following example shows the widget code structure. Use the snippet copied from your account for the installation.
<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://yourcompany.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>For installations that pass user identity directly, your developer replaces these placeholder values:
UNIQUE_USER_IDENTIFICATION: Use a persistent, unique identifier for the current user, such as a database ID. Do not use their name or email address. A stable identifier keeps their feedback associated with them if those details change. The field will accept any string value with no limitation on allowed characters.
USER_NAME: Use the current user's name.
USER_EMAIL_ADDRESS: Use the current user's email address. Aha! can use it to match an existing contact or portal user. For idea submission widgets, users receive a thank-you email and may receive notifications about comments and status changes.
If you use JWT, include the user identity in the server-generated token instead, as described below.
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
Use Target URLs to choose where a widget appears in your application.
Open the widget settings in your Aha! account.
Find Target URLs in the widget's visibility settings.
Add the full URLs of the pages where you want the widget to appear.
Use an asterisk (*) as a wildcard to match multiple pages:
https://www.example.com/records/*/pagematches pages with different record IDs.https://www.example.com/*matches pages under that domain.*matches any page where the widget code is installed.
The widget code must run on a page for the widget to appear there. Turn on Active when you are ready to display the widget.
Install a custom trigger
Users can open a widget from a lower corner or along the side of the page, depending on the Position you select. A custom trigger lets you open it from your own button or link. For example, you can add a link in your help menu that opens the idea submission widget.
To create a custom trigger:
Open the widget settings and find Position.
Select Custom.
Share the sample script with your developer. It includes the widget's unique ID.
Ask your developer to connect the script to your chosen button or link.
Turn on Active and test the trigger.
A widget with a Custom position does not display its standard button or use Target URLs. Your application controls where its custom trigger appears. Another active widget with a standard position can still display its own button.
Add a JWT secret to make your installation secure
Before you Activate your installed widget, you should make sure it is secure. The JWT tells the widget the identity of the user accessing the page in a way that cannot be faked. Without it, a malicious user might be able to submit feedback as another user or see feedback that is shared by another user.
The widget code is associated with a secret. Use this secret to secure the communication between your web application and your Aha! account. 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 your Aha! account.
To use the JWT, the Widget code should be modified to look like this:
aha('initialize', {
account: 'ACCOUNT_DOMAIN',
jwt: 'JWT_VALUE',
});Replace JWT_VALUE with the token generated on your server.
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: 'yourcompany',
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 Jan. 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 your Aha! account, 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. Each time the widget initializes, it reads window.location.href to determine whether its standard trigger should appear on that page.
To do this, run the feedback widget snippet (the <script> tag used to load the feedback 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://yourcompany.aha.io:443/assets/feedback/feedback.js');
aha('initialize', {
account: 'example2',
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! user.
An existing widget can be unloaded by calling aha('destroy').
Install the feedback widget on multiple applications
Create a separate Application configuration for each application where you want widgets to appear.
Open Widget code in your Aha! account.
Open the Application dropdown and select Create a new application.
Enter a unique name and click Create application.
If the installation uses JWT authentication, generate a secret for that application and share it securely with your developer.
Ask your developer to install the snippet using that application's ID and, where needed, configure token signing with its secret.
When configuring a widget, select the Application where you want it to appear.
Troubleshoot your installation
If a widget does not appear as expected, check its settings first. Then ask your developer to check the installation.
Check the widget settings
Confirm that the widget 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 multiple Applications, confirm that the correct one is selected.
If Position is set to Custom, use your custom trigger to open the widget. The standard button will not appear.
Check the installation
Ask your developer to open the browser developer tools on a page where the widget should appear.
Check the Network tab for a request that loads
feedback.js.If the request is missing, check whether the widget snippet runs on that page. Look for browser errors or blocked requests.
If the request appears, inspect the widget's subsequent requests for errors.
If the widget uses JWT authentication, check token generation and the application's JWT configuration.
For private knowledge base content, also review the authentication and access settings described in In-app knowledge base widget.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.