1. Home
  2. Data Services
  3. Targeting API

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.

Access to the 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 SettingsSetup/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/v6/realtime/user?et=<account-key>&amp;_et_coid=<CookieId>

Example:

https://ws.etracker.com/api/v6/realtime/user?et=YM9dM9&amp;_et_coid=6bbece51587a6f7aac4989953149ca47

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.

Response Structure

The 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” ] }

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:

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)
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
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_‘)
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.)
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)
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)

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

Display of Smart Messages

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.