etracker
Analytics Editions / Pricing Live-Demo
etracker
Optimiser Editions / Pricing Live-Demo
Pricing For Agencies Support

Developer APIs

  1. REST Report API v3
  2. Targeting API
  3. Remarketing Feed
  4. External Generation of Test Accounts
  5. Single Sign-On (SSO)
  6. Testing API
  7. Management of authorisation profiles and sub-users

a REST Report API v3

  1. Purpose of the etracker REST Report API
  2. Access to the etracker REST Report API
  3. Using the etracker REST Report API
    1. Structure of the URL for the REST Calls
    2. Return Values
  4. Authentication
  5. Calling the Available Reports
  6. Calling Report and Metadata as well as Request Parameters
    1. Defining etracker Reports
    2. Querying Report Information
    3. Calling Report Data
    4. Calling Query-specific Report Metadata
  7. Basic Parameters of the Report API
  8. Restricting Attributes and Key Figures
  9. Dimension Filter
  10. Using Views
  11. Error Messages
  12. Code Examples
    1. Command Line Tool curl
    2. PHP
    3. Java

1 Purpose of the etracker REST Report API

The etracker REST Report API v3 is an interface you can use to develop your own applications using the etracker data or to further process this data at your company.

2 Access to the etracker REST Report API

In order to be able to use the etracker REST Report API, you need to register with etracker. Save a valid email address with our Support in order to receive a so-called developer token. Using your email address and the developer token, you will then be authorised to access etracker data using the etracker REST Report API.

Note:
In order to protect your privacy and prevent unauthorised use of the etracker Web Services API, you should keep the developer token confidential.

Using your valid email address, you can be kept informed about further developments and changes to the etracker REST Report API in realtime. When registering, you can indicate if you would like to receive regular information on the etracker API or not.

The email address and the developer token are to be supplied in each Web Service Request within the query header.

Note:
If you have the etracker Analytics Enterprise Edition, you can use the REST Report API for free. In all other cases, you can book the REST Report API for an extra charge. We are happy to provide you with prices on request. If necessary, contact your etracker consultant or Support.

3 Using the etracker REST Report API

To simplify using the etracker REST Report API, you should create a REST client. The structure of the client depends on the programming language used. The client sends the queries to the service and returns defined values which can then be further processed.

Apart from the development environment for the programming language used, you will not need any additional software or installation on your system.

3.1 Structure of the URL for the REST Calls

The etracker REST API only accepts calls via https. All of the calls described in this document are GET queries. The address of the etracker REST Server is ws.etracker.com and the basic URI for all queries is /api/rest/v3.

The REST calls can be written with or without parameters. REST calls for calling report data without parameters are not recommended as under certain circumstances very large data quantities are returned. The parameters do not differentiate between upper and lower case.

Example with parameters for calling data from the report ‘Device’:

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?limit=401

The same example without parameters (not recommended):

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data

3.2 Return Values

The format of the return values of etracker REST API queries is either JSON or CSV. CSV is only supported when querying report data and only returns when the format is queried explicitly. With the JSON returns, one JSON array or JSON object always comes back even if just one value is returned.

The etracker REST Report API works with the coding UTF-8. All data which the API provides or receives must be coded in UTF-8. Special characters like German umlauts are partially returned in the form of Javascript Escape sequences. An “ä” character, for example, would be “\u00e4” in the return data. Most JSON parsers automatically convert these kinds of Escape sequences into letters.

4 Authentication

Each REST Report query must have a header. This is for performing the authentication to the API.

The following header information is mandatory.

  • email: This header element includes the email address of the developer who has access to the API.
  • developerToken: This header element includes the developer token which you can request from the etracker Support.
  • accountId: This element includes the etracker account ID. For authentication purposes, an etracker sub-user can also be entered (format: #accountId#-#subuserId#)
  • password: This element includes the password of the etracker account.

Example:

X-ET-email=qa@etracker.com X-ET-developerToken=ab7891ca89d9b4d10dc1703a7f0214256babe6c9 X-ET-accountId=18854 X-ET-password=demo

In Firefox you can also use modify headers (https://addons.mozilla.org/en-us/firefox/addon/modify-headers/) to send on these headers.

5 Calling the Available Reports

https://ws.etracker.com/api/rest/v3/report

With this call, you can receive a list of all reports (including your own) which are available through the interface. The return is a JSON object consisting of key value pairs in which the key report IDs and the values are report names:

{  "EAPage":"Pages",  "CCOverview":"Overview",  "72":"My individual Report",  }

Report data can be called with the numerical or alphabetical report IDs.

6 Calling Report and Metadata as well as Request Parameters

The queries of the etracker report REST API are structured as follows:

https://ws.etracker.com/api/rest/v3/report/#ReportID#/#Service#

The available services are:

ServiceDescription
infoProvides general information and report metadata
metaDataProvides information on types and names of the columns of a specific report query
dataReturns the data of the corresponding report in JSON format
data.csvReturns the data of the corresponding report in CSV format

6.1 Defining etracker Reports

The etracker reports can be understood as dynamic tables or as so-called data cubes. They consist of Attributes and Key Figures. In the literature, the terms Dimensions (for attributes) and Measurements (for key figures) are used.

Attributes contain nominal or categorical values which are not numbers and show the characteristics of user interactions. Typical attribute values are names (e.g. ‘Homepage’ or ‘Womenswear’), categories (e.g. ‘customer’, ‘not customer’) or times (e.g. ‘2016-01-25’ or ‘9 AM’). Some attribute values have a natural order (e.g. the times), but most cannot be sorted sensibly or just alphabetically.

If one value should be selected from three attributes, then we talk of an attribute value combination or characteristic. If, for example, the attributes ‘Page name’, ‘Country’ and ‘Operating System’ are given, then the values ‘Homepage’, ‘Germany’ and ‘Windows’ would be an attribute value combination and ‘Homepage’, ‘Austria’, ‘Windows’ would be another attribute value combination.

Key figures contain numerical values which can be sorted and aggregated. Key figures are always returned from the REST API in aggregated form. The aggregation method depends on the key figure. The key figure ‘Bounce Rate’ is used for averaging. The key figure ‘Visitors’ however, is used for summing.

Each query of a report via the REST API returns a table which returns a specific aggregated view. Each key figure is aggregated for each existing attribute value combination. Each line in the table then consists of one attribute value combination followed by the aggregated key figures which belong to it. Two lines of such a table could look like this:

Attributes  Key data 
Page nameCountryOperating systemVisitorsBounce-Rate
HomepageGermanyWindows52330,45%
HomepageAustriaWindows5735,09%

The attribute value combination and key figures of the second line can be interpreted as follows: There were 57 visitors to the homepage from Austria using the Windows operating system and 35.09% of them viewed just one page.

6.2 Querying Report Information

Calling the information and metadata of the report ‘Device’ is done with the following query:

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/info

The return is a JSON array with one element and has the following structure:

{  "report": {  "createDate": "2016-01-01 00:00:00",  "dimensions": "1",  "segments": "0",  "visualizationType": "",  }, "attributes": [  {  "id": "device_type",  "label": "Ger\u00e4tetyp",  "type": "attribute",  "sortable": true  },   ], "key-figures": [  {  "id": "unique_visits",  "label": "Visits",  "type": "integer",  "sortable": true  },   ]  "views": [  {  "view_id": "24",  "name": "Test Configuration",  "tm": "1477324586",  "access": "this_user",  "is_default": false  },  }

The return object contains four sub-elements:

  1. A report object with general information, like the date, where a report was generated.
  2. An attribute array with metadata on each attribute in the report.
  3. A key figures array with metadata on each key figure in the report.
  4. A views array with metadata on each of the views of the report defined by the users.

The arrays for the attributes and key figures contain objects with the following data for each attribute and each key figure:

  1. The id for the communication with the REST API.
  2. A name legible for people (label). The language of the names depends on the account ID or sub-user ID used in the header and can be modified using the corresponding settings in the etracker application.
  3. The data type (type) of the values in the column.
  4. A Boolean value (‘true’ or ‘false’), which indicates if the report can be sorted by attribute or by key figure.

The data types which can be found in etracker reports are described in the following table. The sample data is data as it is returned from the REST API.

Data typeDescriptionExample
attributeAttributes contain chains of characters"organic"
attributeDateA date as character chain"2016-01-15"
integerWhole number132
floatFloating-point number2.316757394
currencyFloating-point number with two decimal points50321.45
percentPercentage rate: Floating-point number between 0 and 10034.501120345
relPercentageRelative percentage rate: Floating-point number between 0 and 10.573944096
staytimeDuration in seconds: The positions after the decimal point are fractions of seconds239.355444
dateA date2016-01-15
nullIDs and status information which are neither attributes nor key figures.

Views can be defined and saved by each user for each report interactively in the etracker application. The views array contains the following data on each view defined by the users.

  1. The view_id for the communication with the REST API.
  2. The unique name provided by the users (name).
  3. Other metadata for the view (e.g. date of creation).

6.3 Calling Report Data

Calling the data of the ‘Device’ report is done using the following query (a data query without parameters is possible, but not recommended):

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?limit=10

This query returns data in JSON format. For CSV data, ‘data.csv’ instead of ‘data’ at the end of the URI is all that is needed. For the return format, however, CSV and JSON queries are identical. For this reason, we will only describe the JSON case in this section.

The return data have approximately the following format:

[     [         "-,-,-,-,-,-,-,-,-,-",         "=S",         "",         …         "",         104377,         …         4.58239668     ],     [         "373563,1417345,1426710,1426574,1426574,1430935,1373563,1373563,0,3",         "=0",         "Desktop",         …         "no customer",         34201         …         2.3541867     ],     ... ]

The return is a JSON array of maximum 11 arrays as the parameter limit was set as equal to 10. Each array represents a data record or a line in the return table. The first array is always the ‘Total’ line, in which the key figures were aggregated across all attribute value combinations. The other arrays are attribute value combinations with the corresponding aggregated key figures. Since no sorting information was provided in the parameters, the order of the lines does not matter. Each line begins with a list of IDs of the attribute values which were used for the attribute value combination. Each attribute value has an ID which needs to be used if a specific attribute value is to be referenced via the REST API. The attribute value IDs for the same attribute values can vary from one etracker account to the next. Inside an account however they are always unique.

The second element in each line is a designation: ‘=S’ for the line, ‘Total’ and ‘=0’ for all other lines. The attribute values of the attribute combination follow in the same order as in the report information and then the key figure data of the key figures also follows in the same order as in the report information.

The above example is simply for introductory purposes and does not represent sensible use of the etracker REST API. To use the REST API in a sensible way, the desired data range and the order needs to be narrowed down using parameters.

6.4 Calling Query-specific Report Metadata

For each data query of a report, the corresponding query-specific metadata can be called. To see the metadata of the above query, ‘data’ just needs to be replaced with ‘metaData’. Here, the parameters should be kept intact.

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/metaData?limit=10

This query returns a JSON array with one entry per column in the respective data query. The first two entries have the IDs ‘id’ and ‘tree_status’ and the type ‘null’. They correspond to the first two columns described above, which are neither attributes nor key figures.

[  {  "id": "id",  "label": zero,  "type": zero,  "sortable": true  },  {  "id": "tree_status",  "label": zero,  "type": zero,  "sortable": true  },  {  "id": "device_type",  "label": "Ger\u00e4tetyp",  "type": "attribute",  "sortable": false  },  ... ]

7 Basic Parameters of the Report API

The following section describes the basic parameters of the Report API. Examples explaining the parameters then follow.

ParameterLimit
BeschreibungGibt die maximale Anzahl an Datensätzen an. die zzgl. der Summenzeile zurückgegeben werden sollen
Zulässige WerteGanze Zahlen
Beispiele10, 100 oder 5000

 

ParameterOffset
BeschreibungGibt des Startpunkt bzw. den Datensatz unmittelbar vor dem ersten Rückgabedatensatz der Abfrage an
Zuläsige Werteganze Zahlen
Beispiele0, 10 oder 100

 

ParameterstartDate
BeschreibungNur Daten, die ab 00:00 Uhr am angegebenen Datum erfasst wurden, sollen für die Abfrage berücksichtigt werden
Zulässige WerteGültige Datumsangaben der Form JJJJ-MM-TT
Beispiele2016-01-23 oder 2012-10-31

 

ParameterendDate
BeschreibungNur Daten bis 23:59 Uhr am angegebenen Datum sollen erfasst und für die Abfrage berücksichtigt werden
Zulässige WerteGültige Datumsangaben der Form JJJJ-MM-TT
Beispiele2016-01-30 oder 2014-12-17

 

ParametersortColumn
BeschreibungDie dAten sollen vor der Rückgabe nach den Werten der angegebenen Spalte sortiert werden
Zulässige WerteGültige Ids von sortierbaren Spalten. Die Ids und die Sortierbarkeit sind in den Metadaten eines Reports zu finden
Beispieleunique visits oder pi per visit

 

ParametersortOrder
BeschreibungGibt die Richtung der Sortierung an (auf- oder absteigend)
Zulässige Werte1 für absteigend, 2 für aufsteigend

The following query uses the above parameters in order to proceed in a more targeted way when querying the ‘Devices’ report.

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?startDate=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=0&limit=10

The parameters were set as follows:

  • startDate = 2016-01-01
  • endDate = 2016-01-31
  • sortColumn = unique_visits (Besuche)
  • sortOrder = 1 (absteigend)
  • offset = 0
  • limit = 10

This sorts the data recorded in January 2016 in descending order according to the ‘Visits’ key figure column and returns the first 10 lines together with the ‘Total’ line. In case additional data is desired, offset and limit can be increased progressively until no more data is returned. The next 10 data records for example were queried as follows:

https://ws.etracker.com/api/rest/v3/report/32005/data?startDate=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=10&limit=10

8 Restricting Attributes and Key Figures

Along with the basic parameters, the etracker REST API also provides additional parameters in order to more precisely specify the return table. Using the basic parameters, attribute value combinations will always be made up of values from all available attributes. Usually, only combinations from one section of the existing attributes are of interest. Furthermore, not all key figures are required for certain analyses.

It is also possible to fix or ignore certain attribute values with the help of the attribute IDs. Then only those attribute value combinations will be returned which contain the fixed attribute values or which do not contain the ignored attribute values.

Use the following two parameters to limit the attributes and key figures.

ParameterAttributes
DescriptionAttribute value combinations will only be formed from the entered attributes. The values in the return lines appear in the order given.

If value filters are given, only those attribute value combinations will be formed which either contain the fixed values or do not contain the ignored values.
Allowed valuesIn the simplest of cases, a comma-separated list of attribute IDs. The IDs can be found in the metadata of the report.

A semicolon-separated list of attribute value IDs can be entered in brackets behind each attribute ID. The attribute value ID can be found in the first entry in the table lines.

A minus symbol can be prefixed to each attribute value ID so as to ignore all attribute value IDs in the list.
ExamplesSimple case:
'device_type,geo_country,geo_region'

Attribute values are fixed for device_type:
'device_type(3257;2269),geo_country,geo_region'

Attribute values are fixed for device_type and geo_country ignored:
'device_type(3257;2269),geo_country(-10;-324),geo_region'
ParameterFigures
DescriptionOnly the key figures entered will be calculated and returned. The values in the return lines appear in the order given.
Allowed valuesComma-separated list of key figure IDs. The IDs can be found in the metadata of the report. In case a key figure was entered for sorting purposes (see sortColumn), then the key figure must be contained in the list.
Example'unique_visitors,page_impressions,pi_per_visit'

The following query clarifies the use of the ‘attributes’ parameter.

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?startDate=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=0& limit=10&attributes=device_type(137),geo_country,geo_region

The parameters were set as follows:

  • startDate = 2016-01-01
  • endDate = 2016-01-31
  • sortColumn = unique_visits (Besuche)
  • sortOrder = 1 (absteigend)
  • offset = 0
  • limit = 10
  • attributes=device_type(137),geo_country,geo_region

The attribute value ‘Desktop’ has the ID 137. The query only returns the attribute value combinations of the attributes Device Type, Country and Region for which the device type was ‘Desktop’. Only data from January 2016 will be considered and the lines will be sorted by ‘Visits’ before being returned. Only the first 10 lines (and the ‘Total’ line) will be returned.

The attribute value ‘Germany’ has the ID 1086 and the attribute value ‘Austria’ has the ID 1092. In order to ignore these two attribute values, the query can be modified as follows:

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?startDate=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=0&limit=10&attributes=device_type(137),geo_country(-1086;-1092),geo_region

This will only form attribute value combinations which contain ‘Desktop’ and which do not contain ‘Germany’ or ‘Austria’. All other specifications remain the same.

To date, all key figures were issued. In the following query, they are limited:

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?startDate=2016-01-01&endDate=2016-01-31&sortColumn=unique_visits&sortOrder=1&offset=0&limit=10&attributes=device_type(137),geo_country(-1086;-1092),geo_region&figures=unique_visits,page_impressions,pi_per_visit

The ‘figures’ parameter was added:

  • figures=unique_visits,page_impressions,pi_per_visit

This only calculates the values of the three named key figures and issues them in the order given. Since the ‘unique_visits’ key figure was used for sorting, it needs to be contained in the list.

Note:
A maximum of 20 segments can be set per query.

9 Dimension Filter

In etracker Analytics, the data records of a report can be filtered based on the desired value within an activated dimension. The parameter attributeFilter, which can only be applied to segments and dimensions, allows the data of a report to be called filtered using the REST API. The structure is as follows:

ParameterattributeFilter
DescriptionIncludes the filter characteristics in the form of a JSON array.
JSON array structure[
{
"input":"SUCHBEGRIFF",
"type":"contains",
"attributeId":"ATTRIBUT_ID",
"filterType":"simple"
}
]
JSON array description• input: Contains the substring which needs to be included in the dimension or segment.
• attributId: Dimension or segment which should be filtered.
• type and filterType do not need to be adapted
Permitted charactersThe following characters are permitted for input:
• Additional letters from all languages which are included in unicode
• all numbers: 0 - 9
• special characters: § % $ ( ) = ? € @ , . ! & + - ^ ° _ | [ ] / * { } : \
• space
Note:
Correct usage requires URL encoding of the JSON array.
URL-encoded example:
%5B%7B%22input%22%3A%22KEYWORD%22%2C%22type%22%3A%22contains%22%2C%22attributeId%22%3A%22ATTRIBUT_ID%22%2C%22filterType%22%3A%22simple%22%7D%5D

The following example demonstrates the use of the parameter in a query:

https://ws.etracker.com/api/rest/v3/report/EAPage/data?startDate=2016-11-29&endDate=2016-12-06&displayType=grouped&twig=fold%3A&attributes=page_name&sortColumn=unique_visits&sortOrder=1&attributeFilter=%5B%7B%22input%22%3A%22homepage%22%2C%22type%22%3A%22contains%22%2C%22attributeId%22%3A%22page_name%22%2C%22filterType%22%3A%22simple%22%7D%5D

If multiple dimensions or segments inside a display are to be filtered, the additional entries are to be added to the JSON array accordingly.

[ { "input":"KEYWORD", "type":"contains", "attributeId":"ATTRIBUT_ID", "filterType":"simple" }, { "input":"KEYWORD", "type":"contains", "attributeId":"ATTRIBUT_ID", "filterType":"simple" }, { "input":"KEYWORD", "type":"contains", "attributeId":"ATTRIBUT_ID", "filterType":"simple" } ]

10 Using Views

In the etracker application, it is possible to define and save views of certain reports interactively. The data for these views can also be called using the REST API. In the following query, the data for the view with ID ‘4’ will be called in the ‘Devices’ report:

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?viewid=4

ParameterViewid
DescriptionOnly that data which belongs to the specified preset view will be returned
Allowed valuesValid view IDs. The views for a report appear in the report information which can be called using the query/info.
Example4 or 32

The parameter ‘viewid’ can also be combined with all of the other parameters in order to narrow down what is returned.

11 Error Messages

With incorrect queries, data will not be returned. Instead detailed error messages will be returned. The error messages always have the same format:

{     "errorCode":170,     "msg":"Webservice authentication failed [code:170]" }

The return is a JSON object with two properties:

  • An error number (‘errorCode’), which can be used for possible enquiries for etracker and
  • a message (‘msg’), which contains information on the cause of the error.

In certain cases, no error messages are returned. Instead, an empty JSON array is returned. This happens mostly when the transferred parameter values cause problems. In these cases, it is helpful to check the following error sources first:

  • Are all of the attribute or key figure IDs written correctly?
  • Is the attribute ID for the sortColumn written correctly?
  • Is the value of sortOrder ‘1’ or ‘2’?

12 Code Examples

In the following code examples, the ‘Pages’ report with ID ‘EAPage’ is queried. The following parameters are used for the query:

  • startDate = 2016-04-01
  • endDate = 2016-04-30
  • sortColumn = page_impressions
  • sortOrder = 1
  • offset = 100
  • limit = 100
  • attributes = page_name,geo_country,browser_language
  • figures = page_impressions,bounces_per_visit

The following (invalid) data will be used for the authentication. These values would need to be replaced by valid ones so that the examples also work.

  • Email: wrong@etracker.com
  • Developer-Token: 1234567890token
  • Account-Id: 012345
  • Password: easy123

12.1 Kommandozeilen-Tool curl

curl -G \
   --header "X-ET-email: wrong@etracker.com" \
   --header "X-ET-developerToken: 1234567890token" \
   --header "X-ET-accountId: 012345" \
   --header "X-ET-password: easy123" \
   "https://ws.etracker.com/api/rest/v3/report/EAPage/data" \
   -d startDate=2016-04-01 \
   -d endDate=2016-04-30 \
   -d sortColumn=page_impressions \
   -d sortOrder=1 \
   -d offset=100 \
   -d limit=100 \
   -d attributes=page_name,geo_country,browser_language \
   -d figures=page_impressions,bounces_per_visit

The parameter ‘-G’ forces a GET query. Here, ‘-d’ can be used for entering URL parameters.

12.2 PHP

<?php $opts = array(   'http'=>array(     'method' => "GET",     'header' =>        "X-ET-email: wrong@etracker.com\r\n" .       "X-ET-developerToken: 1234567890token\r\n".        "X-ET-accountId: 012345\r\n".        "X-ET-password: easy123\r\n"   ) );    $context = stream_context_create($opts); $uri = 'https://ws.etracker.com/api/rest/v3/report/EAPage/data $parameters =     'startDate=2016-04-01&' .     'endDate=2016-04-30&' .     'sortColumn=page_impressions&' .     'sortOrder=1&' .     'offset=100&' .     'limit=100&' .     'attributes=page_name,geo_country,browser_language&' .     'figures=page_impressions,bounces_per_visit'; $file = file_get_contents(     $uri . '?' . $parameters,      false,      $context ); print_r($file); ?>

12.3 Java

import com.fasterxml.jackson.core.JsonFactory; import com.fasterxml.jackson.core.JsonParser; import java.io.IOException; import java.io.InputStream; import java.net.URL; import java.net.URLConnection; public class Example {     public static void main(String args[])     {         String url = "https://ws.etracker.com/ws/api/rest/v3/report/EAPage/data";         String query = "";         query += "startDate=2016-04-01&";         query += "endDate=2016-04-30&";         query += "sortColumn=page_impressions&";         query += "sortOrder=1&";         query += "limit=100&";         query += "offset=100&";         query += "attributes=page_name,geo_country,browser_language&";         query += "figures=page_impressions,bounces_per_visit";         try         {             URL urlObject = new URL(url + "?" + query);             URLConnection connection = urlObject.openConnection();             connection.addRequestProperty("X-ET-email", "falsch@etracker.com");             connection.addRequestProperty("X-ET-developerToken", "1234567890token");             connection.addRequestProperty("X-ET-accountId", "012345");             connection.addRequestProperty("X-ET-password", "einfach123");             InputStream inputStream = connection.getInputStream();             JsonFactory jsonFactory = new JsonFactory();             JsonParser jsonParser = jsonFactory.createParser(inputStream);             while(!jsonParser.isClosed())             {                 jsonParser.nextToken();                 System.out.println(jsonParser.getValueAsString());             }         }         catch (IOException e)         {             e.printStackTrace();         }     } }

b Targeting API

      1. Function and Purpose of the Targeting API
      2. Access to the Targeting API
      3. Response
        1. Response Structure
        2. Response Attributes
      4. Error Messages
      5. Display of Smart Messages with the Targeting API

1 Function and Purpose of the Targeting API

The Targeting API is used for personalising websites in realtime. Personalisation happens from the moment the visitor arrives at the website.

The Targeting API is a REST Service which can be integrated into the Content Management System or Shop Systems.

With the help of the transferred data, website content can be generated dynamically or exchanged depending on the interest of the customers. In this way, the etracker Targeting API does not just help to improve the user experience, but also to increase the conversion rate and turnover.

2 Access to the Targeting API (TAPI)

The following requirements need to be satisfied in order to be able to use the etracker Targeting API:

      • Desired targeting data must be recorded by etracker and transferred via events (using eCommerce API) or order parameters when calling the page.
        Orders, product performance events (‘Product viewed’, ‘Product placed in basket’ and/or ‘Product ordered’).
      • The desired targeting data (attributes) are configured by etracker.

In order to call the interface, send a request to the URI of the Targeting API. You can call the interface in the frontend using JavaScript or in the backend via HTTPS. One query is enough per session (at the start of the session).

      • The request for the interface must contain two parameters:
        et
        transfers the account key 2 which you can find in the etracker application under Settings > Setup/Tracking Code. Account Key 2 is Base64-encoded.
      • _et_coid
        transfers the first-party cookie from the domain of the etracker customer.
Note:
You can also determine the _et_coid using JavaScript.
For testing purposes you can use the cookie ID _et_coid using Firebug from the website.
https://ws.etracker.com/api/rest/v2/realtime/user?et=<account-key>&_et_coid=<CookieId>

Example:

https://ws.etracker.com/api/rest/v2/realtime/user?et=YM9dM9&_et_coid=6bbece51587a6f7aac4989953149ca47

3 Response

Note:
When a visitor visits a website for the first time, for technical reasons it can take up to half an hour until the Targeting API provides a new user profile.

3.1 Response Structure

he interface provides user profile data in its response. The response is provided in JSON format and in table form with n columns for the attribute name (header) and n lines for the attribute values (data). The number of lines depends on the size of the user profile.

The JSON response structure looks as follows:

{ “status”: “success”,”,”version“:2, “header”: [ ... ], “data”: [ ... ] }

Example with standard attributes:

{ “status”:“success”,“version”:2, “header”:[ “avg_order_value_seg”, “customer_type”, “device_type”, “device_type_detail”, “frequency_seg”, “is_newsletter_recipient”, “purchaser_type”, “time_since_last_order_seg”, “visit_count_seg”, “visitor_type” ], “data”:[ “STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_01”, “STC_CC_ATTR_VALUE_CUSTOMER_TYPE_2”, “STR_CC_ATTR_VALUE_DEVICE_TYPE_DESKTOP”, “STR_CC_ATTR_VALUE_DEVICE_TYPE_DESKTOP”, “STC_CC_ATTR_VALUE_FREQUENCY_SEG_02”, “STC_CC_ATTR_VALUE_NEWSLETTER_2”, “STC_CC_ATTR_VALUE_PURCHASER_TYPE_1”, “STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_01”, “STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_04”, “STC_CC_ATTR_VALUE_VISITOR_TYPE_1” ] }

3.2 Response Attributes

The user profile data is provided via the configured attributes. etracker configures the attributes when purchasing the product according to the needs of the customer. At the moment, a maximum of ten attributes are permitted.

Note:
There are currently ten standard attributes which are also evaluated in the Testing & Targeting Reports.

etracker provides the following attributes:

3.2.1 General Attributes

AttributeFrequency of visits
Attribute namevisit_count_seg
DescriptionStandard attribute with categories for the number of previous visits.
Data typeString
Attribute values (example)″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_01″
(just one visit) (default value)
″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_02″
(low = 2 visits)
″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_03″
(medium = 3-4 visits)
″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_04″
(high = 5 and more visits)

In order to evaluate the following attributes, the UserAgent needs to be transferred to the TAPI by the client request using the http header ‘User-Agent’.

Example transfer of client user agent
User Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0

AttributeBrowser
Attribute namedevice_browser
DescriptionName of the browser from which the visitor in the current session accessed the website.
Data typeString
Attribute values (example)″Firefox″

 

AttributeBrowser version
Attribute namedevice_browser_version
DescriptionVersion of the browser from which the visitor in the current session accessed the website.
Data typeString
Attribute values (example)″37″

 

Attributemanufacturer
Attribute namedevice_manufacturer
DescriptionManufacturer of the device which accessed the website in the current session.
Data typeString
Attribute values (example)″Apple″

 

AttributeDevice name
Attribute namedevice_model
DescriptionName of the device which accessed the website in the current session. Is only issued for mobile devices.
Data typeString
Attribute values (example)″iPad″

 

AttributeOperating system
Attribute namedevice_os
DescriptionOperating system which accessed the website in the current session.
Data typeString
Attribute values (example)″Windows″

 

AttributeOperating system version
Attribute namedevice_os_version
DescriptionVersion of the operating system which accessed the website in the current session.
Data typeString
Attribute values (example)″7″

 

AttributeDevice type
Attribute namedevice_type
DescriptionStandard attribute describing the type of the device which accessed the website in the current session.
Data typeString
Attribute values″STR_CC_ATTR_VALUE_DEVICE_TYPE_DESKTOP″
(value for device_type = Desktop)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_MOBILE_PHONE″
(value for device_type = Mobile)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_TABLET″
(value for device_type = Tablet)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_OTHERS″
(value for device_type = Other)

 

AttributeDevice type (Detail)
Attribute namedevice_type_detail
DescriptionStandard attribute which describes the device type in greater detail if possible.
Data typeString
Attribute values″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_GAME_CONSOLE″
(value for device_type_detail = Game_Console)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_NON_SMARTPHONE″
(value for device_type_detail = Non-Smartphone)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_SMARTTV″
(value for device_type_detail = SmartTV)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_SMARTPHONE″
(value for device_type_detail = Smartphone)

3.2.2 Geo Attributes

The Targeting API (TAPI) offers the option to use the location of website visitor without the localisation API of the browser. Tracing back to the Internet provider is possible using a GeoIP resolver service. The TAPI provides information on the location of the visitor in regard to country, state and city.

In order to evaluate the following attributes, the Client IP needs to be transferred to the TAPI by the client request using the http header ‘X-Forwarded-For’.

Example transfer of Client IP
X-Forwarded-For: 31.19.38.145

AttributeCountry
Attribute namegeolocation_country
DescriptionCountry from which the visitor in the current session accessed the website.
Data typeString
Attribute values (example)Germany

 

AttributeRegion
Attribute namegeolocation_state
DescriptionRegion from which the visitor in the current session accessed the website.
Data typeString
Attribute values (example)Hamburg

 

AttributeCity
Attribute namegeolocation_city
DescriptionCity from which the visitor in the current session accessed the website.
Data typeString
Attribute values (example)Hamburg

3.2.3 eCommerce Attributes

Note:
In order to be able to use the eCommerce attributes, extended data collection must be integrated into the website to be measured. Only this way can events like, for example, ‘Product viewed’, ‘Product placed into basket’ or ‘Product ordered’ be transferred to etracker via the eCommerce API.

Profile information

AttributeCustomer ID
Attribute namecustomer_id
DescriptionCustomer number, unique ID of a customer
Data typeString
Attribute values (example)″345565″

 

AttributeCustomer group
Attribute namecustomer_group
DescriptionGroup to which a customer belongs, according to eCommerce API
Data typeString
Attribute values (example)″Regular customer″

 

AttributePurchaser type
Attribute namepurchaser_type
DescriptionStandard attribute for categorising the purchaser according to the ABC analysis
Data typeString
Attribute values″STC_CC_ATTR_VALUE_PURCHASER_TYPE_1″
(no purchase) (default value)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_2″
(just one purchase)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_3″
(C = unimportant customer)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_4″
(B = important customer)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_5″
(A = very important customer)

 

AttributeScore Value
Attribute namescore_values
DescriptionScore is a whole number which describes the relevance of the interest in a product. Transfer is done via an optional property ‘score’ in the product object of the eCommerce API.
Example:
You wish to present an offer to visitors who have already shown interest in a certain product. The offer should only be presented to those customers who have already shown interest to a specific degree in this product or product area. Interest can be illustrated by score values which are given on the visited product pages or product area pages. A visitor deemed to be interested in a product is someone who tallies up a score for a product over a certain period (e.g. in the last four weeks).
Data typeArray with objects.
Inside the objects there is the data type ‘String’
(JSON Property ‘‘product_name’’)
and the data type ‘Number’
(JSON Properties ‘accumulated_value_last_7_days’, ‘accumulated_value_last_4_weeks’, ‘accumulated_value_last’ and ‘number_of_values’)
Attribute values[
{
“White chocolate”: {
“values”: [{
“accumulated_value”: 1000
}, {
“accumulated_value_last_7_days”: 100
}, {
“accumulated_value_last_4_weeks”: 900
}, {
“accumulated_value_last”: 100
}],
“number_of_values”: 3
}
},
...
}
]

Order information

AttributeFirst Lead
Attribute namelead_first_tm
DescriptionTime of the first order (lead)
Data type/MemberMillisecond timestamp detailing when the lead occurred
Attribute values (example)″1400592736149400″

 

AttributeFirst Sale
Attribute namesale_first_tm
DescriptionTime of the first purchase (sale)
Data type/MemberMillisecond timestamp detailing when the sale occurred
Attribute values (example)″1400592736149400″

 

AttributeLast Lead
Attribute namelead_last_tm
DescriptionTime of the last order (lead).
Data type/MemberMillisecond timestamp detailing when the lead occurred
Attribute values (example)″1400592736149400″

 

AttributeLast Sale
Attribute namesale_last_tm
DescriptionTime of the last purchase (sale)
Data type/MemberMillisecond timestamp detailing when the sale occurred
Attribute values (example)″1400592736149400″

 

AttributeTime of the last order
Attribute nametime_since_last_order_segment
DescriptionStandard attribute for categorisation according to time intervals between orders
Data typeString
Attribute values″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_01″
(No order) (default value)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_02″
(1-30 days)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_03″
(31-90 days)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_04″
(91 days - 12 months)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_05″
(more than 12 months)

 

AttributeNumber of leads
Attribute namelead_number_of_orders
DescriptionNumber of orders (leads) in a specific period
Data typeNumber
Attribute values (example)″16″

 

Attribute Number of sales
Attribute namesale_number_of_orders
DescriptionNumber of purchases (sales) in a specific period
Data typeNumber
Attribute values (example)″12″

 

AttributeSum of leads
Attribute namelead_sum_order_price
DescriptionGoods value of the order (lead) in EURO cents
Data typeNumber
Attribute values (example)″120192″

 

AttributeSumme Sale
Attribute namesale_sum_order_price
DescriptionGoods value of the purchase (sale) in EURO cents
Data typeNumber
Attribute values (example)″100190″

 

AttributeTime between leads
Attribute namelead_avg_time_between_orders
DescriptionAverage interval between orders (leads) in milliseconds
Data typeNumber
Attribute values (example)″120102″

 

AttributTime between sales
Attributnamesale_avg_time_between_orders
DescriptionAverage interval between purchases (sales) in milliseconds
Data typeNumber
Attribute values (example)″16036865125″

 

AttributeProduct quantity lead
Attribute namelead_total_number_of_articles
DescriptionTotal unit count of the order (lead)
Data typeNumber
Attribute values (example)″40″

 

AttributeProduct quantity sale
Attribute namesale_total_number_of_articles
DescriptionTotal unit count of the purchase (sale)
Data typeNumber
Attribute values (example)″16″

 

AttributeAverage order value
Attribute nameavg_order_value_seg
DescriptionStandard attribute which records the amount of average order values in EURO
Data typeString
Attribute values“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_01”
(0-10) (default value)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_02”
(11-20)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_03”
(21-40)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_04”
(41-80)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_05”
(81-100)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_06”
(101-200)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_07”
(201-400)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_08”
(401-800)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_09”
(801-1000)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_10”
(1001-2000)
“STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_11”
(2001-4000)

Product information

Attributes of product categoriesTop 10 product categories “Basket”
Top 10 product categories “Bought”
Top 10 product categories “Viewed”
Attribute namebasket_products_categories
sale_bought_products_categories
viewed_products_categories
DescriptionTop 10 list of product categories which indicates from which product categories
- most product were placed in the basket,
- most products were bought,
- most products were viewed.

All lists are structured identically. The JSON property ‘rank’ indicates the position in the top 10, with “10” being the best. The timestamp shows when the last changes were made and the counter shows how often the product category was opened.
Data typeArray with objects.
Inside the objects there is the data type ‘String’
(JSON Property ‘category_name’)
and the data type ‘Number’
(JSON Properties ‘timestamp’,’rank’ und ‘counter’)
Attribute values (example)[


{ "timestamp": "1416921576121300", "rank": "1", "category_name": "Others", "counter": "3" }
,
{ "timestamp": "1416921576121300", "rank": "3", "category_name": "Geometric bodies", "counter": "9" }
,
{ "timestamp": "1416921567909000", "rank": "2", "category_name": "foods", "counter": "2" }


]

 

Product attributesTop 10 products “Basket”
Top 10 products “Bought”
Top 10 products “Viewed”
Attribute namebasket_products
sale_bought_products
viewed_products
DescriptionTop 10 list of products shows which products
- were placed in the basket the most often,
- were bought the most often,
- were viewed the most often.

All lists are structured identically. The JSON property “rank” indicates the position in the top 10, with “10” being the best. The timestamp shows when the last changes were made and the counter shows how often the product was opened.
Data typeArray with objects.
Inside the objects there is the data type ‘String’
(JSON Properties ‘category_<0-3>‘)
and ‘product_name’)
and the data type ‘Number’
(JSON Properties ‘timestamp’,’rank’, ‘product_id’ and ‘counter’)
Attribute values (example)[


{ "timestamp": "1416921567909000", "rank": "2", "product_id": "6450", "category_3": "delicious", "category_1": "Sweets", "counter": "2", "product_name": "white chocolate", "category_2": "chocolaty", "category_0": "foods" }
,

{ "timestamp": "1416921567909000", "rank": "1", "product_id": "6451", "category_3": "delicious", "category_1": "Sweets", "counter": "1", "product_name": "Dark chocolate", "category_2": "chocolaty", "category_0": "foods"}


]

(The product “white chocolate” with the ID “6450” has achieved the best positioning in regard to the considered attribute. For the “sale_bought_products” attribute, this would mean that white chocolate was sold more often than other products.)

3.2.4 Engagement & Lead Attributes

AttributeTime since last visit
Attribute namefrequency_seg
DescriptionStandard attribute describing time intervals between visits
Data typeString
Attribute values“STC_CC_ATTR_VALUE_FREQUENCY_SEG_01”
(less than 1 day) (default value)
“STC_CC_ATTR_VALUE_FREQUENCY_SEG _02”
(1-7 days)
“STC_CC_ATTR_VALUE_FREQUENCY_SEG _03”
(8-30 days)
“STC_CC_ATTR_VALUE_FREQUENCY_SEG _04”
(More than 30 days)

 

Attribute First visit
Attribute nameengagement_lifetime
DescriptionTime of the first visit
Data type/MemberMillisecond timestamp detailing when the visit occurred
Attribute values (example)″1404217686586200″

 

AttributeLast visit
Attribute nameengagement_recency
DescriptionTime of the last visit
Data type/MemberMillisecond timestamp detailing when the visit occurred
Attribute values (example)″1404480183492400″
Note:
In order to be able to use the following top 10 list for areas or pages, the parameters for page names and areas in the parameter block of the tracking code must be transferred.
Attributes for favouritesTop 10 list for areas or pages
Attribute nameengagement_favorites_area,
engagement_favorites_page
DescriptionTop 10 list detailing which areas/pages were visited the most often. Every area/page has a timestamp and a rank of type Number. The timestamp shows when the last changes were made.
Data typeArray with objects.
Inside the objects is the data type ‘String’
(JSON Properties ‘page’ and ‘area’)
and the data type ‘Number’
(JSON Properties ‘timestamp’ and ‘rank’)
Attribute values
(example of page favourites)
[
{
“timestamp”: “1415627028457600”,
“rank”: “1”,
“page”: “dmexco”
},
{
“timestamp”: “1415713855503100”,
“rank”: “3”,
“page”: “Index”
},
{
“timestamp”: “1415713855436000”,
“rank”: “2”,
“page”: “Targeting Suite”
}
]
(The index page has the rank 3)

 

AttributeNewsletter subscriber
Attribute nameis_newsletter_recipient
DescriptionStandard attribute which indicates if a visitor has registered for the newsletter.
Data typeString
Attribute values“STC_CC_ATTR_VALUE_NEWSLETTER_1”
(yes)
“STC_CC_ATTR_VALUE_NEWSLETTER_2”
(no) (default value)

3.2.5 Status Attributes

AttributeRepeat visitors
Attribute namevisitor_type
DescriptionStandard attribute which indicates if a visitor is returning (or is new)
Data typeString
Attribute values“STC_CC_ATTR_VALUE_VISITOR_TYPE_1”
(yes)
“STC_CC_ATTR_VALUE_VISITOR_TYPE_2”
(no) (default value)

 

AttributeCustomer
Attribute namecustomer_type
DescriptionStandard attribute which indicates if a visitor is a customer or not
Data typeString
Attribute values“STC_CC_ATTR_VALUE_CUSTOMER_TYPE_1”
(yes)
“STC_CC_ATTR_VALUE_ CUSTOMER _TYPE_2”
(no) (default value)

4 Error Messages

Error CodeHTTP Status CodeError MessageError Message
3504The request timed out.Timeout des Requests
4403The access to the requested resource has been denied.Access to resource denied
5500An internal server error occurred.Internal server error
10400The secure code is missing (parameter et).Secure code is missing
11400The passed secure code is invalid.Secure code is invalid
12404Could not get a valid user mapping for the passed _et_coid cookie or _et_coid request parameter.Targeting API not activated
16400The requested API version is not supported.API version is not supported
99500An unexpected error ocurred.Unexpected error

5 Display of Smart Messages with the Targeting API

On GitHub, etracker provides a jQuery plugin for viewing smart messages. The jquery.smartmessage plugin can be used to show how Exit-Intent, Attention Grabber or Greeter Messages can be implemented. The plugin queries the Targeting API for user profiles and uses etracker Analytics for tracking.

c Remarketing Feed

  1. Function and Purpose of the etracker Remarketing Feed
  2. Requirements of Using the Remarketing Feed
  3. Segments
  4. Data Format

1 Function and Purpose of the etracker Remarketing Feed

The remarketing feed interface between etracker and email marketing systems is unidirectional. That means etracker data will be transferred to the email marketing system.

The data is transferred in 5-minute intervals. Each data record is always transferred just once to the email marketing system. Transfer is done via an SFTP server whose access data the provider of the email marketing system makes available to etracker. The short exchange interval enables the on-time sending of reminder emails.

When the requirements specified below are satisfied, then remarketing feed segment data and recipient IDs can be transferred to email marketing systems via etracker for remarketing purposes.

2 Requirements of Using the Remarketing Feed

The following requirements need to be satisfied in order to be able to use the etracker Remarketing Feed:

      • Product performance events (product viewed, product placed in basket and/or product ordered) are transferred to etracker using the etracker eCommerce API.
      • Recipient IDs are transferred via the target link (campaign link) in mailouts to etracker. So that this works, the campaign links in mailout must be augmented with HTTP GET parameters.
        This way, the success of the mailout can on the one hand be tracked and on the other visitor data can from then on can be assigned to mailout recipients.
      • SFTP exchange between etracker and the email marketing system is set up.
      • Campaign with template(s) and set of rules is set up in the email marketing system. This means that the email marketing system can derive suitable rules or triggers from the etracker events.
      • Depending on the campaign (promotion), the shop system or CRM supports persistent shopping baskets and, if necessary, discount codes among other things.

Transferring recipient IDs which are assigned pseudonyms and other mailout information (attributes) to etracker can be done via URL parameters which can be attached to mailout campaign links.

The minimum attribute set consists of four attributes:

AttributeParameterDescription
Mediumetcc_medDescribes the type/channel of a campaign or a source of traffic (SEO, SEA, Type-In, Link/Referrer, Social Media, email).
Campaignetcc_cmpServes to differentiate between advertising campaigns so as to be able to compare them better. In the case of mailouts, different mailout names or distribution times, for example, are tracked.
Mailout IDetcc_midThe mailout ID (see above) transferred to etracker.
Recipient IDetcc_ridA parameter (HTTP-GET, etcc_rid) transferred via mailing which corresponds to a user (see above).

A link for email marketing could, for example, look like this:
www.targetdomain.de?etcc_med=E-Mail&etcc_cmp=Newsletter_July&etcc_mid=123&etcc_rid=12345

The recipient ID transferred here is 12345 and it is assigned the mailout ID 123.

We recommend sending the recipient ID together with all system emails like order confirmations, delivery information, newsletter registration confirmations, etc. in order to enable as complete as possible an allocation of recipients over longer time frames and across different devices.

3 Segments

The standard segments for eCommerce applications are subsets of analysis data which have an identical parameter value in regard to a visitor action. The observed visitor actions are productViews, orders and abandonments. The segment of the product views contains all of the visitors who viewed a product during a certain period. We view orders and abandonments in the same way.

Recording visitor action (events) is done using eCommerce API in etracker Analytics. The eCommerce API needs to be built into the website accordingly.

4 Data Format

The data format is specific for the eCommerce use-cases. The UTF-8 character set and URL coding are used.

Note:
Due to the transmission errors and corruption of URLs, data can be incorrect in exceptional circumstances.
Nr.NameData typeDescription
1dateStringDate when the action (the event) occurred. In the case of a productView, for example, the time when the visitor viewed the product. The format is YYYY-MM-DD HH:mm:SS. The timezone is always CET/CEST.
2etcc_ridStringRecipient ID (HTTP parameter etcc_rid), which was transferred to etracker using the campaign link of an email. Corresponds to one visitor.
3etcc_midInteger, 64 Bit, long The mailout ID transferred to etracker (HTTP parameter etcc_mid). This field can be empty if the action (the event) can no longer be assigned to a mailout due to transmission errors or URL manipulation.
In etracker, you can set if the assignment of a conversion to a campaign is done according to the ‘First Ad’ (first click wins) or ‘Last Ad’ (last click wins) principle. Depending on the customer journey, the field of the mailout ID is occupied by a campaign (conversion is assigned to a mailout) or empty.
4eventtypeStringType of the event. There are three possible default values for this: ‘abandonment’, ‘order’ or ‘productView’.
5contextStringProduct number (SKU Stock Keeping Unit).
6categoryStringCategory information separated by forward slashes which were transferred to etracker using the eCommerce API.
7pricefloatGross price of the product.
8quantityInteger, 32 BitNumber of products for this event type (e.g. number of products in the order). Multiplied by the price results in the total amount for this event type.
9BestellnummerStringValue from the eCommerce System, which shows which positions belong to an order. If multiple lines in this export belong to one order, the order number will always be the same. Different order numbers refer to different orders.
10Session-IDStringID of the visitor session. Using this parameter, products in a cancelled basket can be identified. If session IDs of visitors are also transferred for product views, connected product views can also be identified. If the number here is the same, then the products are from the same basket or the views are from the same session.

The files are named according to the following convention:

<yyyy-MM-dd_HH-mm-ss>_<etracker_string>.cs

The designation of the <etracker_string> can be chosen freely and is used for generating unique files. The date should always show the start of the dates from the interval.

The provider of the email marketing system creates a folder for the files and forwards the path to etracker.

d External Generation of Test Accounts

  1. Initial Requirements
  2. External Setup of Test Accounts
    1. Transferring Variables
    2. Sending JSON Object
    3. Test Account Creation with ‘RESTClient’
    4. All Possible Variables in the JSON Object
  3. Possible Error Messages

1 Initial Requirements

An etracker partner ID is required when allocating the externally created test accounts. These can be received from your etracker Account Manager within the framework of a partner contract. The Partner ID is transferred as well when the test account is created and guarantees secure assignment to the partner.

In the following examples, the Partner ID 1111 is used as a placeholder and must be replaced by the ID assigned to you.

All code examples can also be found in the purely technical online documentation: https://application.etracker.com/docs/index.php?apiName=backoffice#

If you wish to remain updated in this regard, please use the following login data:

Username:  apiDocumentation

Password:   -etracker215-

lease use the following Username without password for the “Try it out!” button:

fbc45d3f099c5f46a51b880e92db7120

2 External Setup of Test Accounts

For the external setup of an etracker test account when sending the partner form (or with the corresponding trigger on the partner page), a JSON object needs to be filled dynamically with values and sent to an etracker. The following example shows the transfer of variables which need to be transferred as a minimum.

2.1 Transferring Variables

{  "url": "http://www.test.de",  "email": "test@test.de",  "firstname": "TEST",  "lastname": "TEST2",  "commercial": "business",  "company": "TEST GmbH",  "packageId": 139,  "additionalPackageId": 150,  "partnerId": 1111,  "dryrun": "false" }

A test account with the products “etracker Analytics Enterprise Edition” and “etracker Optimiser Enterprise Edition” are set up in the backend system. The test account will be assigned to the partner with the ID you entered.

The generated account ID and a link for the password allocation will be sent automatically to the email address provided here: test@test.de.

2.2 Sending JSON Object

The JSON object must be sent to the following URL and usernames using the POST method:

URL: https://application.etracker.com/api/backoffice/v4/accounts
Username: fbc45d3f099c5f46a51b880e92db7120

2.3 Test Account Creation with ‘RESTClient’

To see if the parameters for a test account were transferred correctly you can easily use the ‘RESTClient’ plugin for Firefox (https://addons.mozilla.org/de/firefox/addon/restclient/ ).

This information is required here:

1. Select the method “Post” and enter the above-mentioned URL:

test-account_2-3_erstellung-mit-restclient

2. The header to be used in the plugin is the above-mentioned username:

test-account_2-3_erstellung-mit-restclient-png_2

3. Insert the JSON Object into the body of the plugin:

e.g. the minimum transfer to variables from point 2.1.

2.4 All Possible Variables in the JSON Object

The following information can be transferred to etracker when creating a test account along with mandatory variables.

{   "url": "string",   "email": "string",   "firstname": "string",   "lastname": "string",   "email-billing": "string",   "commercial": 0,   "company": "string",   "sex": 0,   "street": "string",   "zip": "string",   "city": "string",   "phone": "string",   "country": "string",   "taxnr": "string",   "service-period": 0,   "accounting-period": 0,   "packageId": 0,   "additionalPackageId": 0,   "paymethod": "string",   "partnerId": 0,   "dryrun": "string" }

In case the optional parameters are not filled, default values will need to be set or the variable discarded.

Here is a view of all possible parameter values.

{ url (string), email (string), "Please enter a valid mail address, maxlength 150" firstname (string), lastname (string), email-billing (string, optional), "Please enter a valid mail address, maxlength 150" commercial (integer, optional): [undefined, private, business] - param company must only be filled when commercial=business , company (string, optional), sex (integer, optional): [male, female] , street (string, optional), zip (string, optional), city (string, optional), phone (string, optional), country (string, optional), "country maxlength=2, ISO 3166 Codes ALPHA-2 http://de.wikipedia.org/wiki/ISO_3166" taxnr (string, optional), service-period (integer, optional): [1, 3, 12] , accounting-period (integer, optional): [1, 3, 12] , packageId (integer): additionalPackageId (integer, optional): paymethod (string, optional): [bill, paypal, creditcard] , partnerId (integer): partner id , dryrun (string, optional): [true, false] }

3 Possible Error Messages

HTTP status CodeReason
200
400validation error
401access denied
403not allowed to create an account with that specific package
429rate limit exceed
500service error

e Single Sign-On (SSO)

The Single Sign-On describes an interface for logging a CMS user directly into etracker.

What does that mean? – An example

etracker data like the number of visitors to an online shop will be exported and made available to the user in their CMS/shop system. This user would like to receive additional information on where their visitors are coming from. Using a link in the CMS/shop system, this user, without having to log themselves in to etracker, can directly access the etracker application and a report which shows the origin of the shop visitors.

Integration

Logging in is done with the help of a POST call of the https://application.etracker.com/login.php URL with the body in the following format:

  • username = Name of the account
  • password = Password
  • cmsLogin = CMS2
  • targetUrl = Path to the page to be viewed (optional)

# Example with curl:

curl –data “username=123456&password=Secret&cmsLogin=CMS2” https://application.etracker.com/login.php

# Example with TargetUrl

curl –data “username=123456&password=Secret&cmsLogin=CMS2&targetUrl=/report/EATime” https://application.etracker.com/login.php

The response includes a URL which is valid for 60 seconds and enables a direct single call of the etracker application.

The target URL can be copied from the address of the etracker application. Here, the section after the hash key is copied:

Example:
https://newapp.etracker.com/#/report/EATime => /report/EATime

f Testing API

  1. Introduction
  2. How to use the API
    1. API Components
    2. Business Objects
    3. Groups and Permissions
    4. Authentication
    5. API URLs and Versioning
    6. Operations and Ressources
    7. Naming and Ressources
    8. CRUD Operations
    9. Non-CRUD Operations
    10. Passing Data Objects
    11. JSON as Data Format
    12. Nested Objects
    13. REST Responses and Error Handling
    14. Qualifying GET Operations
  3. Reference of Ressources and Operations
    1. Account
    2. Project
    3. Decision
    4. Goal
    5. Rule
    6. Condition
    7. Trend

1 Introduction

Erweitern Sie mit der etracker Testing API Ihr Content-Management- oder Shopsystem um Testing- und Conversion-Optimierungs-Funktionalität. Über eine REST-Schnittstelle nutzen Sie alle Testing-Funktionen, die Sie auch aus dem etracker Optimiser kennen, direkt in Ihrem System. Führen Sie A/B-Tests durch, spielen Sie personalisierte Inhalte aus und rufen Sie individuelle Reports zu den gesammelten Daten ab. Sie entscheiden selbst, wie die perfekte Integration in Ihre Systeme für Sie aussieht.

2 How to use the API

2.1 API Components

The REST API provides functionality in the following areas:

  • Management: Create, retrieve, update and delete projects and all related entities like pages, conversion goals and personalization rules.
  • Reporting: Retrieve data gathered in projects (mostly numbers of impressions and conversions on a daily basis) to visualize them in charts or create custom reports.
  • Delivery: Allows to retrieve personalized and optimized content from the API and to send conversion events in order to optimize applications with personalization and A/B testing via REST communication (vs. Javascript based delivering of content via the etracker Tag).

2.2 Business Objects

The Testing API deals with the following set of business objects.

2.2.1 Account

Represents a user account, where the user identifies herself with a combination of email/password or api-key and api-secret. Users can create projects inside an account.

2.2.2 Project

A project is a container to deliver views to visitors. This can happen by conducting an A/B-test or simply by delivering

2.2.3 Decissiongroup

A decisiongroup represents a sub-project. It is used for “Teaser Tests” and groups decisiongroups together. A project of type “TEASERTEST” may contain multiple decisiongroups, which in turn can contain multiple decisions.
For all other types of projects, decisions are direct children of the project itself.

2.2.4 Decission

A decision is one out of several possibilities to display a piece of content. In a typical project one decision would represent the original version of a web page (also called “the control”), while other decisions represent variants of the page. In an A/B test, the original and variant “decisions” are delivered to users in a randomized manner, while using personalization they could be delivered depending on visitor properties.

2.2.5 Goal

A (conversion-) goal helps to decide which of a project’s decision is the optimal one. A conversion goal could be something like

  • A page URL which has been requested by a visitor
  • The fact that the visitor has clicked some link and thus “engaged” with the website
  • A special Javascript function that has been called from the web page
  • etc.

By definition the decision with the best conversion rate is the best.

2.2.6 Rule and Rule-Condition

A rule is a set of rule conditions and is used to deliver personalized decisions. A condition is a single statement like

  • Visitor traffic source is paid search
  • Visitor device is mobile
  • etc.

A rule is a named set of conditions that combines conditions with AND or OR. It can be tied to a decision, so that a decision is only delivered if the rule is valid.

2.2.7 Trend

A trend is an array of data points, representing user actions in a project. Typically a trend contains impressions, conversions and conversion rates on a given day in a given period of time.

2.3 Groups and Permissions

Each consumer using the API is assigned to one of the following groups:

  • API-Tenants: This role allows to create and manage accounts, including deleting the account. When an account is created, an API-client is created automatically by etracker. The API-tenant role has all permissions of the API-clients it has created.
  • API-Clients: This role allows to manage one account and all nested resources like projects, variants, goals, rules etc. it is not possible to delete the account, though.

An API consumer is identified during authentication with an API key and –secret. Each API-consumer can be assigned to only one role, meaning:

  • Be an API-tenant
  • Be an API-client of one account.

API-tenants may read, update and delete all resources that they created themselves or their clients.

API-clients may read, update and delete all resources that they created, and they may read and update parts of their own account information.

2.4 Authentication

API consumers authenticate themselves via Basic Authentication, which means that an API-key and API-secret of the user have to be passed with every request in the HTTP Authorization header.

2.4.1 The Login Ressource

The API provides one resource (login) that does not represent a business object but is mainly to support authentication and login functionality. It validates API-key and API-secret and returns the internal account-ID of the API user which is necessary for subsequent API calls. The resource has to be called in the following way:
POST /login
with an object in the POST body that contains the following attributes:

FieldDescription
usertypeDepicts wether an API client or tenant accesses the API:
• api-client
• api-tenant
apikeyThe API-key
apisecretThe API-secret

2.5 API URLs and Versioning

The REST API is used by HTTP requests to URLs which are built up by the following parts:

<protocol>://<server and path>/<version>/<resource>/

FieldDescription
protocolOnly SSL is allowed as protocol. Calls to http:// will result in a 403 Forbidden error
server and pathThe server name and base path, typically www.blacktri.com/api/
versionWe use v1, v2... to version the API. The current version number is v1.
resourceThe actual resource that the call refers to. The specification focusses on resource names only and leaves out the rest of the API URL.

Example:

GET https://www.blacktri.com/api/v1/account/4711/project/2435/

2.6 Operations and Ressources

According to REST best practices, the Testing API uses HTTP methods as operations that act on business objects defined by URL “resources”. The following operations are supported:

  • GET: retrieves informations on an object.
  • POST: used to create objects or, more general, for operations that are not “idempotent”, meaning they change the system state after each operation.
  • PUT: used to update objects. An object must exist before it can be updated.
  • DELETE: used to delete objects.

Resources specify business objects via the URL. Example:

/account/4711

Refers to the user account with ID 4711.

2.7 Naming and Ressources

Resources refer to business objects. They are named in singular to represent a single object. When used in plural, they refer to a collection of objects. To identify a single object, an ID is added to the URL following the resource.

/account/    A single user account.

/account/4711    Account with ID 4711.

/account/4711/project/1324    Project 1324 of user 4711.

/account/4711/projects    List of all projects of user 4711

2.8 CRUD Operations

For creating, reading, updating and deleting objects the operations and resources are used as depicted in the following examples.

POST /account    Create a new account and obtain a reference to it in the response.

GET /account/4711    Returns an object for account with ID 4711.

PUT /account/4711/    Update account 4711 using the data passed in the request body.

DELETE /account/4711/project/1234    Delete project 1234.

POST /account/4711/project    Create a new project object for account 4711.

GET /account/4711/projects    Returnd all projects of account 4711.

2.9 Non-CRUD Operations

Some actions are represented by a resource name in case GET, POST, PUT or DELETE are not appropriate operations. Example:

POST /account/4711/project/1234/goal/1654/convert

By this request a client informs the system that a conversion for goal 1654 has happened and shall be tracked.

2.10 Passing Data Objects

With POST and PUT typically a data object is passed which represents a resource that shall be created or updated.

  • Depending on the role of the API consumer some objects attributes can be read-only. If a read-only attribute is passed in a POST or PUT operation (e.g. creation date and time of the resource), an error is returned and the complete operation is discarded.
  • PUT can be used for partial updates, meaning not all attributes of an object need to be contained in the data object. Only those attributes that are contained will be used in the update then.
  • In case a PUT operation is used for a resource which has not been created yet with POST, an error will be raised.
  • Objects can have mandatory attributes. If these are not passed in the data object of a POST operation, an error will be raised.

2.11 JSON as Data Format

As of now, only JSON is supported as the data format in request and response

2.12 Nested Objects

There is a hierarchy of objects which the API refers to. The way this hierarchy is reflected in API calls is depending on the specific operation with regards to the following 2 aspects:

  • How can nested objects be read? By directly accessing them via a resource URL, or as part of the response of the parent object?
  • How can nested objects be created and updated respectively?

2.12.1 Direct Access via URL

Nested objects can always be directly referenced as a resource URL as depicted above:

GET /account/4711/project/1234/variant/88364    Read data of variant 88364

POST /account/4711/project    Create a new project

etc.

2.12.2 GET Operations and Collection Attributes

Some resources allow to return objects and their nested child objects in one request. In such a case the data object contains a collection attribute.
Example:

GET /account/4711/project/1234?list=variants

This would return an object of type project which has an attribute variants that contains all variants of the project.

2.12.3 POST and PUT Operations and Collection Attributes

Some resources allow to pass objects containing nested child objects in a collection attribute. In such a case the following rules apply:

  • When nested objects are passed as part of a POST operation, the parent object is created first and then the child objects.
  • When nested objects are passed as part of a PUT operation, the parent object is updated together with the child objects.
  • When the collection attribute in a PUT operation does not contain all existing child objects of an object, the child objects not in the collection will be deleted.

2.13 REST Responses and Error Handling

For every request the Testing API provides an HTTP response status in some cases (depending on the specific operation) an HTTP header and a JSON formatted response data object.

2.13.1 Successful POST Operations

When a resource has been created from a successful POST operation, the following response is created:

FieldContentDescription
HTTP Status-Code201 Created
HTTP-Location-HeaderLocation:The location header contains the URL of the new resource, so a GET request can read the details of the new resource.
If nested objects have been created together with the POST, nothing is returned for them.
Response-BodyThe response body is empty.

2.13.2 Successful GET Operations

If a resource can be successfully read, the following response is created:

FieldContentDescription
HTTP Status-Code200 OK
Response-BodyThe response body contains the data object.

2.13.3 Successful PUT Operations

When a resource has been sucessfully updated by a PUT operation the following response is created:

FieldContentDescription
HTTP Status-Code204 No content
Response-BodyThe response body is empty.

2.13.4 Successful DELETE Operations

When a resource has been sucessfully deleted by a DELETE operation the following response is created:

FieldContentDescription
HTTP Status-Code204 No content
Response-BodyThe response body is empty.

2.13.5 Error Handling

In case of an error, the HTTP status code has a specific value and the returned data object contains information on the error.

FieldContentDescription
HTTP Status-Code<3 digit HTTP error code> Status code and HTTP reason (a short error message) are depending on the error.
Response-BodyJSON encoded error object, see below.

2.13.6 Error Object

FieldContent
codeDetailed error code. Since there is a limited number of 3 digit HTTP codes, this codes allows to qualify the exact error.
messageClear text error message.

2.13.7 List of API Errors

CodeHTTP CodeMessage
400003400Invalid field/s:
400004400Invalid value supplied for : ""
400100400Mandatory field/s for account missing:
400101400Read-only field/s for account not allowed to be set:
400103400Invalid field: not allowed to change publicid
400104400Unique constraint violation: publicid must be unique
400105400Unique constraint violation: email must be unique
400200400Mandatory field/s for project missing:
400201400Read only field/s for project not allowed to be set:
400300400Mandatory field/s for decision missing:
400301400Read only field/s for decision not allowed to be set:
400400400Mandatory field/s for rules missing:
400401400Read-only field/s for rules not allowed to be set:
400500400Mandatory field/s for rule conditions missing:
400501400Read-only field/s for rule conditions not allowed to be set:
400600400Mandatory field/s for goals missing:
400601400Read-only field/s for goals not allowed to be set:
401000401Authentication error: Invalid api-key or api-secret
403006403No permission for feature/s:
403102403Authorization error, no permission to create account
403103403Authorization error: Access to account denied
403203403Authorization error: Access to project denied
404001404Resource not found:

2.14 Qualifying GET Operations

Some GET operations allow to further qualify the response, e.g. to filter it or control wether nested objects shall be contained in the response or not. Which qualifiers are available is specified in the documentation.

3 Reference of Ressources and Operations

3.1 Account

An account represents the client or user who creates and manages projects to conduct A/B testing or deliver personalized content on his website, app or application. Since account might be purchased by customers, they can be packed with different amounts of quota and different feature sets.
A client could access the account (and all other resources) from a website which is operated by an API-Tenant (etracker and etracker partners are treated as API-Tenants themselves), in which case the API-Tenant uses the API to provide all necessary backend functionality on the website. Alternatively and if desired additionally, the client could use the API to do the same which the website would allow.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
IdintRRInternat account ID
Subidstring, 64RWROptional custom account ID for user system
publicidstring, 40RWRPublicly used account ID string (e.g. in tracking code). Must be unique among all accounts. If no publicid is provided when the account is created, an ID is assigned automatically and can be read from the resource after creation.
emailstring, 255RWREmail address. When set it must be unique for all accounts of a tenant.
passwordstring, 128RW-The account's password.
apikeystring, 64RW-The account's API secret. After creation of the account it is empty and needs to be set by the API tenant.
emailvalidatedbooleanRWRIndicates email has been verified by a double opt-in mail.
custom1string, 64RWRCustom field.
custom2string, 64RWRCustom field.
custom3string, 64RWRCustom field.
FeaturesarrayRW-An array indicating which features of etracker Testing & Targeting the account has permissions for. This can be used to create "packages" or "plans" with certain sets of features.
See the table below for possible values.
firstnamestring, 128RWRWFirst name of account user.
lastnamestring, 128RWRWLast name of account user.
StatusintRWRxStatus of this account:
• EVALUATION: Accounts in evaluation phase can be assigned a quota, and this quota will not automatically be renewed each month.
• FULL: An account with full access and monthly renewed quota.
• HIBERNATED: The client can still log in to change some profile data and manage projects, but all projects are stopped.
• CANCELLED: The account has been cancelled, users can not log in or use the account in any other way.
Plan0intRWRAn ID indicating the user plan. There is no logic in etracker that makes use of it, it is more an identifier for the API-Tenant, who can set the quota or give access to
createddatedatetimeRRDate and time when the account has been created.
quotaintRWRxAvailable quota of unique visitors per month.
usedquotaintRRAmount of used quota in the current 30-day-period which starts each month on the day indicated in quota_reset_dayinmonth
freequotaintRWRDefault 0Amount of monthly quota which will not be billed.
quotareset dayinmonthintRRDay in month (1-28) to reset the used quota to 0. Days 29 to 31 are not used in order to be able to use the same day in each month (even february)
ipblackliststring, 1024RWRWA semicolon separated list of IP address substrings which shall be excluded for visitors.
trackingcodestringRRThe etracker Tracking Code to be included in the client website.

3.1.1 Remarks

  • An API-Tenant can use the account resource to provide registration and login functionality for his clients. He can read and write the necessary data via the API, but still has to implement functionality of web based registration, login, password reminder etc. by himself.
  • The API-Client can change only small parts of the account resource by himself, since most attributes are either in control of the API-Tenant (like userplan) or should be changed only by a UI provided from the API-tenant (like the password) or are under control of etracker (like the used quota).
  • If an API-Tenant needs more fields to fully manage a relationship to a client, he can make use of the 3 custom fields, or needs to store additional data in a local database where rows have a 1:1 relationship to the account resource (meaning: they should use the account id as foreign key).

3.1.2 Public ID

The field publicid is used as the account identifier in the etracker Testing Tag which has to be inserted in the client’s web pages for content injection. It thus needs to be unique among all accounts inside etracker Testing & Targeting. It can be left empty when creating an account, a unique value will then be created by the API. Alternatively, the tenant can provide a value and the API will raise an error if it is not unique.

3.1.3 Authentication

  • When the tenant creates an account, she has to determine how a client authenticates herself and interacts with the system: If the tenant provides a web application where clients can log in with email and password, the tenant should provide these fields when creating an account. To validate a client, the tenant would retrieve accounts with GET /accounts/ and provide email and password as filters (see below). This means the tenant would provide business logic to authenticate clients by herself. We recommend not storing the password in clear text, but creating an md5 hash first before sending it to the API.
  • The tenant can additionally order alternatively provide an API key and API secret to the client. The client could access the API herself using these credentials. etracker creates an API key for every new account, and if the tenant provides an API secret the client could use these data to get API access. As long as the API secret is not set, no API access is possible.

3.1.4 Features

The features array (see above) can have attributes as specified in the following table. In case an attribute is not contained, the default is used (thus the features array could be completely empty or not being passed when creating accounts).

NameDescription
visualtest(true|false) Projects of type "Visual A/B Test" can be created. The default is true.
splittest(true|false) Projects of type "Split Test" can be created. The default is true.
personalization(true|false) Personalization rules can be managed and assigned to projects. The default is true.
startenddate(true|false) Start and end date can be set for a project. The default is true.
numdecisions(1..n) The maximum number of variant decisions that can be created for a project. The default is unlimited.
numactiveprojects(1..n) The maximum number of running projects at the same time. The default is unlimited.

3.1.5 Operations on the Account Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the account. So when the following URI is mentioned.

Please not that deletion of accounts is not allowed. To deactivate an account, the api tenant can set the status to “CANCELLED”.

POST /account/

We refer in fact to a URI similar to this:

POST https://www.blacktri.com/api/v1/account/

3.1.5.1 POST /account

Create a new account and return the account’s URI. Only allowed for API-Tenants. An account object is passed in the request body.

3.1.5.2 PUT /account/<id>

Update an existing account. An account object is passed in the request body.

  • Allowed for both API-Tenants and API-Clients.
  • Write permissions apply as depicted in the table above.
3.1.5.3 GET /account/<id>

Get data for an existing account.

  • Write permissions apply as depicted in the table above.
3.1.5.4 GET /accounts

Only allowed for API-Tenants. Retrieves a list of all accounts they created (the result provides the URI for each account). The response will contain an ordered list of account objects.

The list can be searched/filtered with the following query string qualifiers that refer to values of the resource attributes (see above).

Name
subid
publicid
custom1
custom2
custom3
apikey
apisecret
email
emailvalidated
status

Example:

/accounts/?email=test@google.de&password=thisissecret    Retrieve an account for a given email and password to implement a login functionality.

/accounts/?status=FULL    Retrieve a list of all active (payed) accounts.

The result list can be sorted by providing the qualifier sort with one of the following attributes. A dash can be added to the attribute to indicate descending order.

Name
publicid
custom1
custom2
custom3
apikey
email
createdate

Example:

/accounts/?sort=email    Retrieves all accounts sorted ascending by email.

/accounts/?sort=-createddate    Retrieves all accounts sorted descending by creation date.

All qualifiers can be combined:
/accounts/?sort=-createddate&status=FULL

3.2 Project

A project is used by clients to conduct A/B tests and/or to deliver personalized content.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
idintRRInternal project ID
typestringRWRWxType of project:
• VISUAL: Visual A/B-test
• SPLIT: Split-test
mainurlstring, 1024RWRWxA URL representing the main original URL of a project. It is used to create a preview page and internal documentation.

Syntactically invaid URLs (protocol missing etc.) will raise an error.
runpatternstring, 1024RWRWxPattern (typically for a URL) which determines whether or not the project runs on a given URL or not. Oftentimes it is identical to mainurl.
An asterisk (*) can be used as a wildcard in the URL.
createddatedatetimeRRDate and time when project has been created
startdatedatetimeRWRWProject does not collect before this datetime. The format is 'YYYY-MM-DD hh:mm:ss', e.g.
'2015-04-22 22:10:12'.
enddatedatetimeRWRWProject does not collect after this datetime. The format is 'YYYY-MM-DD hh:mm:ss'
restartdatedatetimeRRDate when project has been restarted the last time
remainingdaysintRRNumber of days needed to make the project significant. In case this number cannot be computed yet, this fields contains -1.
nameintstring, 128RWRWxName of the project, does not need to be unique.
statusstringRRShows wether project is running or not:
• PAUSED
• RUNNING
visitorsintRRNumber of visitors that have participated in this project.
conversionsintRRNumber of conversions in this project.
conversionratefloatRRConversions divided by Visitors. If an A/B test is statistically significant, the conversion rate of the winning decision is returned here.
resultstringRRThe result of the project, meaningful for A/B-testing only.
• NA: Not applicable. The project is no A/B-test and has thus no result.
• NONE: The A/B test is not significant yet.
• LOST: The control decision has the highest conversion rate.
• WON: At least one decision has a higher conversion rate than the control.
originalidintRRID of the original decision.
winneridintRRIn case result=WON this field contains the ID of the winning decision (and -1 if result != WON).
winnernamestringRRIn case result=WON this field contains the name of the winning decision (and 'NA' if result != WON)
upliftfloatRRIn case result=WON this field contains the improvement of conversion rate of the winning decision relative to the original decision (and -1 if result != WON)
autopilotstringRRTells wether autopilot is running or not.
• NA: Not applicable because the project is no A/B test and has thus no significance.
• RUNNING: significant decisions are cut off from traffic and the best decision is delivered on end of test
• PAUSED: all decisions are delivered equally distributed
allocationint RW RW Value between 0 and 100. Determines the percentage of visitors to be allocated to this test. Default is 100.
ipblacklistingbooleanRW RW (true|false) Determines whether or not an IP blacklisting for the account is applied for this project (default is true)
personalization modestring RW RW Determines how personalization is managed in this project:
• NONE: No personalization for this project.
• COMPLETE: The project as a while is personalized, this means we have a personalized A/B test.
• SINGLE: Each decision can be assigned it's own personalization rule. The original is not delivered anymore.
The default is NONE. If this field is set to SINGLE or COMPLETE and personalization is not an available feature (see the account resource), then an error is raised.
ruleidintRW RW In case personalization mode is set to COMPLETE, this value refers to the rule resource which determines whether the project is delivered to visitors or not.
If the field is empty AND personalization mode = COMPLETE, then an error is returned.

3.2.1 Operations on the Project Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the account. So when the following URI is mentioned

POST /project/

We refer in fact to a URI similar to this:

POST https://www.blacktri.com/api/v1/account/4711/project/

3.2.1.1 POST /project

Create a new project and return the project’s URI. A project object is passed in the request body.

3.2.1.2 PUT /project/<id>

Update an existing project. A project object is passed in the request body.

3.2.1.3 GET /project/<id>

Get data for an existing project.

3.2.1.4 DELETE /project/<id>

Delete an existing project.

3.2.1.5 GET /projects

Retrieves a list of all projects of the given account in the URI. The response will contain an ordered list of project objects.

The list can be searched/filtered with the following query string qualifiers that refer to values of the resource attributes (see above).

Name
type
status

The result list can be sorted by providing the qualifier sort with one of the following attributes. A dash can be added to the attribute to indicate descending order.

Name
createddate
name

The fields contained in the result set can be determined or limited by providing a parameter fields with a comma separated list of field names. The following fields are contained in the resultset as default:

Name
id
name
mainurl
visitors
conversions
conversionrate
result
uplift
remainingdays

Example:

GET /account/4711/projects?sort=-createddate&status=RUNNING&fields=id,name,conversionrate

3.2.1.6 POST /project/<id>/start

Start a project. No object is passed in the request body, and no data are provided in the response.

3.2.1.7 POST /project/<id>/stop

Pause a project. No object is passed in the request body, and no data are provided in the response.

3.2.1.8 POST /project/<id>/restart

Delete all report data for a project and start over. No object is passed in the request body, and no data are provided in the response.

3.2.1.9 POST /project/<id>/autopilot/start

Start the project autopilot. No object is passed in the request body, and no data are provided in the response.

3.2.1.10 POST /project/<id>/autopilot/stop

Stop the project autopilot. No object is passed in the request body, and no data are provided in the response.

3.3 Decision

A decision is one out of a set of contents which can be delivered in a project. There is always one decision called the “original” or “control” decision which is the entity that shall be optimized, for example a web page. Additional variant decisions can be defined which are delivered alternatively. In an A/B test they are delivered together with the control in a random manner, in case of personalization they are delivered depending on whether personalization rules are matching or not.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
idintRRInternal decision ID
namestring, 128RWRWxName of the decision, does not need to be unique.
urlstring, 1024RWRWOnly relevant for Split-Test variants: contains the URL that shall be called instead of the control.
previewurlstring, 102RRA URL which opens a preview of the decision.
typestringRRThe type of decision:
• CONTROL
• VARIANT
The type cannot be set. When creating a project, the control decision is created automatically. All additional decisions are of type VARIANT.
ruleidintRWRWFor projects where
• personalization mode is set to SINGLE
• AND the type of this decision is VARIANT
this field refers to to the rule resource which determines whether the decision is delivered to visitors or not. If the field is empty, the decision is not personalized.
resultstringRRThe result/status that this variant has in an A/B test:
• NA: Not applicable since the project is no A/B test
• NONE: The status is not known since confidence is not significant yet.
• LOST:
o If the decision is the control: There is at least one variant decision with a higher conversion rate.
o If the decision is a variant: The control has a higher conversion rate than this decision.
• WON:
o If the decision is the control: There is no variant decision with a higher conversion rate.
o If the decision is a variant: The control has a lower conversion rate than this decision.
visitorsintRRNumber of visitors that have participated in the project and been delivered the decision.
conversionsintRRNumber of visitors that have participated in the project and been delivered the decision and converted subsequently.
conversion ratefloatRRConversion rate of this decision (conversions / visitors).
confidencefloatRRA value between 0.5 and 1 representing the probability that the result is not by accident. In case the confidence cannot be calculated it is 0.
distributionfloatRRA value between 0 and 1 representing the probability this decision will be delivered to a visitor.
jsinjectiontextRWRWJavascript code to be injected into a webpage to visualize the content of the decision. This is only applicable for projects of type VISUAL.
cssinjectiontextRWRWCSS code to be injected into a webpage to visualize the content of the decision. This is only applicable for projects of type VISUAL.

3.3.1 Operations on the Decision Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the decision. So when the following URI is mentioned

POST /decision/
We refer in fact to a URI similar to this:
POST https://www.blacktri.com/api/v1/account/4711/project/456/decision/

3.3.1.1 POST /decision

Create a new decision and return the decision’s URI. A decision object is passed in the request body. Only decisions of type variant can be created like this, the control decision is created implicitly when creating the project.

3.3.1.2 PUT /decision/<id>

Update an existing decision. A decision object is passed in the request body.

3.3.1.3 GET /decision/<id>

Get data for an existing decision.

3.3.1.4 DELETE /decision/<id>

Delete an existing decision. The control decision cannot be deleted.

3.3.1.5 GET /decisions

Retrieves a list of all decisions of the given project in the URI. The response will contain an ordered list of decision objects.
The result list can be sorted by providing the qualifier sort with one of the following attributes. A dash can be added to the attribute to indicate descending order. For all sort operations the control decision will be the first in the list.

Name
name
conversionrate

The list can be searched/filtered with the following querystring qualifiers that refer to values of the resource attributes (see above).

Name
result

3.4 Goal

A goal is a criterion to attach a conversion event to a decision. It typically represents a user action or the technical event that indicates a certain action. Goals are assigned to projects. Most of them only apply to online/mobile based projects.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
idintRRInternal goal ID
typestringRWRWxType of goal, one of the following:
• ENGAGEMENT: user clicks a link on the landingpage.
• AFFILIATE: user klicks a link which is from a known affiliate network.
• TARGETPAGE: user loads a page with a given URL. An asterisk (*) can be used as a wildcard in the URL.
• LINKURL: user klicks a link with a given URL. An asterisk (*) can be used as a wildcard in the URL.
• CUSTOMJS: user does something that triggers calling a certain predifined Javascript function.
paramstring, 512RWRWAn optional parameter, needed for some of above goals:
• If goal is TARGETPAGE: URL of page that shall be opened.
• If goal is LINKURL: URL of link that shall be clicked.

3.4.1 Operations on the Goal Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned

POST /goal/

We refer in fact to a URI similar to this:

POST https://www.blacktri.com/api/v1/account/4711/project/456/goal/

3.4.1.1 POST /goal3.5 Rule

The rule resource represents a personalization rule, consisting of one or more condition resources.

Create a new goal and return the goal’s URI. A goal object is passed in the request body.

3.4.1.2 PUT /goal/<id>

Update an existing goal. A goal object is passed in the request body.

3.4.1.3 GET /goal/<id>

Get data for an existing goal.

3.4.1.4 DELETE /goal/<id>

Delete an existing goal.

3.4.1.5 GET /goals

Retrieves a list of all goals of the given project in the URI. The response will contain an ordered list of goal objects.
The list can be searched/filtered with the following querystring qualifiers that refer to values of the resource attributes (see above).

3.5 Rule

The rule resource represents a personalization rule, consisting of one or more condition resources.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
idintRRInternal rule ID
namestring, 128RWRWxDisplay name of the rule
operationstringRWRWxThe boolean operator to combine all related conditions. One out of:
• AND
• OR
conditionslistRRA list of related conditions resource objects.

3.5.1 Operations on the Rule Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned
POST /rule/
We refer in fact to a URI similar to this:
POST https://www.blacktri.com/api/v1/account/4711/rule/

3.5.1.1 POST /rule

Create a new goal and return the rule’s URI. A rule object is passed in the request body.

3.5.1.2 PUT /rule/<id>

Update an existing rule. A rule object is passed in the request body.

3.5.1.3 GET /rule/<id>

Get data for an existing rule.

3.5.1.4 DELETE /rule/<id>

Delete an existing rule.

3.5.1.5 GET /rules

Retrieves a list of all rules of the given account in the URI. The response will contain an ordered list of rule objects.

3.6 Condition

The condition resource represents a personalization condition which is always part of a rule.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
idintRRInternal condition ID
negationbooleanRWRWx(true|false) Whether the condition or it's negation must be met:
true: the condition's result will be negated before it gets returned
false: the conditions original value gets returned
typestringRWRWxThe kind of condition that will be evaluated. Which types are available is depending on the tenant and server implementation. Currently one out of the following:
• REFERRER_CONTAINS: the given substring ist contained in the HTTP referrer.
• URL_CONTAINS: the given substring is contained in the URL or querystring.
• SOURCE_IS: the referrer depicts that the visitor's traffic source is as specified.
• IS_RETURNING: the visitor is a new visitor vs. a returning visitor.
• SEARCH_IS: the traffic source is paid or organic search with one or more of the given keywords.
• TARGETPAGE_OPENED: visitor has opened the given page URL one or more times. Asterisk can be used as wildcard in URL.
• DEVICE_IS: visitor uses the given device.
• ETRACKER_RTA: Visitor profile as returned from the etracker Real Time API matches the provided argument
arg1string, 255RWRWAn argument, necessary for most of the rules (e.g. a substring for URL_CONTAINS). The following shows condition types where an argument is necessary, together with the allowed values:
• REFERRER_CONTAINS
• string with the following validation: alphanumeric (numbers and letters) and the following characters: &_-
• URL_CONTAINS
• string with the following validation: alphanumeric (numbers and letters) and the following characters: &_-
• SOURCE_IS: one of the following
• TYPE_IN: no referrer
• SOCIAL: social media
• ORGANIC_SEARCH: organic search
• PAID_SEARCH: paid earch
• IS_RETURNING: one of the following
• YES: is a returning visitor
• NO: is new
• SEARCH_IS
• A string with one or more words, separated by blanks. Validation is: alphanumeric (numbers and letters) and blanks.
• TARGETPAGE_OPENED
• string with the following validation: alphanumeric (numbers and letters) and the following characters: &_-.*
• DEVICE_IS: one of the following
• MOBILE
• TABLET
• DESKTOP
• ETRACKER_RTA: a match with a certain RTA attribute has to be provided as JSON string according to the following description:
• "attribute": Name of the RTA attribute
• "comparator": One out of
• EQUALS
• NOT_EQUALS
• TO
• FROM
• GREATER_THAN
• LESS_THAN
• "value": Return value of the API to be matched

3.6.1 Operations on the Condition Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned
POST /condition/
We refer in fact to a URI similar to this:
POST https://www.blacktri.com/api/v1/account/4711/rule/4567/condition/

3.6.1.1 POST /condition

Create a new condition and return the condition’s URI. A condition object is passed in the request body.

3.6.1.2 PUT /condition/<id>

Update an existing condition. A condition object is passed in the request body.

3.6.1.3 GET /condition/<id>

Get data for an existing condition.

3.6.1.4 DELETE /condition/<id>

Delete an existing condition.

3.6.1.5 GET /conditions

Retrieves a list of all conditions of the given rule in the URI. The response will contain an ordered list of condition objects.

3.7 Trend

The trend resource represents an array of data sets, each containing impressions and conversions of a decision resource in a given period of time. The trend resource can thus be used to populate charts or create custom reports.

FieldTypePermissions
API Tenant
Permission
API Client
Mandatory
On Create
Message
timestampsarrayRRAn array of datetime-objects, each representing the sample date and time of one data point. Currently each timestamp represents one day.
datasetsarrayRRAn array of dataset objects. Each represents one decision in a project. The first dataset is by convention the original ("control").
Each dataset contains the three arrays below (impressions, conversions, aggregatedcr).

.....namestringRRThe name of the decision.
.....impressionsarrayRRAn array of int. Each value represents the number of impressions for the decision on the corresponding timestamp.
.....conversionsarrayRRAn array of int. Each value represents the number of conversions for the decision on the corresponding timestamp.
.....aggregatedcrarrayRRAn array of float. Each value represents the conversion rate for the decision on the corresponding timestamp, aggregated over all impressions and conversions since starting or restarting the project.

Operations on the Trend Ressource

In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned

GET /trend/

We refer in fact to a URI similar to this:

GET https://www.blacktri.com/api/v1/account/4711/project/2435/trend/

Retrieves a trend object for a certain time period. The result can be parametrized with the following query string qualifiers.

NameTypeDescription
enddatetimeSpecifies the latest required timestamp in the result.
entriesintNumber of datapoints / timestamps in the result (currently translated to the number of days in the result).
The default is 30.
goalidintA goal for which conversions shall be calculated.

g Management of authorisation profiles and sub-users

  1. Managing authorisation profiles
    1. Query profile
    2. Create profile
    3. Delete profile
  2. Manage sub-users
    1. Query sub-users
    2. Create sub-user
    3. Delete sub-user

1. Managing authorisation profiles

The setup of the general route for the authorisation profiles is as follows:

https://ws.etracker.com/api/rest/v3/subuserPublic/role

1.1 Query profile

You can set a GET request in order to query existing authorisation profiles in your account. The following Curl example is good for demonstration purposes here:

curl 'https://ws.etracker.com/api/rest/v3/subuserPublic/role' -X GET -H 'X-ET-email: qa@etracker.com' -H 'X-ET-developerToken: ab7891ca89d9b4d10dc1703a7f0214256babe6c9' -H 'X-ET-accountId: 18854' -H 'X-ET-password: demo'

As a response to the GET request, you will then receive:

[[{"id":"7","name":"Read and write 
permissions","version":"1","users":"1"},{"id":"5","name":"Read 
permissions","version":"1","users":"2"}]]

1.2 Create profile

The following Curl example shows you how to create an authorisation profile that grants access to two sub-users:

curl 'https://ws.etracker.com/api/rest/v3/subuserPublic/role' -X POST -H 'X-ET-email: qa@etracker.com' -H 'X-ET-developerToken: ab7891ca89d9b4d10dc1703a7f0214256babe6c9' -H 'X-ET-accountId: 18854' -H 'X-ET-password: demo' --data 'name=Test&role_type=admin&multi_client_access_mode=custom&multi_clients_selection%5B%5D=18855&multi_clients_selection%5B%5D=260960'

The information contained in the “–data” parameter is:

name = The name for the authorisation profile can be freely chosen and must be unique

role_type = Read and write permissions or just read permissions, value can be: read_only or admin

multi_client_access_mode = Set whether or not multiple clients can be accessed using this authorisation profile. Values can be: none, all or custom.

multi_clients_selection = Details of the multiple clients to whom access is granted. More than just one can be entered.

Important note: In the “–data” parameter, the following information must always be contained: name, role_type and multi_client_access_mode

If the value “custom” is assigned to multi_client_access_mode, the corresponding accounts (multiple clients) must be set via multi_clients_selection (see Curl example).

1.3 Delete profile

The setup of the route for deleting an authorisation profile is as follows:

https://ws.etracker.com/api/rest/v3/subuserPublic/role/<roleId>

The following Curl shows a DELETE request, which deletes the profile with the ID 7.

curl 'https://ws.etracker.com/api/rest/v3/subuserPublic/role/7' -X DELETE -H 'X-ET-email: qa@etracker.com' -H 'X-ET-developerToken: ab7891ca89d9b4d10dc1703a7f0214256babe6c9' -H 'X-ET-accountId: 18854' -H 'X-ET-password: demo'
Note: The available “roleIDs” can be queried with a GET request (see Curl example in 2.1). It will not be possible to delete an authorisation profile if it is also assigned to another user.

2. Manage sub-users

The setup of the general route for sub-users is as follows:

https://ws.etracker.com/api/rest/v3/subuserPublic/user

2.1 Query sub-users

The following Curl example shows a GET request for querying already existing sub-users:

curl 'https://ws.etracker.com/api/rest/v3/subuserPublic/user' -X GET -H 'X-ET-email: qa@etracker.com' -H 'X-ET-developerToken: ab7891ca89d9b4d10dc1703a7f0214256babe6c9' -H 'X-ET-accountId: 18854' -H 'X-ET-password: demo'

As a response to the GET request, you will then receive:

[[{"id":"6","name":"Dalton","fname":"Lars","version":"1","subid":"2","role":"Read
permissions","role_type":"read_only","enable":"1","login":"3","role_id":"5"},
{"id":"8","name":"Write permission","fname":"Lars","version":"1","subid":"3","role":
"Read permissions","role_type":"read_only","enable":"1","login":"0","role_id":"5"},
{"id":"9","name":"Read-Write permission","fname":"Lars","version":"1","subid":"4",
"role":"Read and write permissions","role_type":"read_only","enable":"1","login":"3",
"role_id":"7"}]]

2.2 Create sub-user

The following Curl example shows you the setup of a sub-user:

curl 'https://ws.etracker.com/api/rest/v3/subuserPublic/user' -X POST -H 'X-ET-email: qa@etracker.com' -H 'X-ET-developerToken: ab7891ca89d9b4d10dc1703a7f0214256babe6c9' -H 'X-ET-accountId: 18854' -H 'X-ET-password: demo'--data 'enable=1&sex=0&fname=John&name=Doe&email=qa%40etracker.com&role_id=7&language=de&pass=test'

The information contained in the “–data” parameter is:

enable = active, value 1 or inactive, value 0

sex = female, value 0; sex male, value 1

fname = First name

name = Last name

email = Email address

role_id = Identifier of the user profile

pass = Password

language = language

(Spanish = es, English = en, French = fr and German = de)

In the “–data” parameter, the following information must always be contained:

role_id, name, fname, sex, pass, email, language, enable

Note: The available “roleIDs” can be queried with a GET request (see Curl example in 1.1).

2.3 Delete sub-user

The route for deleting a sub-user is as follows:

https://ws.etracker.com/api/rest/v3/subuserPublic/user/<userId>

The following Curl example shows a DELETE request which deletes the sub-user with the ID 8:

curl 'https://ws.etracker.com/api/rest/v3/subuserPublic/user/8' -X DELETE -H 'X-ET-email: qa@etracker.com' -H 'X-ET-developerToken: ab7891ca89d9b4d10dc1703a7f0214256babe6c9' -H 'X-ET-accountId: 18854' -H 'X-ET-password: demo'
Note: The available “userIDs” can be queried with a GET request (see 2.1).

 

Need help?
Our friendly, knowledgeable support engineers are here for you.