NAV
Shell

Server-Side Documentation

Welcome to the Server-Side test documentation! You can use this API to access AB Tasty endpoints, which can generate unique visitor IDs, allocate a visitor to a test, and push visit and conversion events in order to help you analyze the outcomes of your campaign.

We have language bindings in Shell in order to illustrate every endpoint and help you make good use of it! You can view code examples in the panel on the right-hand side.

Should you have any question about this documentation, feel free to reach out to us.

Link to the GRPC documentation

Authentication

Use the following code for authentication:

# Using curl, simply pass the header with each request as shown below
curl "api_endpoint_here"
  -H "x-api-key: your_api_key"

Make sure you replace your_api_key with your personal API key.

AB Tasty uses an API key to grant access to the API.

AB Tasty requires the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: your_api_key

Endpoints

Generate a unique visitor ID

curl -X POST \
  https://serverside.abtasty.com/v1/visitor \
  -H 'x-api-key: your_api_key'

The above command returns a JSON object structured as shown below:

  {
    "id": "bfr9ad2t0hm0009vj6l0",
  }

This endpoint generates a unique visitor ID.

HTTP Request

POST /v1/visitor

Arguments

Responses

Parameter Type Description
id string Unique ID of the visitor

Allocate a visitor to a variation

curl -X POST \
  https://serverside.abtasty.com/v1/allocate \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
    "visitor_id": "bfr9ad2t0hm0009vj6l0"
}'

The above command returns a JSON object structured as shown below:

{
  "allocations": {
    "355385": 462141,
    "563299": 10
  }
}

When called with the optional parameter campaign_id, the allocations object will only contain the corresponding entry, along with the deprecated variation_id :

curl -X POST \
  https://serverside.abtasty.com/v1/allocate \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
    "visitor_id": "bfr9ad2t0hm0009vj6l0",
    "campaign_id": "355385"
}'

Returns

{
    "variation_id": "462141",
    "allocations": {
        "355385": "462141"
    }
}

This endpoint allocates a visitor to a variation. It requires one parameter : the visitor_id.

HTTP Request

POST /v1/allocate

Arguments

Parameter Type Required Description
visitor_id string required> Unique identifier of the visitor
campaign_id string optional Unique identifier of the test

Responses

Parameter Type Description
allocations object A mapping of the variation the visitor is allocated to, for all existing campaigns. Represented as a set of $campaignId:$variationId. When called with the parameter campaign_id, it will contain only the corresponding entry
variation_id string deprecated The id of the variation allocated to the visitor for the specified campaign. This field is missing if there is no campaign_id input

Send Campaign Activated event

curl -X POST \
  https://serverside.abtasty.com/v1/campaign_activated_event \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
  "campaign_id": "355385",
  "variation_id": "462141",
  "tracking_data": {
      "device_type": "DESKTOP",
      "origin": "http://www.mywebsite.com/products/p-123.php",
      "visitor_id": "bfr9ad2t0hm0009vj6l0"
    }
}'

The above command returns a JSON object structured as shown below:

{}

The campaign_activated_event lets you validate the fact that a visitor has seen a campaign / variation. Once seen, the variation_id and the campaign_id must be stored for the given visitor in order to display the same variation throughout the user journey.

HTTP Request

POST /v1/campaign_activated_event

Arguments

Parameter Type Required Description
campaign_id string required Unique identifier of the test
variation_id string required Unique identifier of the variation
tracking_data object required Set of visitor tracking data retrieved when the campaign was activated
tracking_data.visitor_id string required Unique identifier of the visitor whose tracking data are retrieved.
tracking_data.device_type string required Device used by the visitor to view the test. The following devices are currently supported: "DESKTOP", "MOBILE_PHONE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER".
tracking_data.origin string required Original page where the event occurred (can be a URI or a screen name).
tracking_data.timestamp string optional Date and time when the event occurred, expressed using the iso8601 standards.
tracking_data.ip string optional IP address of the visitor’s device to determine the geolocation.

Send Action Tracking event

curl -X POST \
  https://serverside.abtasty.com/v1/action_tracking_event \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
  "name": "goal-add-to-basket",
  "type": "CLICK",
  "tracking_data": {
    "visitor_id": "bfr9ad2t0hm0009vj6l0",
    "device_type": "DESKTOP",
    "origin": "http://www.mywebsite.com/products/p-123-toto.php"
  }
}'

The above command returns a JSON object structured as shown below:

{}

The action tracking event lets you track conversion i.e. clicks or touches on your website/mobile app.

HTTP Request

POST /v1/action_tracking_event

Arguments

Parameter Type Required Description
name string required Label of the click tracking/touch as displayed in the reporting.
type string required Type of action tracking i.e. click on a webpage or touch on a mobile page. It can be either "CLICK" or "TOUCH".
tracking_data object required User data retrieved when the click tracking occurred.
tracking_data.visitor_id string required Unique identifier of the visitor.
tracking_data.device_type string required Device used by the visitor to view the test. The following devices are currently supported: "DESKTOP", "MOBILE_PHONE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER".
tracking_data.origin string required Original page where the event occurred (can be a URI or a screen name).
tracking_data.timestamp string optional Date and time when the event occurred, expressed using the iso8601 standards.
tracking_data.ip string optional IP address of the visitor’s device to determine the geolocation.
value_string string optional String value attached to the action tracking event.
value_integer int optional Integer value attached to the action tracking event.
position object optional Object that contains the position where the touch occurred on the mobile page.
position.x int required Abscissa of the touching point on the mobile device.
position.y int required Ordinate of the touching point on the mobile device.
resolution object optional Object that contains the resolution of the screen where the touch occurred.
resolution.width int required Width of the screen where the touch occurred.
resolution.height int required Height of the screen where the touch occurred.

Send Custom event

curl -X POST \
  https://serverside.abtasty.com/v1/custom_event \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
  "name": "time-before-purchase",
  "value_integer": 53000,
  "tracking_data": {
      "device_type": "DESKTOP",
      "geolocation": {
        "lat": 48.868117,
        "long": 2.3559636
      },
      "ip": "87.200.72.165",
      "origin": "http://www.mywebsite.com/products/p-123.php",
      "timestamp": "2018-02-12T17:29:02Z",
      "visitor_id": "bfr9ad2t0hm0009vj6l0"
  }
}'

The above command returns a JSON object structured as shown below:

{}

The custom_event lets you track events that are specific to your business.

HTTP Request

POST /v1/custom_event

Arguments

Parameter Type Required Description
name string required Label of the event tracked as displayed in the reporting.
tracking_data object required Set of visitor tracking data retrieved when the event tracking occurred.
tracking_data.visitor_id string required Unique identifier of the visitor.
tracking_data.device_type string required Device used by the visitor to view the test. The following devices are currently supported: "DESKTOP", "MOBILE_PHONE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER".
tracking_data.origin string required Original page where the event occurred (can be a URI or a screen name).
tracking_data.timestamp string optional Date and time when the event tracking occurred, expressed using the iso8601 standards.
tracking_data.ip string optional IP address of the visitor’s device to determine the geolocation.
value_string string optional String value attached to the action tracking event.
value_integer int optional Integer value attached to the action tracking event.

Send Transaction event

curl -X POST \
  https://serverside.abtasty.com/v1/transaction_event \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
  "name": "transaction-apparel",
  "id": "transaction-2",
  "revenue": 13099,
  "shipping": 899,
  "tracking_data": {
    "device_type": "DESKTOP",
    "geolocation": {
      "lat": 48.868117,
      "long": 2.3559636
    },
    "ip": "87.200.72.165",
    "origin": "http://www.mywebsite.com/order-confirmation.php",
    "visitor_id": "bfr9ad2t0hm0009vj6l0"
  },
  "tax_total": 239,
  "payment_method": "PayPal",
  "items_count": 2,
  "currency": {
    "name": "USD",
    "rate": "1"
  },
  "items": [{
    "name": "Black T-shirt",
    "price": 2700,
    "sku": "0240670010",
    "category": "tops",
    "quantity": 1,
    "tax_amount": 529,
    "tax-rate": 19.6
  },
  {
    "name": "Blue Jean",
    "price": 9500,
    "sku": "blu-jeans-levis-503",
    "category": "jeans",
    "quantity": 1,
    "tax_amount": 1862,
    "tax-rate": 19.6
  }]
}'

The above command returns a JSON object structured as shown below:

{}

The transaction_event lets you track any purchase on a website/mobile app.

HTTP Request

POST /v1/transaction_event

Arguments

Parameter Type Required Description
name string required Label of the transaction tracked as displayed in the reporting.
id string required Unique identifier of the transaction.
revenue int required Total amount of money spent by the visitor expressed in cents. If no value is passed, the revenue will be 0.
shipping int required Shipping cost - expressed in cents. If no value is passed, the shipping will be 0.
tracking_data object required User data retrieved when the click tracking occurred.
tracking_data.visitor_id string required Unique identifier of the visitor.
tracking_data.device_type string required Device used by the visitor to view the test. The following devices are currently supported: "DESKTOP", "MOBILE_PHONE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER".
tracking_data.origin string required Original page where the event occurred (can be a URI or a screen name).
tracking_data.timestamp string optional Date and time when the event tracking occurred, expressed using the iso8601 standards.
tracking_data.ip string optional IP address of the visitor’s device to determine the geolocation.
tax_total int optional Total tax expressed in cents.
payment_method string optional Means of payment.
item_count int optional - default number of items Total number of products purchased on the website/mobile app.
currency object optional Currency used for the payment.
currency.name string required Name of the currency used for the payment.
currency.rate float required Exchange rate between USD in cents (used as a reference) and the currency used for the payment.
items object  optional Products purchased on the website/mobile app.
items.name string required  Label of the product.
items.price int required Price of the item expressed in cents.
items.sku string optional Identifier of the item.
items.category string optional Category of product the item belongs to.
items.quantity int optional Number of identical products purchased at the same time on the website/mobile app.
items.tax_amount int optional Amount of tax applied to the item.
items.tax_rate float optional Percentage of tax applied to the item.

Send Visit event

curl -X POST \
  https://serverside.abtasty.com/v1/visit_event \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your_api_key' \
  -d '{
  "tracking_data": {
      "device_type": "DESKTOP",
      "geolocation": {
        "lat": 48.868117,
        "long": 2.3559636
      },
      "ip": "87.200.72.165",
      "origin": "http://www.mywebsite.com/products/p-123.php",
      "timestamp": "2018-02-12T17:29:02Z",
      "visitor_id": "bfr9ad2t0hm0009vj6l0"
  }
}'

The above command returns a JSON object structured as shown below:

{}

The visit_event lets you track any visit occurring on a website/mobile app page.

HTTP Request

POST /v1/visit_event

Arguments

Parameter Type Required Description
tracking_data object required User data retrieved when the click tracking occurred.
tracking_data.visitor_id string required Unique identifier of the visitor.
tracking_data.device_type string required Device used by the visitor to view the test. The following devices are currently supported: "DESKTOP", "MOBILE_PHONE", "TABLET", "CAMERA", "TV", "GAMES_CONSOLE", "PAYMENT_TERMINAL", "WRISTWATCH", and "OTHER".
tracking_data.origin string required Original page where the event occurred (can be a URI or a screen name).
tracking_data.timestamp string optional Date and time when the event tracking occurred, expressed using the iso8601 standards.
tracking_data.ip string optional IP address of the visitor’s device to determine the geolocation.

Errors

The AB Tasty API uses the following error codes:

Error Code Error Label Meaning
0 OK OK is returned on success.
1 Canceled Canceled indicates that the operation was canceled (typically by the caller).
2 Unknown Unknown error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted into this error.
3 InvalidArgument InvalidArgument indicates that the client specified an invalid argument. Note that this differs from FailedPrecondition. It indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
4 DeadlineExceeded DeadlineExceeded means that operation expired before completion. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.
5 NotFound NotFound means some requested entity (e.g., file or directory) was not found.
6 AlreadyExists AlreadyExists means an attempt to create an entity failed because one already exists.
7 PermissionDenied PermissionDenied indicates that the caller does not have permission to execute the specified operation. It must not be used for rejections caused by exhausting some resource (use ResourceExhausted instead for those errors). It must not be used if the caller cannot be identified (use Unauthenticated instead for those errors).
8 RessourceExhausted ResourceExhausted indicates that some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
9 FailedPrecondition FailedPrecondition indicates that an operation was rejected because the system is not in a state required for the operation’s execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc. A litmus test that may help a service implementor in deciding between FailedPrecondition, Aborted, and Unavailable: (a) Use Unavailable if the client can retry just the failing call. (b) Use Aborted if the client should retry at a higher-level (e.g., restarting a read-modify-write sequence). © Use FailedPrecondition if the client should not retry until the system state has been explicitly fixed. E.g., if an “rmdir” fails because the directory is non-empty, FailedPrecondition should be returned since the client should not retry unless they have first fixed up the directory by deleting files from it. (d) Use FailedPrecondition if the client performs conditional REST Get/Update/Delete on a resource and the resource on the server does not match the condition. E.g., conflicting read-modify-write on the same resource.
10 Aborted We’re temporarily offline for maintenance. Please try again later.
11 OutOfRange OutOfRange means an operation was attempted past the valid range. E.g., seeking or reading past end of file. Unlike InvalidArgument, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate InvalidArgument if asked to read at an offset that is not within the range [0,2^32-1], but it will generate OutOfRange if asked to read from an offset past the current file size. There is a fair bit of overlap between FailedPrecondition and OutOfRange. We recommend using OutOfRange (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OutOfRange error to detect when they are done.
12 Unimplemented Unimplemented indicates an operation that is not implemented or not supported/enabled in this service.
13   Internal  Internal errors. Means some invariant expected by underlying system has been broken. If you see one of these errors, something is very broken.
14   Unavailable  Unavailable indicates the service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. See litmus test above for deciding between FailedPrecondition, Aborted, and Unavailable.
15  DataLoss DataLoss indicates unrecoverable data loss or corruption.
16  Unauthenticated Unauthenticated indicates that the request does not have valid authentication credentials for the operation.

Changelog

16 July, 2018

{
//Example of how to use response.allocations instead
// of response.variation_id

const campaignId = 123;
//Old way
const variationId = response.variation_id;
//New way
const variationId = response.allocations[campaignId];
}

We changed the signature of the POST /v1/allocate endpoint. This is a non breaking change: