Ratings is a plugin which helps collect, store, search, and track user feedback from web and mobile applications. It pops up as a widget that triggers the collection of data so that you can obtain feedback from users.

Getting Started

First of all, make sure the Ratings plugin is enabled. To do so, in the main Countly Dashboard, go to Management > Plugins and enable the Star Ratings toggle.

After that, you will find Ratings in the Reach section of your Countly Dashboard, under the Feedback category.

Inside Ratings, you will find three tabs:

• Ratings: An overview of the cumulative data from the Ratings widgets.
• Comments: A tabular view of the free text responses from Ratings widgets.
• Ratings Widgets: A list of all Ratings Widgets and access to the widget creator.

Creating Your Ratings Widget

As a first step, you need to create a widget to collect user ratings. Go to the Ratings Widgets tab, where you will find a list of all existing widgets.

To create a new Ratings widget, click on the green button Add new ratings widget.

The creation process consists of three steps:

1. Popup appearance.
2. Trigger button appearance.
3. Devices and Targeting.

Popup Appearance

The Add new widget drawer contains a form on the right side. As you edit the fields, the left side containing the Popup preview will reflect the changes.

This section contains inputs for the Ratings plugin popup appearance like Title of popup, Labels of checkboxes, Title of submit button, and Thank you message values. If you leave these fields empty, their values are set by default.

Also you can hide Add comment and Contact me via email sections from the future popup by using checkboxes on the drawer.

Trigger Button Appearance

This step contains inputs for properties of the trigger button. You can customize the position of the trigger button, its background and font color, and its written content. You can also customize the trigger button size, with three options: Small, Medium, and Large.

For some use cases which require a manual popup call, there is an option called Hide sticker. If you check this option, the popup trigger button will not be seen on the page, even if you integrate Ratings to your site. Instead, you need to call the Ratings popup manually through the show_feedback_popup(widget_id) method. There are sample use cases for this in the Integration section, below.

Devices and Targeting

In this step, you can easily enable or disable the Ratings popup for some devices (e.g. desktop, tablet, or phone). Also, you can define target pages for which the Ratings popup will be shown.

You can define the exact target pages like /products/our-great-product or use /products/* for all pages under the /products/ path.

By default, Ratings popups are disabled. If you want to enable them, just click on Set Ratings Active checkbox. You may also change the Ratings popup state after you create it as well.

When you click on the Complete button, your Ratings popup is ready to be shown to your users.

After creating the popup, a helper page for the web integration will appear. You just need to copy the highlighted line and paste it into your html file, inside the Countly SDK. For details, please check the Integration step below.

Editing Ratings Widgets

All Ratings popups are listed in a table under the Ratings Widgets tab. Each widget in the list has a toggle button to easily enabling or disabling it,. Additionally, each widget can be edited from the 3-dot ellipsis menu on the right side.

When you click on Edit widget in the menu, an Edit widget drawer will appear, similar to the Add new widget drawer, but populated with the existing information.

Removing a Widget

When you want to delete a widget, simply click on Delete widget for the corresponding widget row in the Ratings Widgets tab.

Integration

When your popup creation process is done, you need to integrate this popup into your application. The integrations of the Ratings plugin is different for web and mobile applications.

Web Integration

To integrate Ratings to your web application, you first need Countly to integrate the web SDK. If Countly web SDK is already initialized on your web application, you just need to integrate the following code:

/* ATTENTION PLEASE! */
Countly.q.push(['enable_feedback',{'popups':['5b86772f7965c435319c79ee']}]);
/* THANKS FOR YOUR ATTENTION! :) */

Then, your Countly Web SDK integration code section will look like the following:

<script type="text/javascript">
   // Some default pre init
   var Countly = Countly || {};
   Countly.q = Countly.q || [];
   // Provide your app key that you retrieved from Countly dashboard
   Countly.app_key = "1234426e50d669e5035d618cbff9374982065223";
   // Provide your server IP or name. Use try.count.ly for EE trial server.
   // If you use your own server, make sure you have https enabled if you use
   // https below.
   Countly.url = "https://your.countly.instance"; 

   // Your Other Countly feature pushes to Countly.q array
   // Countly.q.push(['track_session']);
   // Countly.q.push(['track_pageview']);
   
   /* ATTENTION PLEASE! */
Countly.q.push(['enable_feedback',{'popups':['5b86772f7965c435319c79ee']}]);
/* THANKS FOR YOUR ATTENTION! :) */


// Load countly script asynchronously
(function() {
var cly = document.createElement('script'); cly.type = 'text/javascript'; 
cly.async = true;
// Enter url of script here (see below for other option)
cly.src = '/countly.js';
cly.onload = function(){Countly.init()};
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(cly, s);
})();
</script>

Now, you are ready to use the Ratings plugin.

Multiple Popups

In some cases you may want to use multiple popups in one page. In this case your only need to add popup ID values into the popups array. For example, as shown in the code below, you can add multiple popups into one page with the array type popups parameter of enable _feedback function:

/* ATTENTION PLEASE! */
Countly.q.push(['enable_feedback',{'popups':['5b86772f7965c435319c79ee','5b86772f7965c435319c79fe','4b86772f7965c435319c79ee']}]);
/* THANKS FOR YOUR ATTENTION! :) */

Manually Calling a Popup

You may need to trigger a popup manually. To do so, you should check the Hide sticker checkbox. After setting this up, you just need to call the popup as follows:

var go = confirm("Do you want to continue?");

if (go) {
  // you can get popup id easily through the ‘Copy Popup Id’ option in the popup menu.
show_feedback_popup("5b890791dfc7d9562b391df8")
}

Mobile Integration

When you use the Ratings plugin for mobile applications, you have two options:

• Using native dialogs: In this case, native dialogs have the ability to show 1-5 star ratings only.
• Using web dialogs: In this case, web dialogs called from native iOS/Android apps can show avatars (emoji-like faces) that help retrieve the end users’ feelings (e.g. from very satisfied to very disappointed). This is the same as how web integration works.

The first case will not retrieve comments but only 1-5 star ratings, whereas the second option will be able to show an option to retrieve comments and email of the end user.

For iOS integration, please check the iOS SDK documentation.

For Android integration, please check the Android SDK documentation.