Introduction
Welcome to the Usabilla API documentation. Here you will find a detailed guide on how to access the data related to your customers' feedback.
You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. On top of this, we've also included our client repositories we have on GitHub.
Usabilla maintains the following client libraries:
- Usabilla API PHP Client
- Usabilla API Python Client
- Usabilla API Go Client
- Usabilla API Node.js Client
Client libraries maintained by third parties:
- Usabilla API Ruby On Rails Client - maintained by Jon Molinaro (CareerBuilder.com)
- Usabilla API Shell Script - maintained by Alexander Vellekoop (Aegon.nl)
If you wrote a public client library that would be beneficial to fellow coders, we would love to hear about it and include it in our documentation, please send us a link to your project repository.
If you prefer to use a language we do not provide a client library for you can continue to the next section to see how our authentication method works. Please contact support if you need help calling our API.
Authentication
The authentication code for each language can be found under the respective GitHub pages:
The credentials consist in an access key and a secret key used for authentication purposes. You can acquire the credentials by logging into your Usabilla account and access the following link or navigating to the settings menu under the tab Usabilla API. If you're new to the Usabilla API then we recommend you to read through our support article on Getting Started with the Usabilla Public API. Our API authentication system is inspired by the signed AWS API requests.
1. Create a Canonical Request
To begin the signing process, you create a string that includes information from your request in a standardized (canonical) format. This step will allow you to create a canonical request string which will be used by our servers to verify the signed request.
Follow the steps here to create a canonical version of the request. Otherwise, your version and the version calculated by our servers won't match, and the request will be denied.
The following example shows the pseudocode to create a canonical request:
CanonicalRequest =
HTTPRequestMethod + '\n' +
CanonicalURI + '\n' +
CanonicalQueryString + '\n' +
CanonicalHeaders + '\n' +
SignedHeaders + '\n' +
HexEncode(Hash(RequestPayload))
Example request
To show you how to construct the canonical form of an HTTP request, we'll use the following example request. The original request might look like this as it is sent from the client to our servers, except that this example does not include the signing information yet.
GET https://data.usabilla.com/ HTTP/1.1
Host: data.usabilla.com
Date: 20150830T123600Z
To create a canonical request, concatenate the following components from each step into a single string:
Start with the GET, HTTP request method written in upper case, followed by a newline character. Example request method:
GET
Add the canonical URI parameter, followed by a newline character.
If the absolute path is empty, use a forward slash (/). In the example request, nothing follows the host in the URI, so the absolute path is empty.
Example canonical URI:
/button
- Add the canonical query string, followed by a newline character.
If the request does not include a query string, use an empty string (essentially, a blank line). The example request does not contain a query string:
Example canonical query string:
?limit=1&since=123456789
To construct the canonical query string, complete the following steps:
a. URI-encode each parameter name and value according to the following rules: do not URL-encode any of the unreserved characters that RFC 3986 defines: A-Z
, a-z
, 0-9
, hyphen (-
), underscore (_
), period (.
), and tilde (~
); and percent-encode all other characters with %XY, where X and Y are hexadecimal characters (0-9 and uppercase A-F).
b. Sort the encoded parameter names by character code.
c. Build the canonical query string by starting with the first parameter name in the sorted list.
d. For each parameter, append the URI-encoded parameter name, followed by the character =
(ASCII code 61), followed by the URI-encoded parameter value. Use an empty string for parameters that have no value.
e. Append the character &
(ASCII code 38) after each parameter value except for the last value in the list.
Example authentication parameters in a query string:
The following example shows a query string that includes authentication information.
Algorithm=USBL1-HMAC-SHA256&
Version=2010-05-08&
Credential=AKIAIOSFODNN7EXAMPLE%2F20150112%2Fusbl1_request&
Date=20150112T135139Z&
SignedHeaders=date%3Bhost
- Add the canonical headers, followed by a newline character. The canonical headers consist of a list of all the HTTP headers. The required headers are host and date.
Example canonical headers:
host:data.usabilla.com\n
date:20150111T003735Z\n
To create the canonical headers list, convert all header names to lowercase and trim excess white space characters out of the header values. When you trim, remove leading spaces and trailing spaces, and convert sequential spaces in the value to a single space. However, do not remove extra spaces from any values that are inside quotation marks.
The following pseudocode describes how to construct the canonical list of headers:
CanonicalHeaders = CanonicalHeadersEntry[0] + CanonicalHeadersEntry[1] + ... + CanonicalHeadersEntry[n]
CanonicalHeadersEntry = lowercase(HeaderName) + ':' + trimall(HeaderValue) + '\n'
lowercase
represents a function that converts all characters to lowercase, and trimall
function removes excess white space before and after values and from inside non-quoted strings, per RFC 2616 Section 4.2.
Build the canonical headers list by iterating through the collection of header names and sorting the headers lowercase character code. Construct each header by using the following rules:
* Append the lowercase header name followed by a colon.
* Append a comma-separated list of values for that header. If there are duplicate headers, the values are comma-separated. Do not sort the values in headers that have multiple values.
* Append a new line (\n
).
The following two samples compare a more complex set of headers with their canonical form:
Example original headers:
host:data.usabilla.com\n
date:20150111T003735Z\n
Example canonical form:
date:20150111T003735Z\n
host:data.usabilla.com\n
To create the signed headers list, convert all header names to lowercase, sort them by character code, and use a semicolon to separate the header names. The following pseudocode describes how to construct a list of signed headers.
lowercase
represents a function that converts all characters to lowercase.SignedHeaders =
lowercase(HeaderName0) + ';' + lowercase(HeaderName1) + ";"
+ ... + lowercase(HeaderNameN)
Build the signed headers list by iterating through the collection of header names, sorted by lowercase character code. For each header name except the last, append a semicolon (';') to the header name to separate it from the following header name.
Only the host and date headers are required. Optionally if the users have added additional headers to the CanonicalHeaders these will also be required. Note: Certain API calls require additional headers to be present in the signed headers list.
Example request: Signed headers
host;date
Use the hash (digest) function SHA256 and create a hashed value from the RequestPayload in the body of the HTTP or HTTPS request. Since none of the current API calls support a request body the RequestPayload must always be the empty string. Therefore the RequestPayload will always be the hexadecimal SHA-256 hash of an empty string.
HashedPayload = Lowercase(HexEncode(Hash(requestPayload)))
Example request: RequestPayload
empty string
Example request: Hashed RequestPayload
The following example shows the result of using SHA-256 to hash the example RequestPayload.
3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2
To construct the finished canonical request, combine all the components from each step as a single string. As noted, each component ends with a newline character. If you follow the canonical request pseudocode explained earlier, the resulting canonical request is shown in the following example:
Example canonical request:
GET
/live/website/button
date:Mon, 12 Jan 2015 13:57:54 GMT
host:data.usabilla.dev
date;host
3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2Create a digest (hash) of the canonical request by using the same algorithm that you used to hash the RequestPayload. The hashed canonical request must be represented as a string of lowercase hexademical characters.
Example hashed canonical request:
3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2
2. Create a String to Sign
The string to sign includes meta information about your request and about the canonical request. To create the string to sign, concatenate the algorithm, date, credential scope, and the digest of the canonical request, as shown in the following pseudocode:
Structure of the String to Sign:
StringToSign =
Algorithm +
RequestDate +
CredentialScope +
HashedCanonicalRequest
Example of a HTTPS request:
GET
/live/website/button
date:Mon, 12 Jan 2015 13:57:54 GMT
host:data.usabilla.dev
date;host
3511de7e95d28ecd39e9513b642aee07e54f4941150d8df8bf94b328ef7e55e2
To create the string to sign:
Start with the algorithm designation, followed by a newline character. This value is the hashing algorithm that you're using to calculate the digests in the canonical request.
USBL1-HMAC-SHA256\n
Append the request date value, followed by a newline character. The date is specified by using the ISO8601 Basic format via the Date header in the
YYYYMMDD'T'HHMMSS'Z'
format. This value must match the value you used in any previous steps.20150112T135139Z\n
Append the credential scope value, followed by a newline character. This value is a string that includes the date and termination string (
usbl1_request
) in lowercase characters.20150112/usbl1_request\n
The date must be in the
YYYYMMDD
format. Note that the date does not include a time value.Append the hash of the canonical request that you created in task 1; Create a canonical Request. This value is not followed by a newline character. The hashed canonical request must be lowercase base-16 encoded, as defined by Section 8 of RFC 4648
daf6b02d8ae6809bf3b2445c480c1ee6038da1a19a2bd5ad21b7a30acd0fdec2
Example string to sign:
USBL1-HMAC-SHA256
20150112T135139Z
20150112/usbl1_request
daf6b02d8ae6809bf3b2445c480c1ee6038da1a19a2bd5ad21b7a30acd0fdec2
3. Calculate the Signature
Before you calculate a signature, you derive a signing key from your Usabilla secret key.
To calculate a signature:
Derive your signing key. To do this, you use your secret access key to create a series of hash-based message authentication codes (HMACs) as shown by the following pseudocode, where HMAC(key, data) represents an HMAC-SHA256 function that returns output in binary format. The result of each hash function becomes input for the next one.
Pseudocode for deriving a signing key:
kSecret = Your Usabilla Secret Key
kDate = HMAC("USBL1" + kSecret, Date)
kSigning = HMAC(kDate, "usbl1_request")Use the digest for the key derivation. Most languages have functions to compute either a binary format hash, commonly called a digest, or a hex-encoded hash, called a hexdigest. The key derivation requires that you use a digest.
Example inputs:
HMAC(HMAC("USBL1" + kSecret,"20110909"),"usbl1_request")
The following example shows the derived signing key that results from this sequence of HMAC hash operations, using the inputs shown in the previous example. This representation shows the digit representation of each byte in the binary derived key.
Example signing key:
152 241 216 137 254 196 244 66 26 220 82 43 171 12 225 248 46 105 41 194 98 237 21 229 169 76 144 239 209 227 176 231
Calculate the signature. To do this, use the signing key that you derived and the string to sign as inputs to the keyed hash function. After you've calculated the signature as a digest, convert the binary value to a hexadecimal representation.
Pseudocode for calculating the signature:
signature = HexEncode(HMAC(derived-signing-key, string-to-sign))
Note: Make sure you specify the HMAC parameters in the correct order for the programming language you are using. This example shows the key as the first parameter and the data (message) as the second parameter, but the function that you use might specify the key and data in a different order.
Example signature:
ced6826de92d2bdeed8f846f0bf508e8559e98e4b0199114b84c54174deb456c
4. Sign the Request
After you have calculated the signature, add it to the Authorization header of your request.
The following pseudocode shows the construction of the Authorization header:
Authorization: algorithm
Credential=access key ID/credential scope,
SignedHeaders=SignedHeaders,
Signature=signature
The following example shows a finished Authorization header:
Authorization: USBL1-HMAC-SHA256
Credential=AccessKey/20130524/usbl1_request,
SignedHeaders=date;host;user-agent,
Signature=fe5f80f77d5fa3beca038a248ff027d0
445342fe2855ddc963176630326f1024
Note the following:
There is a space between the algorithm and Credential, not a comma. On the other hand, the SignedHeaders and Signature values are separated from the earlier values using a comma.
The Credential value starts with the access key, which is prefixed with a slash (/) onto the credential scope value that you calculated earlier. In contrast, the secret access key is used to derive the signing key for the signature, but is not included in the signing information that's sent in the request.
Request URL structure
This section covers the resources that can be requested.
https://data.usabilla.com/live/<product-name>/<resource-type>/<id>/<nested-resource>?params
Parameters
Field | Type | Description |
---|---|---|
id | String | The id of the resource |
params | String | Query URL parameters |
200 OK
{
"items": [
...
],
"count": 0,
"hasMore": false,
"lastTimestamp": 1419340238645
}
Field | Type | Description |
---|---|---|
items | Array | An array containing items of the requested resource type |
count | Integer | The number of items returned |
hasMore | Integer | A flag that indicates whether more items can be requested |
lastTimestamp | Timestamp | The timestamp of the last item in the items array. Can be used to request more items when hasMore is true |
Errors
403 Forbidden
{
"error": "Invalid client key"
}
Field | Description |
---|---|
DateError | Date is not valid |
SignatureDoesNotMatch | The signature does not match the content |
SignatureMissing | Request doesn't have a signature |
TokenMismatch | Token not found |
HostError | Requested host is not valid |
404 Not Found
Field | Description |
---|---|
NotFound | Invalid URL |
429 Too Many Requests
Field | Description |
---|---|
TooManyRequests | Request limit reached, please contact your Usabilla account manager |
RateLimitExceeded | Request rate too high |
500 Internal Server Error
{
"error": "The server has encountered an error."
}
Field | Description |
---|---|
DatabaseError | Account Provider not available |
WrongCodec | Signed algorithm is not valid |
QueryFailed | Could not query |
AuthenticationFailed | Please re-authenticate |
Usabilla for Websites
Feedback Button
This section covers the resources that can be requested regarding Usabilla's Feedback buttons. The feedback button is a button widget that is shown on your website at a visible but non-obtrusive location to enable visitors to leave feedback on their experience.
Get Buttons
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all buttons for this account.
usabilla.websites.buttons
.get()
.then(buttons => {
const button = buttons[0];
if (!button) {
return;
}
})
.catch(reason => {
// If the usabilla call fails, we want to see the error message
console.error(reason);
});
import usabilla as ub
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Get all buttons for this account
buttons = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES,api.RESOURCE_BUTTON)
# Print first button
first_button = buttons['items'][0]
print first_button['name']
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Gets the command.
$command = $client->getCommand('GetWebsiteButtons');
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
package main
import (
"os"
"fmt"
"github.com/usabilla/api-go"
)
func main() {
key := os.Getenv("USABILLA_API_KEY")
secret := os.Getenv("USABILLA_API_SECRET")
// Pass the key and secret which should be defined as ENV vars
usabilla := usabilla.New(key, secret, nil)
resource := usabilla.Buttons()
// Get the first ten buttons
params := map[string]string{"limit": "10"}
buttons, _ := resource.Get(params)
}
The data will be received in JSON format like this:
{
"id": "8d73568ac2be",
"name": "My website feedback button"
}
Endpoint
GET /live/websites/button
This request returns all your feedback buttons in JSON format as shown to the right.
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier for a button. 12 characters long. |
name | String | The name of the button given when created. Can be updated in the button setup page. |
Get Feedback Items
/* eslint-disable no-console */
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Use a button id to get feedback for a specific button.
let buttonFeedbackQuery = {
id: button.id,
params: {
limit: 10
}
};
usabilla.websites.buttons.feedback
.get(buttonFeedbackQuery)
.then(feedback => {
console.log('# button feedback', feedback.length);
})
.catch(reason => {
console.error(reason);
})
.catch(reason => {
// If the usabilla call fails, we want to see the error message
console.error(reason);
});
import usabilla as ub
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Get the feedback items from a specific button
feedback_items = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_FEEDBACK, 'button_id', iterate=True)
print len([item for item in feedback_items])
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//NonMandatoryIdParam defaults to * if not set, must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'NonMandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetWebsiteFeedbackItems', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
package main
import (
"os"
"fmt"
"github.com/usabilla/api-go"
)
func main() {
key := os.Getenv("USABILLA_API_KEY")
secret := os.Getenv("USABILLA_API_SECRET")
// Pass the key and secret which should be defined as ENV vars
usabilla := usabilla.New(key, secret, nil)
resource := usabilla.Buttons()
// Get the first ten buttons
params := map[string]string{"limit": "10"}
buttons, _ := resource.Get(params)
// Print all feedback items for each button
for _, button := range buttons.Items {
feedback, _ := resource.Feedback().Get(button.ID, nil)
fmt.Printf("Feedback for button: %s\n%v\n", button.ID, feedback.Items)
}
}
The data will be received in JSON format like this:
{
"buttonId": "07f5ec0c3b93",
"comment": "asd",
"custom": null,
"date": "2015-04-28T14:48:39.289Z",
"email": "",
"id": "553f9dc7d350221532dfa715",
"image": "",
"labels": [],
"location": "Netherlands",
"nps": 10,
"publicUrl": "https://www.usabilla.com/feedback/item/538ce51b93804a7f568324fbef81e6559743ba7e",
"rating": 5,
"tags": [],
"url": "https://staging.usabilla.com/",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36"
}
After a visitor leaves feedback on a button it becomes a feedback item that consists of several data fields.
Endpoint
GET /live/websites/button/:id/feedback
Parameters
Field | Type | Description |
---|---|---|
id | String | The button id. If you wish to get all available feedback items use * (asterisk) as value. |
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Default value is 100. |
since | Timestamp | [Optional] UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the feedback item. |
userAgent | String | Information about the browser's user-agent. |
comment | String | Comment given by the user in the feedback form. |
commentTranslated | String | The translated version of the comment given by the user. |
commentTranslatedFrom | String | The language from which the translation was made. |
location | String | String containing geographical information about the location of the user based on the user's ip address. |
date | Date | The creation date of the feedback item, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
custom | Map | Custom variables that have been assigned in the button setup page. |
String | Optional field that the user fills in in case he wishes to be contacted. | |
image | String | The screenshot of the specific item that has been selected to give feedback on. |
labels | Map | An array of labels that have been assigned to the feedback item. |
nps | Integer | The Net Promoter Score given by the user (0-10). |
publicUrl | String | When the owner of the button has publicized the feedback item it becomes publicly accesible through this URL. |
rating | Integer | Rating given by the user (0-5). |
buttonId | String | The source button of the feedback item. |
tags | Array | An array of tags assigned to the feedback item. |
url | Integer | The link through which the source button can be accessed in the backend. |
Campaigns
This section covers how to retrieve data for Usabilla Campaigns. These surveys are aimed towards web users with specific targeting options set up. The survey will trigger without the users intent, actively asking for feedback.
Get Campaigns
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all campaigns
usabilla.websites.campaigns
.get()
.then(campaigns => {
const campaign = campaigns[0];
console.log('# campaigns', campaigns.length);
if (!campaign) {
return;
}});
import usabilla as ub
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Get all campaigns
campaigns = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_CAMPAIGN)
first_campaign = campaigns['items'][0]
print first_campaign['name']
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetWebsiteCampaigns', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
// Go example under construction
The data will be received in JSON format like this:
{
"id": "5499612ec4698839368b4573",
"date": "2014-01-15T19:48:06.003Z",
"buttonId": "8d73568ac2be",
"analyticsId": "901f1d832a55",
"status": "active",
"name": "My campaign",
"type": "boost",
"url": ""
}
Endpoint
GET /live/websites/campaign
This request returns a list of your Usabilla for Websites Campaigns.
Parameters
Field | Type | Description |
---|---|---|
limit | Integer | Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier for a campaign. |
date | Date | The creation date of the campaign, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
buttonId | String | The source button that triggers the campaign. |
analyticsId | String | Analytics ID. |
status | String | The status of the campaign. Possible values are created , active , paused and finished . |
name | String | The name of the campaign given when created. Can be updated in the campaign setup page. |
type | String | The type of the campaign. |
url | String | The url of the campaign when the campaign is of type Survey , empty otherwise. |
Get Campaign Results
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Specify a campaign id
let campaignQuery = {
id: campaign.id
};
// Get the responses from a campaign with the specific id
usabilla.websites.campaigns.results
.get(campaignQuery)
.then(responses => {
console.log('# web campaign responses', responses.length);
})
.catch(reason => {
console.error(reason);
});
import usabilla as ub
if __name__ == '__main__':
# Get the responses of a specific campaign
responses = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_CAMPAIGN_RESULT, <CAMPAIGN_ID>, iterate=True)
print len([item for item in responses])
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//MandatoryIdParam must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetWebsiteCampaignResults', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "549972d5c469885e548b4570",
"campaignId": "5499612ec4698839368b4573",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36",
"location": "Amsterdam, Netherlands",
"date": "2014-01-15T19:48:06.003Z",
"customData": {
"form_name": "form1"
},
"data": {
"text": "test"
},
"time": 5000,
"url": "https://usabilla.com"
}
Endpoint
GET /live/websites/campaign/:id/results
This request returns the responses of a campaign with a specific id.
Parameters
Field | Type | Description |
---|---|---|
id | String | The campaign id. Use * (asterisk) to request feedback of all campaigns. |
limit | Integer | Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success 200
Field | Type | Description |
---|---|---|
id | String | Unique identifier for a campaign result. |
date | Date | The creation date of the campaign result item, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
campaignId | String | Unique identifier for the campaign it belongs to. |
userAgent | String | Information about the browser user agent. |
url | String | Origin URL where the campaign result was registered. |
customData | Map | Custom variables that have been assigned to the campaign result. |
data | Array | An array containing the values of the campaign form fields. |
time | Integer | The amount of time the user has taken to complete the survey. Expressed in miliseconds. |
location | String | String containing geographical information about the location of the user based on the user's IP address. |
Get Campaign Statistics
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get the stats of the first campaign
usabilla.websites.campaigns.stats
.get(campaignQuery)
.then(stats => {
console.log('# web campaign stats', stats);
})
.catch(reason => {
console.error(reason);
});
import usabilla as ub
if __name__ == '__main__':
# Get the stats of the first campaign
stats = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_CAMPAIGN_STATS, first_campaign['id'])
print stats
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//MandatoryIdParam must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetWebsiteCampaignStats', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "549972d5c469885e548b4570",
"completed": 5,
"conversion": 83,
"views": 6
}
Endpoint
GET /live/websites/campaign/:id/stats
This endpoint returns the statistics of a campaign with a specific id.
Parameters
Field | Type | Description |
---|---|---|
id | String | The campaign id. Use * (asterisk) to request feedback of all campaigns. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier for a campaign result. |
completed | Integer | The amount of completed campaign forms that were submitted. |
views | Integer | The amount of views the campaign form got by counting how many times it was opened. |
conversion | Integer | The percentage of conversion (views to completion). |
In-Page
This section is regarding the Usabilla In-Page product and how to retrieve the feedback data. The In-Page widget can be placed anywhere on your webpage for users to give valuable feedback on the web content.
Get In-Page Widgets
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all inpage widgets for this account.
usabilla.websites.inpage.get()
import usabilla as ub
# Create an API client with access key and secret key
api = ub.APIClient('ACCESS_KEY', 'SECRET_KEY')
api.set_query_parameters({'limit': 10})
# Get all In - Page Widgets for this account
widgets = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_INPAGE)
print(widgets)
# Get one specific widget
specific_widget = widgets['items'][1]
print(specific_widget)
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetInpageWidgets', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "5499612ec4698839368b4573",
"date": "2014-01-15T19:48:06.003Z",
"name": "My In-Page widget"
}
Endpoint
GET /live/websites/inpage
This endpoint returns a list of your Usabilla for Websites In-Page widgets.
Parameters
Field | Type | Description |
---|---|---|
limit | Integer | Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier for an In-Page widget. |
date | Date | The creation date of the In-Page widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
name | String | The name of the In-Page widget given when created. Can be updated in the In-Page widget setup page. |
Get In-Page Feedback
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all inpage widgets for this account.
usabilla.websites.inpage
.get()
.then(inPageWidgets => {
// Get the feedback for an inpage widget with id.
let inPageQuery = {
id: inPageWidgets[0].id
};
// Get the feedback of the first inpage widget
usabilla.websites.inpage.feedback
.get(inPageQuery)
.then(feedback => {
console.log('# inpage feedback', feedback.length);
})
.catch(reason => {
console.error(reason);
});
})
.catch(reason => {
// If the Usabilla call fails, we want to see the error message
console.error(reason);
});
import usabilla as ub
# Create an API client with access key and secret key
api = ub.APIClient('ACCESS_KEY', 'SECRET_KEY')
# Get feedback of the first widget
feedback = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_WEBSITES, api.RESOURCE_INPAGE_RESULT, 'WIDGET_ID', iterate=False)
print(feedback)
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//MandatoryIdParam must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetInpageWidgetFeedbackItems', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "549972d5c469885e548b4570",
"date": "2014-01-15T19:48:06.003Z",
"widgetId": "5499612ec4698839368b4573",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36",
"location": "Amsterdam, Netherlands",
"geo": {
"city": "Schoten",
"country": "BE",
"region": "01"
},
"comment": "Very nice indeed",
"data": {
"Did_you_enjoy_th": 5
},
"customData": {
"form_name": "form1"
},
"mood": 3,
"rating": 0.5,
"nps": 5,
"url": "https://usabilla.com"
}
Endpoint
GET /live/websites/inpage/:id/feedback
This endpoint returns a list of your Usabilla for Websites In-Page feedback.
Parameters
Field | Type | Description |
---|---|---|
id | String | The In-Page widget id. Use * (asterisk) to request feedback of all In-Page widgets. |
limit | Integer | Optional. URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional. UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier for the In-Page widget feedback item. |
date | Date | The creation date of the in-page widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
data | Array | An array containing the values of the In-Page widget form fields. |
customData | Array | An array containing the values of the widget's custom fields. |
widgetId | String | Unique identifier for the In-Page widget it belongs. |
mood | Integer | Mood given by the user (0-5). |
rating | Float32 | Rating from 0.0 to 1.0. |
nps | Integer | The Net Promoter Score given by the user (0-10). |
comment | String | Comment given by the user in the feedback form. |
userAgent | String | Information about the browser user agent. |
url | String | Origin URL where the In-Page widget result was registered. |
geo | Map | Geographic location of user, consisting of city , country and region . |
Usabilla for Email
Usabilla for Email is a real-time customer feedback solution for integration with your email system. This section covers the resources that can be requested regarding the Usabilla for Email product.
Get Email Widgets
The email feedback widget is a widget usually placed in the footer of an email. Your recipients can click on the feedback widget after reading your email in order to give feedback.
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all email widgets for this account.
usabilla.email.widgets.get()
import usabilla as ub
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Get all email widgets for this account
widgets = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_EMAIL, api.RESOURCE_BUTTON)
first_widget = widgets['items'][0]
print first_widget['name']
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Gets the command.
$command = $client->getCommand('GetEmailButtons');
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"date": "2015-03-11T14:35:04.536Z",
"groups": [
{
"active": true,
"date": "2015-03-11T14:35:04.539Z",
"id": "af8c54de7067",
"name": "Joshua's email footer"
}
],
"id": "e4b5a0661176",
"introText": "We'd love your input",
"locale": "en_US",
"name": "Mail campaign"
}
Endpoint
GET /live/email/widget
This endpoint returns a list of your email widgets
Parameters
Field | Type | Description |
---|---|---|
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the widget. 12 characters long. |
date | Date | The creation date of the email widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
name | String | The name of the widget. |
introText | String | The name of the widget given when created. Can be updated in the widget setup page. |
locale | String | Regional language of the widget and form text items. |
groups | Array | List of groups this campaign item is member of. |
Get Email Feedback
After the reader leaves feedback on an email widget it becomes a feedback item that you can view in your Usabilla account.
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all email widgets for this account.
usabilla.email.widgets
.get()
.then(emailWidgets => {
// Get the feedback for a email widget with id.
let emailQuery = {
id: emailWidgets[0].id
};
// Get the feedback of the first email widget
usabilla.email.widgets.feedback
.get(emailQuery)
.then(feedback => {
console.log('# email feedback', feedback.length);
})
.catch(reason => {
console.error(reason);
});
})
.catch(reason => {
// If the usabilla call fails, we want to see the error message
console.error(reason);
});
import usabilla as ub
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Get all email widgets for this account
widgets = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_EMAIL, api.RESOURCE_BUTTON)
first_widget = widgets['items'][0]
print first_widget['name']
# Get the feedback of the first email widget
feedback = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_EMAIL, api.RESOURCE_FEEDBACK, first_widget['id'], iterate=True)
print len([item for item in feedback])
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//NonMandatoryIdParam defaults to * if not set, must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'NonMandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetEmailFeedbackItems', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "5499612ec4698839368b4573",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36",
"comment": "Thx for your email.",
"location": "Amsterdam, Netherlands",
"date": "2014-01-15T19:48:06.003Z",
"customData": {
"form_name": "form1"
},
"email": "dev@usabilla",
"labels": [
"label 1",
"label 2"
],
"nps": 10,
"rating": 5,
"widgetId": "8d73568ac2be",
"tags": [
"interesting",
"unattractive"
],
"urlParams": {
"utm_campaign": "1234576_20160101_my_campaign",
"utm_medium": "email",
"utm_source": "email_feedback_form"
}
}
Endpoint
GET /live/email/widget/:id/feedback
This request returns a list of your email widget feedback.
Parameters
Field | Type | Description |
---|---|---|
id | String | The widget id. If you wish to get all available feedback items use * (asterisk) as value. |
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the feedback item. |
userAgent | String | Information about the browser user agent. |
comment | String | Commentary left by the user in the feedback form. |
location | String | String containing geographical information about the location of the user based on the user's ip address. |
date | Date | The creation date of the email widget, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
customData | Map | Custom variables that have been assigned in the widget setup page. |
String | Optional field that the user fills in in case he wishes to be contacted. | |
labels | Map | An array of labels that have been assigned to the feedback item. |
nps | Integer | The Net Promoter Score given by the user (0-10). |
rating | Integer | Rating given by the user (0-5). |
widgetId | String | The source widget of the feedback item. |
tags | Array | An array of tags assigned to the feedback item. |
urlParams | Map | The URL parameters passed via the feedback URL. |
Usabilla for Apps
Usabilla for Apps is a real-time user feedback system for analysis of customer experience on your mobile applications. This section covers the resources that can be requested regarding the Usabilla for Apps product.
Get App Forms
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all apps forms for this account.
usabilla.apps.forms.get().then(appsForms => {
const appsForm = appsForms[0];
if (!appsForm) {
return;
}
});
import usabilla as ub
from datetime import datetime, timedelta
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Set the limit of buttons to retrieve to 1
if False:
api.set_query_parameters({'limit': 1})
# Set a limit for last 7 days
# NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
if False:
epoch = datetime(1970, 1, 1)
since = timedelta(days=7)
since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
api.set_query_parameters({'since': since_unix})
# Get all apps forms for this account
forms = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_APPS, api.RESOURCE_APP)
first_form = forms['items'][0]
print first_form['name']
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Gets the command.
$command = $client->getCommand('GetApps');
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"date": "2014-08-22T13:34:07.043Z",
"id": "53f746cfc469889e628b4568",
"name": "New untitled App Form",
"status": "active"
}
Each App has a feedback button placed somewhere in the mobile application. App users can click on the feedback button at any time in order to give feedback. The feedback form (App Form) is initialized in the mobile application by calling the Usabilla SDK with the Form ID.
Endpoint
GET /live/apps
This endpoint returns a list of your App Forms that are created in your Usabilla dashboard.
Parameters
Field | Type | Description |
---|---|---|
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the Form. 24 characters long. |
date | Date | The creation date of the Form, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
name | String | The name of the Form. |
status | String | The status the Form. |
Get App Form Feedback
/**
* argv[0] Access Key
* argv[1] Secret Key
*/
const args = require('yargs').argv._;
const Usabilla = require('../dist/api-js-node');
const usabilla = new Usabilla(args[0], args[1]);
// Get all apps forms for this account.
usabilla.apps.forms
.get()
.then(appsForms => {
const appsForm = appsForms[0];
if (!appsForm) {
return;
}
// Get the feedback for a apps form with id.
let appsQuery = {
id: appsForm.id
};
// Get the feedback of the second app form
usabilla.apps.forms.feedback
.get(appsQuery)
.then(feedback => {
console.log('# apps feedback', feedback.length);
})
.catch(reason => {
console.error(reason);
});
})
.catch(reason => {
// If the usabilla call fails, we want to see the error message
console.error(reason);
});
import usabilla as ub
from datetime import datetime, timedelta
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Set the limit of buttons to retrieve to 1
if False:
api.set_query_parameters({'limit': 1})
# Set a limit for last 7 days
# NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
if False:
epoch = datetime(1970, 1, 1)
since = timedelta(days=7)
since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
api.set_query_parameters({'since': since_unix})
# Get all apps forms for this account
forms = api.get_resource(api.SCOPE_LIVE, api.PRODUCT_APPS, api.RESOURCE_APP)
first_form = forms['items'][0]
print first_form['name']
# Get the feedback of the first app form
feedback = api.get_resource(
api.SCOPE_LIVE,
api.PRODUCT_APPS,
api.RESOURCE_FEEDBACK,
first_form['id'],
iterate=True)
print len([item for item in feedback])
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//NonMandatoryIdParam defaults to * if not set, must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'NonMandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetAppFeedbackItems', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"appId": "53f746cfc469889e628b4568",
"appName": "Usabilla Test Frame",
"appVersion": "48",
"batteryLevel": -1,
"connection": "WiFi",
"customData": {
"custom_variable": "one",
"shaken": 1,
"user_id": "786690"
},
"data": {
"name": "pablo",
"nps": 8,
"rating": 4,
"speed": 5,
"subject": "Compliment"
},
"date": "2015-04-20T08:12:13.382Z",
"deviceName": "iPhone Simulator",
"freeMemory": 224776,
"freeStorage": 131880204,
"geoLocation": {
"country": "NL",
"region": "07",
"city": "Amsterdam",
"lat": 52.35,
"lon": 4.9167
},
"id": "5534b4dcea5b09b33557bb20",
"ipAddress": "80.101.117.33",
"language": "en",
"location": "Amsterdam, Netherlands",
"orientation": "Portrait",
"osName": "ios",
"osVersion": "8.3",
"rooted": false,
"screenshot": "https://usabilla-feedback-app.s3.amazonaws.com/staging/media/55/34/5534b4dcea5b09b33557bb20/screenshot",
"screensize": "320x568",
"timestamp": "1429517532",
"totalMemory": 14032256,
"totalStorage": 243924992
}
After the user sends feedback using the feedback button it becomes a feedback item that you can view in your Usabilla dashboard.
Endpoint
GET /live/apps/:id/feedback
This endpoint returns a list of your feedback items that are connected to a specific App Form. The App Form is loaded in from the Usabilla SDK once a user clicks on the feedback button in the application.
Parameters
Field | Type | Description |
---|---|---|
id | String | The Form ID. For feedback items of all Forms use * (asterisk) as value. |
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the feedback item. |
date | Date | The creation date of the Form, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
timestamp | String | Date and time (Unix timestamp) when feedback was sent by the App. |
deviceName | String | Device name on which the app is running. |
data | Map | Map containing the Feedback data ("mood" and "nps" scores). |
customData | Map | Map containing the optionally configured custom values. |
appId | String | ID of the feedback form the feedback item belongs to. |
appName | String | Name of the feedback form |
appVersion | String | Version of the app. |
osName | String | Operating System name on which the app is running. |
osVersion | String | Operating System version on which the app is running. |
location | String | Readable location (City, Country). |
geoLocation | Map | Geographic location details ("country", "region", "city", "lat", "lon"). |
freeMemory | Integer | Bytes of RAM left unused. |
totalMemory | Integer | Bytes of RAM in total. |
freeStorage | Integer | Bytes of storage memory left unused. |
totalStorage | Integer | Bytes of storage memory in total. |
screenshot | String | Screenshot URL. |
screensize | String | Screen property size. |
connection | String | Current connections. |
ipAddress | String | Current IP address. |
language | String | Language used. |
orientation | String | The orientation of the screen at time of feedback ['Portrait','Landscape']. |
batteryLevel | Float32 | Battery level from 0.0 to 1.0 (-1 means unknown). |
Get App Campaigns
// JavaScript example under construction
import usabilla as ub
from datetime import datetime, timedelta
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Set the limit of buttons to retrieve to 1
if False:
api.set_query_parameters({'limit': 1})
# Set a limit for last 7 days
# NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
if False:
epoch = datetime(1970, 1, 1)
since = timedelta(days=7)
since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
api.set_query_parameters({'since': since_unix})
# Campaigns for apps
app_campaigns = api.get_resource(
api.SCOPE_LIVE,
api.PRODUCT_APPS,
api.RESOURCE_CAMPAIGN)
first_campaign = app_campaigns['items'][0]
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Gets the command.
$command = $client->getCommand('GetAppCampaigns');
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "a705f2be-d55c-4a5e-8b35-32a472f860f1",
"createdAt": "2018-02-27T16:56:42.555Z",
"lastModifiedAt": "2019-01-24T16:00:51.623Z",
"status": "active",
"name": "checkout confirmation page",
"appIds": [
"f9604f35-6d9a-4f1c-a5fa-33402d7a4d96"
]
}
The App Campaigns are activated within the App by sending an event to our SDK.
Endpoint
GET /live/apps/campaign
This endpoint returns a list of your Usabilla for Apps Campaigns.
Parameters
Field | Type | Description |
---|---|---|
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the campaign. |
createdAt | Date | The creation date of the campaign, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
lastModifiedAt | Date | The creation date of the campaign, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
status | String | The status of the campaign. Can be active or inactive . |
name | String | The name of the campaign. |
appIds | Array | Map containing the AppID's connected to the campaign. |
Get App Campaign Feedback
// JavaScript example under construction
import usabilla as ub
from datetime import datetime, timedelta
if __name__ == '__main__':
# Create an API client with access key and secret key
api = ub.APIClient('YOUR-ACCESS-KEY', 'YOUR-SECRET-KEY')
# Set the limit of buttons to retrieve to 1
if False:
api.set_query_parameters({'limit': 1})
# Set a limit for last 7 days
# NB: You might need to convert the since_unix calculation from scientific notation or set the since parameter manually
if False:
epoch = datetime(1970, 1, 1)
since = timedelta(days=7)
since_unix = (datetime.utcnow() - since - epoch).total_seconds() * 1000
api.set_query_parameters({'since': since_unix})
# Campaigns for apps
app_campaigns = api.get_resource(
api.SCOPE_LIVE,
api.PRODUCT_APPS,
api.RESOURCE_CAMPAIGN)
first_campaign = app_campaigns['items'][0]
responses = api.get_resource(
api.SCOPE_LIVE,
api.PRODUCT_APPS,
api.RESOURCE_CAMPAIGN_RESULT,
first_campaign['id'],
iterate=True)
print len([item for item in responses])
// Go example under construction
<?php
require 'autoload.php';
use Usabilla\API\Client\UsabillaClient;
// Creates a new Usabilla client.
$client = new UsabillaClient('ACCESS_KEY', 'SECRET_KEY');
// Specify the parameters as mentioned in the service description:
//MandatoryIdParam must be of type string
//NonMandatoryLimitParam must be of type integer
//NonMandatorySinceParam must be of type integer
$params = ['id' => 'MandatoryIdParam', 'limit' => NonMandatoryLimitParam, 'since' => NonMandatorySinceParam];
// Gets the command.
$command = $client->getCommand('GetAppCampaignResults', $params);
// Executes the command.
$response = $client->execute($command);
// Prints the received response.
print_r($response);
The data will be received in JSON format like this:
{
"id": "bd1c5b72-2c77-4de3-b65c-b314cc540af4",
"date": "2018-12-04T15:20:05.011Z",
"campaignId": "e67e8b74-ca36-4a29-8fdd-1be78e32fabb",
"appId": "15f2e909-fecc-4cee-871a-385c7bba3b54",
"data": {
"mood": 3
},
"context": null,
"metadata": {
"app_name": "Demo App",
"app_version": "1",
"battery": 1,
"device": "x86_64",
"language": "en",
"network_connection": "WiFi",
"orientation": "Portrait",
"os_version": "12.0",
"screen": "375 x 667",
"sdk_version": "5.1.4",
"system": "ios",
"timestamp": "2018-12-04T15:17:36Z"
},
"complete": false
}
After the user gives feedback through the campaign it becomes a feedback item that you can view in your Usabilla account.
Endpoint
GET /live/apps/campaign/:id/results
This endpoint returns a list of your Usabilla for Apps Campaign feedback items.
Parameters
Field | Type | Description |
---|---|---|
limit | Integer | Optional URL query parameter that limits the number of retrieved results between 1 and 100. Defaults to 100 when omitted. |
since | Timestamp | Optional UTC Timestamp (in milliseconds) URL query parameter used to retrieve items of which creation date is after the supplied value. |
Success response
Field | Type | Description |
---|---|---|
id | String | Unique identifier of the campaign feedback. |
date | Date | The date of the feedback, in UTC. The format being used is %Y-%m-%dT%H:%M:%S.%fZ as defined in ISO 8601. |
appId | String | App ID connected to the campaign feedback. |
campaignId | String | Campaign ID connected to the campaign feedback. |
data | Map | Contains all the feedback from the campaign. |
context | Map | Custom variables connected to the campaign feedback |
metadata | Map | Metadata from the device |
complete | String | Equals to true if campaign feedback is fully completed. Equals to false if the user didn't finish the campaign |
Get App Campaign Feedback schema
// JavaScript example under construction
// Python example under construction
// Go example under construction
// PHP example under construction
The data will be received in JSON format like this:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://data.usabilla.com/live/apps/campaign/50e463f7-4f44-4c96-b12c-47da71c9251d/results/schema",
"description": "Usabilla for Apps Campaign feedback item.",
"title": "Feedback",
"type": "object",
"properties": {
"appId": {
"description": "App ID connected to the campaign feedback.",
"format": "uuid",
"type": "string"
},
"campaignId": {
"description": "Campaign ID connected to the campaign feedback.",
"format": "uuid",
"type": "string"
},
"complete": {
"description": "Equals to true if campaign feedback is fully completed. Equals to false if the user didn't finish the campaign",
"type": "boolean"
},
"context": {
"description": "Custom variables connected to the campaign feedback",
"type": [
"object",
"null"
],
"properties": {
"*": {
"type": "string"
}
}
},
"data": {
"description": "Contains all the feedback from the campaign.",
"type": ["object", "null"],
"properties":
{
"nps": {
"type": [
"integer",
"null"
]
}
}
},
"date": {
"description": "The date of the feedback, in UTC.",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Unique identifier of the campaign feedback.",
"format": "uuid",
"type": "string"
},
"metadata": {
"description": "Metadata from the device",
"type": "object",
"properties": {
"app_name": {
"description": "Name of the Hosting Application",
"type": "string"
},
"app_version": {
"description": "Version of the Hosting Application",
"type": "string"
},
"battery": {
"description": "Level of battery (-1.0 ... 0 ... 1.0 )",
"maximum": 1,
"minimum": -1,
"type": "number"
},
"device": {
"description": "Name of the device app is runing on",
"type": "string"
},
"language": {
"description": "Locale of the device",
"type": "string"
},
"network_connection": {
"description": "Current networkconnection ('Cellular' | 'WiFi' | 'No Connection')",
"type": "string"
},
"orientation": {
"description": "Device orientation ('Portrait' | 'Landscape')",
"type": "string"
},
"os_version": {
"description": "Devices os version",
"type": "string"
},
"screen": {
"description": "Device Screen size",
"type": "string"
},
"sdk_version": {
"description": "Version of our SDK",
"type": "string"
},
"system": {
"description": "Operating system of device ('ios' | 'android')",
"type": "string"
},
"timestamp": {
"description": "Time of gathering above data in RFC3339 format",
"format": "date-time",
"type": "string"
}
}
}
},
"required": [
"appId",
"campaignId",
"complete",
"date",
"id"
]
}
After the user gives feedback through the campaign it becomes a feedback item that you can view in your Usabilla account.
Endpoint
GET /live/apps/campaign/:id/results/schema
This endpoint returns a JSON Schema that will describe all feedback items you can retrieve with the GET /live/apps/campaign/:id/results
endpoint.
Parameters
This endpoint has no parameters.
Success response
The response follows the JSON Schema specification which you can find here. The version we're currently using is 2020-12.