IFrame Query API
Use this API to query if there are survey opportunities available for a respondent.
When surveys are available, you can use the provided "offerURL" in the API's output to set as the source of your iFrame or to display it on WebView.
Command
"iframe/query/1"
Inputs
The following values are expected in the JSON body:
Name | Type | Required | Description |
---|---|---|---|
command | String | Must be "iframe/query/1" |
|
rid | String | A string uniquely identifying the respondent. The same string must be sent on repeat visits, allowing us to target using previously collected data. |
|
country | String | The 2 digit ISO country code |
|
postalCode | String | Australia, South Africa: 4 digits |
|
gender | String | Accepted values:
|
|
birthday | String | The respondent's birthday, formatted as yyyy-MM-dd |
|
unitConv | Integer | The number of units awarded for each US Dollar that we pay you. In the example command below, if we have a survey where the payout to you is $2.50, the respondent would be shown "50 Silver Coins". |
|
ip | String | String value corresponding to the respondent's IP. If included, we will use it to consider only the surveys where a respondent with the same IP has not participated, thus reducing the probability of a term due to deduplication. |
|
fingerprint | String | The code to compute the fingerprint is available at https://hosting.researchforgood.com/js/df-fp.js
|
|
**See description for possible values | * | Additional Datapoints In addition to the above parameters, you may also send us any of the datapoints listed in the RFGdatapoints.json file.
Datapoint TypesDatapoint types may be:
For these optional datapoints, you may provide as few or as many as you wish. Any datapoints not provided will be profiled when the respondent begins to take surveys. Please note that some datapoints only apply to certain countries. If a datapoint does not list countries, then it applies to all countries. |
Outputs
Name | Type | Description |
---|---|---|
offer | String | Indicates if we have surveys available for the respondent. Possible values:
|
offerURL | String | Only returned if we have surveys available for the respondent. You should use this URL as source of the iframe or WebView where you want to display our surveys. |
Example Command
{
"command": "iframe/query/1",
"rid": "4e882a9bc2748d24",
"country": "US",
"postalCode": "10025",
"gender": "m",
"birthday": "1977-02-25",
"unitName": "Silver Coins",
"unitConv": 20,
"ip":"57.143.126.61",
"fingerprint":"c042ac342900efdfceee4a2edb549f5c",
"employees_number":2 //Additional non-mandatory datapoint
}
Example Response
On success, the API will respond as follows:
{
command: "iframe/query/1",
result: 0,
response: {
offer: "yes",
offerURL: "http://www.saysoforgood.com/iframe/......"
}
}
If no surveys are available, the response will be as follows:
{
command: "iframe/query/1",
result: 0,
response: {
offer: "no"
}
}