Skip to main content

​
Overview

The Review API evaluates an open-ended text answer together with data about how it was entered. The Research Defender review library runs in the respondent’s browser and collects that data, including pasted text, timestamps, and behavioral data. When the respondent submits, your page sends the answer and the collected data to the Review API. You can send the request with POST or GET. Both use the same fields.
Use POST. Answers and behavioral data can be long and may contain line breaks, quotes, and personal content. With GET, all of it goes into the URL, which has length limits and is often written to server and proxy logs.

​
How it works

1

Load the library

Add the review library script to the <head> of your page.
2

Add the page elements

Add the answer field, a submit button, and the fields the library writes its data into.
3

Create the library

Create scReviewLib when the page has loaded, passing your environment URL, publishable key, the element IDs, and your listeners.
4

Send the review on submit

In submitEventListener, read the answer and the collected data from the page and call the Review API.

​
Prerequisites

  • A Research Defender publishable key
  • A page served over HTTP(S). Opening the file directly from disk (file://) will not work.

​
Step 1: Load the library

Add the library to the <head> of your page.
Use the same environment in the library URL and in your code. For example, if the script loads from prod.rtymgt.com, set ENVIRONMENT to "prod". A mix of environments is a common cause of failures.

​
Step 2: Add the page elements

The library reads from and writes to elements on your page. Each one needs an ID, which you pass to the library.
The five fields the library writes to are meant to be hidden. The sample shows them so you can see the collected data. In production, use type="hidden" for them.

​
Step 3: Create the library and send the review

Create scReviewLib after the page has loaded. The constructor takes these arguments, in order.

​
Review API request

​
string
GET or POST https://{environment}.rtymgt.com/api/v4/respondents/review/{publishable_key}
For a POST request, send the fields as a JSON body. For a GET request, send them as query parameters.
​
string
required
The question ID.
​
string
required
The question text shown to the respondent.
​
string
required
The respondent’s answer.
​
string
The pasted text collected by the library.
​
number
A number. The sample uses 5.
​
string
The page load timestamp collected by the library.
​
string
The timestamp of when the respondent started entering the answer, collected by the library.
​
string
The submit timestamp collected by the library.
​
string
The behavioral data collected by the library.
Send the request with credentials (credentials: "include") so Research Defender cookies are included.

​
Examples

review-post.js
The two examples differ only in sendReview(). The POST version sends a JSON body built with JSON.stringify, which correctly handles quotes, line breaks, and special characters in the answer. The GET version encodes the same fields into the URL with URLSearchParams.

​
Full HTML pages

If you want a complete page you can open in a browser, use one of the samples below. Replace the placeholder values at the top of the script, then serve the file over HTTP(S).
review-post-integration.html
review-get-integration.html

​
Handling errors

The samples show the API’s error message on the page, write it to the browser console, and always re-enable the submit button so the respondent is never left waiting. Decide in advance what your survey should do when a review fails.

​
Troubleshooting