Managing the RefTracker widget

The RefTracker widget provides a way for requests to be submitted to your RefTracker system via a small “Got a question – Email us” widget that you can insert (embed) directly in your web pages without an iframe, have proactively pop up, or have appear in the page or pop out when selected from a button or sliding bar. The proactive and pop up versions float over the page they are in, and so can be used without leaving the page.

This widget is an attractive and easy to use invitation to your end users to ask for assistance at the point that they need it, and in new attractive ways that will let more users know about your services. For more information about using the RefTracker widget, see this help page.

You can only have one widget in your RefTracker system so think about the type of service that you want to offer with it. For example:

A “Quick Assist” service where requests arrive in RefTracker clearly indicated as needing a quick response by email. Place the widget in pages in your web pages that remind your end users that you are there to provide assistance with the services provided in those web pages.
A “Quick Meet” service where the widget includes the Meeting room link field. Place the widget in places where your end users might need online assistance with how to use things. They can request assistance and provide their online meeting room address or just specify their favourite online meeting product. You can suggest a time to meet online that is convenient to you both.

Services based on the widget are not a replacement for a chat service where staff are always online to be able to have immediate conversations with end users, but rather one where the end user requests assistance and you either provide a short response back as soon as staff are available, or you arrange a time to have a chat or phone call or desktop sharing session with the end user to help them with their request – a bit like phone calls have become where you might send a text/SMS message or email to ask if it is appropriate to call, before calling. Your end users see that quick service is available online, and your staff get to provide the assistance when they next have a moment to spare.

The Widget is a supplement to, not a replacement for, request forms as request forms ensure specific data is collected when requests are submitted. The widget is configurable to some extent, but can display a maximum of only 5 fixed fields. See below for information about configuring it to suit your needs.

Want to give the Widget a try? Its easy! Just try out the widget links in the example pages! Go to System>Request form summary>Requester service>Quick Question Widget and then, in the top right corner, select Preview. Click that link to the embedded widget test page that appears at the top of the form in that page. You’ll also find links to the other example widget implementations in the page that displays. If the widget does not display in that page, try again after you have enabled parameter 9.50 (tick it but do not set a key – the APIkey line should be blank for this test as the API key is not embedded in the test page code, which means it is NOT secure and should be disabled again as soon as the test is over!).

Questions you submit using these widget test pages will arrive in your RefTracker system, so this link provides a way to familiarise yourself and your staff with the process before going live with it in your web pages.

We highly recommend that you use this example/test page to try it out, before trying to implement it in your own pages.

When you are ready to implement it in your pages, here’s all the information you need to know:
There can only be one RefTracker widget per RefTracker instance, but you can insert in your web pages in as many places as you want to use it.
It is meant to be a small interface so it can have a minimum of two fields (Email address, and Request text) and a maximum of 5 fields (Email address, Name, Meeting room link URL, Subject, and Request text).
The data entered into the widget creates a question in RefTracker using the same process as email importing, and just as for email importing the content of the data received is checked for dangerous html before being allowed into RefTracker.

There are three “out of the box” widget types, plus the ability for your programmer to create other ways of implementing the widget in your web pages. The three distribution types (implementation methods) are:

Popup – adds a sticky launch button in the bottom right of the browser screen and displays the form when that button is clicked. The sticky button stays on the page as the user scrolls up and down the page.

When the button is clicked the Widget displays and moves over the page as you scroll up and down that page:

And the confirmation screen looks like this, after one of these Pop-up widgets has been Submitted:

Embedded – just adds the widget right into the page, without having to use an iframe (you might like to make the widget size a little smaller when using it embedded):

Auto – automatically (proactively) shows the widget x seconds after the web page displays (no launch button is needed). The default parameters have it displaying 10 seconds after the page displays, but you can change that:

And the confirmation screen looks like this:

Additionally a programmer can implement the widget in other ways using the “Custom” option to program access any way they wish.

Here’s a quick summary of how you can make the widget (implemented in any of these ways) do exactly what you want it to do:
– Allow use of the widget by setting parameter 9.50 to Enabled, and adding the domain/s of the page/s you are inserting the widget into, in config/settings/api.xml. Then click “Set” to create an APIkey, if one has not already been created.
– Insert the widget code in the web page that you allowed in the api.xml file, to see it working with its standard parameters. Ensure that the APIkey for parameter 9.50 has been included.
– Adjust the Quick Question Widget Request form to collect all of the information and set the answering parameters for the questions that will come in through your new widget based “Quick Assist” service.
– Adjust the qqform text template to make the widget collect the data you need for your new service.
– Adjust the widget colour and size, if necessary, by adjusting its css file.
As is usually the case for RefTracker, the widget is delivered with the settings you are most likely to use, so many of the options for changes will require no action.

Here are the details of the widget implementation steps, and all the options:

1 Make the Widget functionality available for use (if not already done):
If you haven’t already done these things to test the widget (test using http://{YourRefTrackerDomain}/exchange/widget/example/methods.html), you will need to make the Widget functionality available for use with these two steps:
1.1 At System>Parameters>9 – Security, set Parameter 9.50 to “enabled” by ticking it. Don’t forget to click Update to save your changes.
If an APIkey for parameter 9.50 is not already showing, click “Set” to create one.
If there are APIkeys already showing in that page, for other API methods (in the 9.50-56 parameters), and they are all the same, you should select, right click, and copy that already set APIkey, and paste it into the APIkey for parameter 9.50. having all these APIkeys the same makes it easier for them to be used for multiple API applications.
1.2 Make the Quick Question Widget form available for client use by going to System>Request forms summary, and then clicking [Options] for the “Quick Question Widget” form, and:
– ticking the “Enabled” box in the Main access options tab of that form’s Edit options mode, and,
– in the “Client availability” parameter of the same tab, make it available for “External” client use. The form should NOT be made available for staff use.

2 Configure the API security:
If parameter 9.50 is NOT enabled, the RefTracker widget API cannot be used (it is secured).
Enabling it, as described in the previous step, allows it to be used, but the api.xml file controls what domains it can be used in – by default, only the same domain as your RefTracker system. As your RefTracker system is often hosted by Altarama, and you will want the widget to appear in your corporate web pages, you will need to let RefTracker know that it is OK to use this API method from your corporate web pages.
To do this add the domain/s you want to use the RefTracker widget in, into the <access> element under the QuickQuestion method in the api.xml file.
To edit the api.xml file go to System>Utilities>Administration utilities>File upload/download and select the config/settings directory.
Download the api.xml file
In that file, the QuickQuestion <access> parameter allows access from specified domains outside of the domain being used by your RefTracker system.
The distribution value for <access> is “http://somedomain.com” which is deliberately intended to prevent access to the Widget from any other domain than your RefTracker domain (this exemption for the RefTracker domain allows the examples to work without having to make this change).
To allow access to the widget from other domains, just replace “http://somedomain.com” with the domain of the web pages into which you are inserting the widget (such as the domain of your corporate web pages) e.g.
<access> https://enquiries.abc.com </access>

If you are adding the widget into more than one domain, add each domain in a separate <access> line.

* on the <access> line will allow access from any domain and is usually only be used by customers using RefTracker on a server in a secure network, but can be used to resolve access issues, and for testing.

Don’t forget to upload the api.xml file when you’ve finished editing it!
You may like to ask your RefTracker support representative for help setting this up (more information about this API security is provided here).

3 Place the widget in your web pages using these instructions:
The RefTracker widget can be inserted anywhere it is needed in your web pages (as long as the domain for those pages has been included in the api.xml file as described above). Some customers may want to consider placing the widget in pages that are only accessible to your organisation’s end users who have already been validated by logging in to your web pages (to limit who can use this widget style form, as there is limited ability to include other spammer traps in widget technology).
These instructions will insert the widget, with the distribution layout, in your web pages for testing. Later steps of these instructions will explain how to change how it looks and works.
Insert this code at the place in your web page/s where you want the widget to appear (in the <body>), ensuring that you replace the apikey with your parameter 9.50 APIkey and the domain with your RefTracker system domain.

<script id=”rtqqwidget” apikey =”{9.50ParameterAPIkey}” src=”https://{yourReftrackerDomain}/exchange/widget/js/qq.min.js” type=”text/javascript”>
</script>
<div id=”rtqqwidget_container_popup”></div>
<!– <div id=”rtqqwidget_container_embedded”></div> –>
<!– <div id=”rtqqwidget_container_auto”></div> –>
<!– <div id=”rtqqwidget_container_custom”></div> –>

Notes about this code:
– The “container” lines provide all options for you to choose which style of widget will be used. The example above will insert the popup style widget. To use a different style, uncomment the line for that other style and comment out the popup line. The commented out lines for the other styles have been included so you can easily change between styles, but it is only necessary to include the one line for the style you want to use – you can remove the others, if you prefer.
– Some web site content management systems may require that the <script> line of this code be inserted in the <head> part of the page rather than in the <body> of the page.
-This code presumes that jquery has already been included in the page (as it usually has been). If jquery is not already included in the page, you will also need to add this line of code at the end of the <head> division (just above </head>).

<script src=’https://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js‘>
</script>

As a reminder, the “widget type” options that you can select in this code are as follows (see the beginning of this point, and “The RefTracker widget” help page for more details about using these types):
Popup – adds a sticky launch button in the bottom right of the browser screen and displays the form when that button is clicked. The button and widget float above the page so that they are always visible no matter where you move on the page.
Embedded – just adds the widget right into the page, without having to use an iframe. The default size of the widget is 390 px wide, but this can be adjusted using css. The height will depend on the number of fields you include in your widget (with four fields it is 465px high – adjust the fields that display using the Quick Question Widget request form).
Auto – automatically (proactively) shows the widget x seconds after the web page displays (no launch button is needed). The default parameters have it displaying 10 seconds after the page displays (adjust attributes like this using the qqform text template):
Custom – adds the popup widget to the page but hidden – its up to the designer of the page to trigger the showing of the popup widget, for example you could have the widget display when a button in your web page is clicked (however, if you are going to have a button in a page your should consider whether a traditional RefTracker form where the form can ensure that the end user provides all of the data required to successfully answer their specific type of request, is more appropriate. Remember that this widget has a specific purpose of attracting quick questions and requests for assistance – that you might want to call “Quick assist” or “Quick meet” services).
Here’s an example of how to code for the custom widget to be instigated from a button in your web page (don’t for get to add your API key for security):

5 Adjust the RefTracker Request form configuration:

The widget uses the “Quick Question Widget” Request form, to control how the RefTracker request is created from the widget. This form can be found at System>Request forms summary like all other Request forms.

Note that for the widget to work, this form MUST be set to enabled for External client use. It is distributed that way, but if you are having issues with the widget not showing, check the “Enabled” box in the Main access options tab of that form’s Edit options mode is ticked, and, in the “Client availability” parameter make it available for “External” client use. The form should not be made available for staff use.

This Quick Question Widget form is a System form, and so cannot be deleted, but it can be amended to better suit your requirements.

Your widget can have up to five fields (Name, Email address, Meeting room URL, Subject and Question) but you can configure yours to only have some of them (minimum is email address and your request description – Question), and they may have different labels in your system. All fields displaying in the widget are mandatory fields!

The important things about your Quick Question Widget design are the labels for the fields, and additional fields you want to include as hidden fields to collect known information, and the Edit options settings for the form.

The Quick Question Widget form layout must always include the Response method, Client email address, Client name, Meeting URL, Subject line, Request text fields. You select which of these fields actually show in the widget, in the next step (the qqform text template), and all fields you include in the widget, via the qqform, will be mandatory no matter how you have them defined in this Quick Question Widget request form.
The labels you define for the fields you use in the Quick Question Widget request form will be the labels seen in the widget, so set them accordingly!

In this form you will most likely set Response method to email (or Meeting app perhaps), so you may also want to adjust the email templates that will be used.
However, note that Response method is actually set by the data provided in the widget – if an email address is provided, the Response method will be set to email. If an email address is not provided and a meeting room app link is provided, the Response method will be set to Meeting room app.

Other fields can be added to the Quick Question Widget form like Priority, and any other known information about the users of your widget, but none of these other fields will show in the widget.

All other Request form attributes that relate to handling of the question created using this form and the widget, can be set in the “Quick Question Widget” Request form, and will apply to all questions that come in through the Widget e.g. Target Date, Item Summary, Classify on receipt, etc.
Set all the other form attributes to suit your needs using Edit options, as you would for any other Request form. Options that relate to the layout of the form are irrelevant to the widget (e.g. the Captcha and Attachment options), and can be ignored.

If you use Dynamic Lookups, you can also add the same Dynamic Lookups definition to this form as you use in your Email importing form (a Post pop lookup on email address or name, in Edit options, Lookups tab), and the lookup data will be added as the Widget information is submitted.

The distribution “Quick Question Widget” form has its Target date set to 1 weekday and its Needs attention Response value set to the same thing so that these questions arrive with the Target date highlighted and “Needs attention” already shows in the Allocation column to draw attention to the need for a quick response. It also has Priority set to High and an Item summary of “Widget request” to further draw attention to the need for a quick response to these requests.
The distribution “Quick Question Widget” form does NOT send a confirmation email on the presumption that the objective of this service is to get responses back to the client very quickly (minutes rather than hours) but you may well want to change the request form to specify a confirmation email depending on the objectives of your service.
Even if these distribution settings suit your needs you WILL need to check and amend this “Quick Question Widget” form as other attributes such as Request type, Classify on receipt, and Answering and Closing data collection fields will all need to be set to suit your specific needs. We particularly recommend that you look at how the form will be allocated on arrival. You might want to provide an email address/es to be notified when one of these requests arrives. You might also want to change the Request type and set “Classify on receipt” to “Yes” so that staff have to set a correct Request type when they start working on one of these questions.

For this form, the layout you see in Preview is never seen by clients – they just see the resulting widget.

To test the setup you have created, go to Preview mode for the form and use the link to the embedded widget test page provided in the first division of the form, as it displays in that page.

6 Adjust the widget configuration:
The operation of the widget, and the confirmation pop up, are controlled by the qqform.htm text file. Make a Local copy of it using System>Utilities>Administration utilities>Template editor (text) if you need to customise any of the following things to meet your needs.

This template includes important coding and MUST be edited using HTML edit mode. Do not remove any of the coding, but you can change any of the text and settings to better suit your style.

You can remove the Client name, Subject line and/or Meeting room link fields from the widget by simply commenting out (<!– –>) the entire div’s that provide those lines in the qqform. (The labels for the fields in the widget come from the associated Quick Question Widget Request form as described in point 5 above, not from these definitions).

Note that Response method is actually set by the data provided in the widget – if an email address is included in the qqform, the Response method will be set to email. If an email address is not provided and the meeting room app link field is provided, the Response method will be set to Meeting room app.

By definition, ALL fields included in the widget are mandatory for completion by the end user.

You can change all the text used in the widget (other than the field labels) by changing it in this qqform file, for example you may want to add more information to the popup confirmation – such as “We’ll get back to you soon”, or “A copy of your message has been emailed to the address you provided”. Or you might want to change the “Email us” heading to something like “Ask us for help!”

You also need to check the settings for the time delays relevant to the widget type that you are inserting, if relevant. Here are the defaults:
   <!– responseDelay = seconds response confirmation information will display for (relevant to all types) –>
   <!– resetDelay = seconds before the form will be cleared after last input – ensures entered information is cleared for security/privacy reasons (relevant to all types)–>
   <!– autoDelay = seconds before the popup will display after page loads in auto style–>
   <span id=”rtqqwg_settings” style=”display:None;”>
   responseDelay=10|resetDelay=180|autoDelay=10</span>

If you are at all unsure about how to edit this qqform file, please ask your RefTracker support representative to edit it for you – send a mark-up of the widget showing the changes that you want.

7 Set the Widget css if necessary:
The colour and size of the widget and its associated button are controlled by widget.reftracker.css that can be found at System>Utilities>Administration utilities>File upload/download and then selecting the include/css directory, but if you want to provide custom css, do it in widget.local.css so your code is protected from software updates. The widget.local.css file is automatically included when you insert the widget code, so it just need to include any addition or overriding css (use !important).
Because the widget uses this RefTracker provided css file, it inherits its colours from the RefTracker css that can be managed at System>Utilities>Administration utilities>Colour scheme editor, Widget tab, unless you specifically set other colours in the widget.local.css file.

8 Statistics for questions received via the widget:
Widget questions appear in your Requester service statistics. To find the number of requests coming through your widget, do a code table analysis on “Received via”. There is a new Received via code table entry “Widget” that is applied to all requests received via the widget.

9 Diagnosing issues with the widget:
When inserting the widget code in your web pages, you may come across issues (usually related to conflicts with other things in the page you are inserting it into).
A debug mode can be instigated by adding

data-debug=”1″

to the widget script – like this:

And if that flag is on, the widget will output messages to the browser console log, like this:

Also the script will add a meta tag to the page when it is executed. If this meta tag exists then we know that the script has already been run.

< Previous Page

External mode access

Next Page >

Using and interfacing RefTracker with other systems