etracker
Analytics Editionen / Preise Live-Demo
etracker
Optimiser Editionen / Preise Live-Demo
Preise Academy Support Know-how

Entwickler-APIs

  1. REST-Report API v3
  2. Targeting API
  3. Remarketing Feed
  4. Externe Erstellung von Test-Accounts
  5. Single Sign-On (SSO)
  6. Testing API

a REST-Report API v3

  1. Zweck der etracker REST-Report API
  2. Zugang zur etracker REST-Report API
  3. Die etracker REST-Report API nutzen
    1. Aufbau der URL für die REST-Calls
    2. Rückgabewerte
  4. Authentifizierung
  5. Abruf der zur Verfügung stehenden Reports
  6. Abruf von Report- und Metadaten sowie Request-Parametern
    1. Definition von etracker Reports
    2. Abfrage von Report Informationen
    3. Abruf von Report Daten
    4. Abruf von abfragespezifischen Report Metadaten
  7. Basis-Parameter der Report API
  8. Einschränkung von Attributen und Kennzahlen
  9. Dimensionsfilter
  10. Nutzung von Ansichten
  11. Fehlermeldungen
  12. Code-Beispiele
    1. Kommandozeilen-Tool curl
    2. PHP
    3. Java

1 Zweck der etracker REST-Report API

Die etracker REST-Report API v3 ist eine Schnittstelle, die Sie nutzen können, um eigene Anwendungen mit den Daten aus etracker zu entwickeln oder um diese Daten im eigenen Unternehmen weiter zu verarbeiten.

2 Zugang zur etracker REST-Report API

Um die etracker REST-Report API nutzen zu können, müssen Sie sich bei etracker anmelden. Sie hinterlegen bei unserem Support eine gültige E-Mail-Adresse und erhalten einen sogenannten ‚Entwickler-Token‘ (developer token). Mit der E-Mail-Adresse und dem Entwickler-Token sind Sie dann berechtigt, über die etracker REST-Report API auf Daten aus etracker zuzugreifen.

Hinweis:
Um Ihre Privatsphäre zu schützen und eine unberechtigte Benutzung der etracker Web Services API zu vermeiden, sollten Sie den Entwickler-Token in jedem Fall geheim halten.

Über Ihre gültige E-Mail-Adresse können Sie zeitnah über Weiterentwicklungen und Änderungen der etracker REST-Report API auf dem Laufenden gehalten werden. Bei der Anmeldung können Sie angeben, ob Sie regelmäßig Informationen zur etracker API haben möchten oder nicht.

Die E-Mail-Adresse und der Entwickler-Token sind in jeder Web Service Anfrage (Request) innerhalb des Anfrage-Headers mitzuliefern.

Hinweis:
Wenn Sie die etracker Analytics Enterprise Edition haben, können Sie die REST-Report API kostenlos nutzen. In allen anderen Fällen können Sie die Nutzung der REST-Report API gegen einen Aufpreis dazu buchen. Preise nennen wir Ihnen gerne auf Anfrage. Wenden Sie sich bei Bedarf an Ihren etracker Berater oder den Support.

3 Die etracker REST-Report API nutzen

Um die Nutzung der etracker REST-Report API zu erleichtern, sollten Sie einen REST-Client erstellen. Die Ausgestaltung des Clients hängt von der eingesetzten Programmiersprache ab. Der Client sendet die Anfragen an den Service und gibt definierte Werte zurück, die anschließend weiterverarbeitet werden können.

Außer einer Entwicklungsumgebung für die verwendete Programmiersprache benötigen Sie keinerlei weitere Software oder Installation auf Ihrem System.

3.1 Aufbau der URL für die REST-Calls

Die etracker REST API nimmt ausschließlich Calls über https entgegen. Alle in diesem Dokument beschriebenen Calls sind GET-Abfragen. Die Adresse des etracker REST-Servers ist  ws.etracker.com und die Basis-URI für alle Abfragen ist /api/rest/v3.

Die REST-Calls können mit oder ohne Parameter geschrieben sein. REST-Calls zum Abrufen von Report-Daten ohne Parameter werden nicht empfohlen, da unter Umständen sehr große Datenmengen zrückgegeben werden. Bei den Parametern wird nicht nach Groß- und Kleinschreibung unterschieden.

Beispiel mit Parametern zum Abrufen von Daten aus dem Report ‚Gerät‘:

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

Das gleiche Beispiel ohne Parameter (nicht empfohlen):

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

3.2 Rückgabewerte

Das Format der Rückgabewerte von etracker REST API Abfragen ist entweder JSON oder CSV. CSV wird nur bei der Abfrage von Report-Daten unterstützt und kommt nur dann zurück, wenn das Format explizit abgefragt wird. Bei den JSON-Rückgaben kommt immer ein JSON-Array oder -Objekt zurück, auch dann, wenn nur ein Wert zurückgegeben wird.

Die etracker REST-Report API arbeitet mit der Kodierung UTF-8. Alle Daten, welche die API liefert oder entgegennimmt, müssen in UTF-8 kodiert sein. Sonderzeichen wie Umlaute werden teilweise in Form von Javascript Escape-Sequenzen zurückgegeben. Ein ‚ä‘-Zeichen wäre dann z. B. ‚\u00e4‘ in den Rückgabedaten. Die meisten JSON-Parser wandeln solche Escape-Sequenzen automatisch in Buchstaben um.

4 Authentifizierung

Jede REST-Report-Anfrage muss mit einem Header versehen werden. Dieser dient dazu, die Authentifizierung an der API vorzunehmen.

Folgende Header-Informationen sind zwingend notwendig:

  • email: Dieses Header-Element enthält die E-Mail-Adresse des Entwicklers, der Zugriff auf die API hat.
  • developerToken: Dieses Header-Element enthält den Entwickler-Token, den Sie beim etracker Support anfordern können.
  • accountId: Dieses Element enthält die etracker Account-Id. Für die Authentifizierung kann auch ein etracker Mitbenutzer angegeben werden (Format: #accountId#-#subuserId#)
  • password: Dieses Element enthält das Passwort des etracker Accounts.

Beispiel:

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

Im Firefox können Sie auch Modify Headers (https://addons.mozilla.org/en-us/firefox/addon/modify-headers/) verwenden, um diese Header mitzusenden.

5 Abruf der zur Verfügung stehenden Reports

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

Mit diesem Abruf bekommen Sie eine Liste aller Reports (auch eigener), die über die Schnittstelle zur Verfügung stehen. Die Rückgabe ist ein JSON-Objekt bestehend aus Schlüssel-Wert-Paare, in denen die Schlüssel Report-Ids und die Werte Reportnamen sind:

{  "EAPage":"Seiten",  "CCOverview":"Übersicht",  "72":"Mein individueller Report",  }

Report-Daten können mit den numerischen oder alphabetischen Report-Ids aufgerufen werden.

6 Abruf von Report- und Metadaten sowie Request-Parametern

Die Abfragen an der etacker Report REST API werden wie folgt aufgebaut:

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

Die verfügbaren Services sind:

ServiceBeschreibung
InfoGibt allgemeine Informationen und metaDaten zu einem Report zurück
metaDataGibt Informationen zu Typen und Namen der Spalten einer bestimmten Report-Abfrage zurück
dataGibt die Daten des entsprechenden Reports im JSON-Format zurück
data.csvGibt die Daten des entsprechenden Reports im CSV-Format zurück

6.1 Definition von etracker Reports

Die etracker Reports können als dynamische Tabellen oder sog. Data Cubes verstanden werden. Sie bestehen aus Attributen (attributes) und Kennzahlen (key figures). In der Literatur werden auch die Begriffe Dimensionen (für Attribute) und Maße (für Kennzahlen) verwendet.

Attribute beinhalten nominale oder kategorische Werte, die keine Zahlen sind, und stellen die Eigenschaften von Benutzerinteraktionen dar. Typische Attributwerte sind Namen (z. B. ‚Startseite‘ oder ‚Damenbekleidung‘), Kategorien (z. B. ‚Kunde‘, ’nicht Kunde‘) oder Zeiten (z .B. ‚2016-01-25‘ oder ‚9 Uhr‘). Manche Attributwerte haben eine natürliche Reihenfolge (z .B. die Zeiten), die meisten können aber nicht sinnvoll bzw. nur alphabetisch sortiert werden.

Wenn aus drei Attributen jeweils ein Wert selektiert werden soll, dann sprechen wir von einer Attributwertkombination oder Ausprägung. Seien z. B. die Attribute ‚Seitenname‘, ‚Land‘ und ‚Betriebssystem‘ gegeben, dann wären die Werte ‚Startseite‘, ‚Deutschland‘ und ‚Windows‘ eine Attributwertkombination und ‚Startseite‘, ‚Österreich‘, ‚Windows‘ eine weitere Attributwertkombination.

Kennzahlen beinhalten numerische Werte, die sortiert und aggregiert werden können. Kennzahlen werden immer in aggregierter Fom von der REST-API zurückgegeben. Die Aggregationsmethode hängt von der Kennzahl ab. Bei der Kennzahl ‚Bounce Rate‘ wird bspw. gemittelt. Bei der Kennzahl ‚Besucher‘ wird dagegen summiert.

Jede Abfrage eines Reports über die REST API gibt eine Tabelle zurück, die eine bestimmte aggregierte Ansicht wiedergibt. Jede Kennzahl wird für jede vohandene Attributwertkombination aggregiert. Jede Zeile in der Tabelle besteht dann aus einer Attributwertkombination gefolgt von den dazugehöigen aggregierten Kennzahlen. Zwei Zeilen einer solchen Tabelle könnten wie folgt aussehen:

Attribute  Kennzahlen 
SeitennameLandBetriebssystemBesucherBounce-Rate
StartseiteDeutschalndWindows52330,45%
StartseiteÖsterreichWindows5735,09%

Die Attributwertkombination und Kennzahlen der zweiten Zeile kann wie folgt interpretiert werden: Es gab 57 Besucher auf der Startseite aus Österreich mit dem Betriebssystem Windows und 35,09% von ihnen haben nur eine Seite aufgerufen.

6.2 Abfrage von Report Informationen

Der Abruf der Informationen und Metadaten des Reports ‚Gerät‘ erfolgt mit der folgenden Abfrage:

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

Die Rückgabe ist ein JSON-Array mit einem Element und hat folgende Struktur:
 {  "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": "Besuche",  "type": "integer",  "sortable": true  },   ]  "views": [  {  "view_id": "24",  "name": "Test Konfiguration",  "tm": "1477324586",  "access": "this_user",  "is_default": false  },  }

Das Rückgabe-Objekt beinhaltet vier Unterelemente:

  1. Ein report-Objekt mit allgemeinen Informationen wie das Datum, an dem ein Report erzeugt wurde.
  2. Ein attributes-Array mit Metadaten zu jedem Attribut im Report.
  3. Ein key-figures-Array mit Metadaten zu jeder Kennzahl im Report.
  4. Ein views-Array mit Metadaten zu jeder von Benutzern definierten Ansicht des Reports.

Die Arrays zu den Attributen und Kennzahlen beinhalten Objekte mit den folgenden Daten für jedes Attribut und jede Kennzahl:

  1. Das id für die Kommunikation mit der REST API.
  2. Eine für Menschen lesbare Bezeichnung (label). Die Sprache der Bezeichnungen hängt vom im Header verwendeten Account- bzw. von der Subuser-ID ab und kann über die entsprechenden Einstellungen in der etracker Applikation geändert werden.
  3. Der Datentyp (type) der Werte in der Spalte.
  4. Ein Boolean-Wert (‚true‘ oder ‚false‘), der angibt, ob der Report nach dem Attribut oder der Kennzahl sortiert werden kann.

Die Datentypen, die in etracker Reports vorkommen können, werden in der folgenden Tabelle beschrieben. Bei den Beispieldaten handelt es sich um Daten wie sie von der REST API zurückgegeben werden.

DatentypBeschreibungBeispiel
attributeAttribute beinhalten Zeichenketten"organisch"
attributeDateEin Datum als Zeichenkette"2016-01-15"
integerGanze Zahl132
floatGleitkommazahl2.316757394
currencyGleitkommazahl mit zwei Nachkommastellen50321.45
percentProzentsatz: Gleitkommazahl zwischen 0 und 10034.501120345
relPercentageRelativer Prozentsatz: Gleitkommazahl zwischen 0 und 10.573944096
staytimeDauer in Sekunden: Die Nachkomastellen sind Sekundenbruchteile239.355444
dateEin Datum2016-01-15
nullIds und Statusangaben, die weder Attribute noch Kennzahlen sind.

Ansichten können von jedem Benutzer zu jedem Report in der etracker Applikation interaktiv definiert und gespeichert werden. Das views-Array enthält die folgenden Daten zu jeder von Benutzern definierten Ansicht:

  1. Die view_id für die Kommunikation mit der REST-API.
  2. Der von Benutzern vergebene eindeutige Name (name).
  3. Weitere Metadaten zur Ansicht (z. B. Zeitpunkt der Erstellung).

6.3 Abruf von Report Daten

Der Abruf der Daten des Reports ‚Gerät‘ erfolgt mit folgender Abfrage (eine Datenabfrage ohne Parameter ist möglich, wird aber nicht empfohlen):

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

Diese Abfrage gibt Daten im JSON-Format zurück. Für CSV-Daten muss lediglich ‚data.csv‘ anstatt ‚data‘ am Ende der URI stehen. Bis auf das Rückgabeformat sind CSV- und JSON-Abfragen identisch. In diesem Abschnitt werden wir daher nur den Fall JSON beschreiben.

Die Rückgabedaten haben etwa das folgende Fomat:

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

Die Rückgabe ist ein JSON-Array von maximal 11 Arrays, da das Parameter-Limit gleich 10 gesetzt wurde. Jedes Array stellt einen Datensatz oder eine Zeile in der Rückgabe-Tabelle dar. Das erste Array ist immer die Zeile ‚Gesamt‘, in der die Kennzahlen über alle Attributwertkombinationen hinweg aggregiert wurden. Die anderen Arrays sind Attributwertkombinationen mit den entsprechenden aggregierten Kennzahlen. Da keine Sortiervorgaben in den Parametern angegeben wurden, ist die Reihenfolge der Zeilen beliebig. Jede Zeile beginnt mit einer Liste der Ids der Attributwerte, die für die Attributwertkombination verwendet wurden. Jeder Attributwert hat eine Id, die verwendet werden muss, wenn ein bestimmter Attributwert über die REST-API referenziert werden soll. Die Attributwert-Ids können für die gleichen Attributwerte von etracker Account zu etracker Account variieren. Innerhalb eines Accounts sind sie aber immer eindeutig.

Das zweite Element in jeder Zeile ist eine Kennzeichnung: ‚=S‘ für die Zeile ‚Gesamt‘ und ‚=0‘ für alle anderen Zeilen. Es folgen die Attributwerte der Attributkombination in der gleichen Reihenfolge wie in den Report-Informationen und dann die Kennzahlgrößen der Kennzahlen ebenfalls in der gleichen Reihenfolge wie in den Report-Informationen.

Das obige Beispiel dient der Einführung und stellt keine sinnvolle Nutzung der etracker REST-API dar. Um die REST-API sinnvoll zu verwenden, müssen der gewünschte Datenumfang und die Anordnung mithilfe von Parametern eingegrenzt werden.

6.4 Abruf von abfragespezifischen Report Metadaten

Zu jeder Daten-Abfrage eines Reports können die entsprechenden abfragespezifischen Metadaten abgerufen werden. Um die Metadaten zur obigen Abfrage zu sehen, muss lediglich ‚data‘ durch ‚metaData‘ ersetzt werden. Dabei sollten die Parameter beibehalten werden.

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

Diese Abfrage gibt ein JSON-Array mit einem Eintrag pro Spalte in der dazugehörigen Datenabfrage zurück. Die ersten beiden Einträge haben die Ids ‚id‘ und ‚tree_status‘ und den Typ ’null‘. Sie entsprechen den ersten beiden oben beschriebenen Spalten, die weder Attribute noch Kennzahlen sind.

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

7 Basis-Parameter der Report API

Im Folgenden werden die Basis-Parameter der Report API beschrieben. Es folgen dann Beispiele zur Erläuterung der Parameter.

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

Die folgende Abfrage verwendet die obigen Parameter, um gezielter bei der Abfrage des Reports ‚Geräte‘ vorzugehen.

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

Die Parameter wurden wie folgt gesetzt:

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

Damit werden die in Januar 2016 erfassten Daten nach der Kennzahlspalte ‚Besuche‘ absteigend sortiert und die ersten 10 Zeilen zusammen mit der Zeile ‚Gesamt‘ zurückgegeben. Falls weitere Daten erwünscht sind, können offset und limit progressiv erhöht werden, bis keine Daten mehr zurückgegeben werden. Die nächsten 10 Datensätzen wurden z. B. wie folgt abgefragt:

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 Einschränkung von Attributen und Kennzahlen

Die etracker REST API bietet neben den Basis-Parametern auch weitere Parameter, um die Rückgabe-Tabelle genauer zu spezifizieren. Unter Verwendung der Basis-Parameter werden Attributwertkombinationen immer mit Werten aus allen vorhandenen Attributen gebildet. Meist interessieren aber nur Kombinationen aus einem Teil der vorhandenen Attribute. Des Weiteren sind nicht alle Kennzahlen für bestimmte Analysen notwendig.

Es ist auch möglich, bestimmte Attributwerte mithilfe von Attributwert-Ids zu fixieren oder zu ignorieren. Dann werden nur die Attributwertkombinationen zurückgegeben, die die fixierten Attributwerte enthalten bzw. die ignorierten Attributwerten nicht enthalten.

Mit den folgenden beiden Parametern können die Attribute und Kennzahlen eingeschränkt werden.

ParameterAttributes
BeschreibungEs werden Attributwertkombinationen nur aus den angegebenen Attributen gebildet. Die Werte in den Rückgabe-Zeilen erscheinen in der angegebenen Reihenfolge.

Falls Wert-Filter angegeben werden, werden nur die Attributwertkombinationen gebildet, die die fixierten Werte enthalten oder die ignorierten Werte nicht enthalten.
Zulässige WerteIm einfachsten Fall eine mit Kommas getrennte Liste von Attribut-Ids. Die Ids können den Metadaten des Reports entnommen werden.

Hinter jeder Attribut-Id kann eine mit Semikolons getrennte Liste von Attributwert-Ids in Klammern angegeben werden. Die Attributwert-Ids können dem ersten Eintrag in den Tabellen-Zeilen entnommen werden.

Ein Minuszeichen darf vor jeder Attibutwert-Id hinzugefügt werden, um alle Attributwert-Ids in der List zu ignorieren.
BeispieleEinfacher Fall:
'device_type,geo_country,geo_region'

Attributwerte werden für device_type fixiert:
'device_type(3257;2269),geo_country,geo_region'

Attributwerte werden für device_type fixiert und geo_country ignoriert:
'device_type(3257;2269),geo_country(-10;-324),geo_region'
ParameterFigures
BeschreibungEs werden nur die angegebenen Kennzahlen berechnet und zurück- gegeben. Die Werte in den Rückgabe-Zeilen erscheinen in der angegebenen Reihenfolge.
Zulässige WerteKomma-separierte Liste von Kennzahl-Ids. Die Ids können den Metadaten des Reports entnommen werden. Falls eine Kennzahl zum Sortieren angegeben wurde (siehe sortColumn), dann muss die Kennzahl in der Liste enthalten sein.
Beispiel'unique_visitors,page_impressions,pi_per_visit'

Die folgende Abfrage verdeutlicht die Nutzung des Parameters ‚attributes‘.

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

Die Parameter wurden wie folgt gesetzt:

  • 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

Der Attributwert ‚Desktop‘ hat die ID 137. Die Abfrage gibt also nur die Attributwertkombinationen der Attribute Gerätetyp, Land und Region zurück, für die der Gerätetyp ‚Desktop‘ war. Es werden auch nur Daten von Januar 2016 berücksichtigt und die Zeilen werden nach ‚Besuche‘ sortiert, bevor sie zurückgegeben werden. Nur die ersten 10 Zeilen (und die Zeile ‚Gesamt‘) werden zurückgegeben.

Der Attributwert ‚Germany‘ hat die ID 1086 und der Attributwert ‚Austria‘ hat die ID 1092. Um diese beiden Attributwerte zu ignorieren, kann die Abfrage wie folgt abgeändert werden:

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

Damit werden nur Attributwertkombinationen gebildet, die ‚Desktop‘ enthalten und ‚Germany‘ und ‚Austria‘ nicht enthalten. Alle andere Vorgaben sind gleich geblieben.

Bisher wurden alle Kennzahlen ausgegeben. In der folgenden Abfrage werden sie eingeschränkt:

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

Der Parameter ‚figures‘ wurde hinzugefügt:

  • figures=unique_visits,page_impressions,pi_per_visit

Damit werden nur die Werte der drei genannten Kennzahlen berechnet und in der angegebenen Reihenfolge ausgegeben. Da die Kennzahl ‚unique_visits‘ zum Sortieren benutzt wurde, muss sie in der Liste enthalten sein.

9 Dimensionsfilter

In etracker Analytics können die Datensätze eines Reports auf Basis eines gewünschten Wertes innerhalb einer aktivierten Dimension gefiltert werden. Der Parameter attributeFilter, der jedoch nur auf Segmente und Dimensionen angewendet werden kann, erlaubt es, die Daten eines Reports auch mittels REST API gefiltert abzurufen. Der Aufbau ist wie folgt:

ParameterattributeFilter
BeschreibungEnthält die Filtereigenschaften in Form eines JSONArrays.
Aufbau JSONArray[
{
"input":"SUCHBEGRIFF",
"type":"contains",
"attributeId":"ATTRIBUT_ID",
"filterType":"simple"
}
]
Beschreibung JSONArray• input: Enthält den substring, der in der Dimension bzw. in dem Segment enthalten sein soll.
• attributId: Dimension bzw. Segment, welche(s) gefiltert werden soll.
• type und filterType sind nicht anzupassen
Erlaubte ZeichenFür input sind die folgenden Zeichen erlaubt:
• Sämtliche Buchstaben sämtlicher Sprachen, die im Unicode enthalten sind
• alle Ziffern: 0 - 9
• Sonderzeichen: §,%,€,@,',',.,!,&,+,-,_,|,[,]
• Leerzeichen
Hinweis:
Die korrekte Nutzung erfordert eine URL-Encodierung des JSONArrays.
URL-encodiertes Beispiel:
%5B%7B%22input%22%3A%22SUCHBEGRIFF%22%2C%22type%22%3A%22contains%22%2C%22attributeId%22%3A%22ATTRIBUT_ID%22%2C%22filterType%22%3A%22simple%22%7D%5D

Das nachfolgende Beispiel veranschaulicht die Nutzung des Parameters in einer Abfrage:

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

Soll innerhalb von mehreren Dimensionen oder Segmenten gefiltert werden, sind die weiteren Einträge dem JSONArray entsprechend hinzuzufügen:

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

10 Nutzung von Ansichten

In der etracker Applikation ist es möglich, Ansichten auf bestimmten Reports interaktiv zu definieren und zu speichern. Die Daten zu diesen Ansichten können auch über die REST API aufgerufen werden. In der folgenden Abfrage werden die Daten zur Ansicht mit Id ‚4‘ im Report ‚Geräte‘ aufgerufen:

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

ParameterViewid
BeschreibungEs werden nur die Daten zurückgegeben, die zu der angegebenen voreingestellten Ansicht gehören
Zulässige WerteGültige Ansicht-Ids. Die Ansichten zu einem Report erscheinen in den Report-Informationen, die mit der Abfrage /info abgerufen werden können.
Beispiel4 oder 32

Der Parameter ‚viewid‘ kann auch mit allen anderen Parametern kombiniert werden, um die Rückgabe einzugrenzen.

11 Fehlermeldungen

Bei fehlerhaften Abfragen werden keine Daten sondern detaillierte Fehlermeldungen zurückgegeben. Die Fehlermeldungen haben immer das folgende Format:

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

Die Rückgabe ist ein JSON-Objekt mit zwei Eigenschaften:

  • Eine Fehlernummer (‚errorCode‘), die für eventuelle Rückfragen an etracker verwendet werden kann, und
  • eine Nachricht (‚msg‘), die Hinweise auf die Fehlerursache beinhaltet.

In bestimmten Fällen werden aus technischen Gründen keine Fehlermeldungen sondern lediglich ein leeres JSON-Array zurückgegeben. Das tritt meistens dann auf, wenn die übergebenen Parameterwerte problematisch sind. In diesen Fällen ist es hilfreich, zunächst die folgenden Fehlerquellen zu überprüfen:

  • Sind alle Attribut- bzw. Kennzahl-Ids korrekt geschrieben?
  • Ist die Kennzahl-Id für sortColumn korrekt geschrieben?
  • Ist der Wert von sortOrder ‚1‘ oder ‚2‘?

12 Code-Beispiele

In den folgenden Code-Beispielen wird eine Abfrage des Reports ‚Seiten‘ mit Id ‚EAPage‘ durchgeführt. Für die Abfrage werden die folgenden Parameter verwendet:

  • 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

Die folgenden (ungültigen) Daten werden für die Authentifizierung verwendet. Diese Werte müssten durch gültige ersetzt werden, damit die Beispiele auch funktionieren.

  • Email: falsch@etracker.com
  • Developer-Token: 1234567890token
  • Account-Id: 012345
  • Passwort: einfach123

12.1 Kommandozeilen-Tool curl

curl -G \
   --header "X-ET-email: falsch@etracker.com" \
   --header "X-ET-developerToken: 1234567890token" \
   --header "X-ET-accountId: 012345" \
   --header "X-ET-password: einfach123" \
   "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

Der Paramter ‚-G‘ erzwingt eine GET-Abfrage. Damit kann ‚-d‘ für die Angabe von URL-Parametern verwendet werden.

12.2 PHP

<?php $opts = array(   'http'=>array(     'method' => "GET",     'header' =>        "X-ET-email: falsch@etracker.com\r\n" .       "X-ET-developerToken: 1234567890token\r\n".        "X-ET-accountId: 012345\r\n".        "X-ET-password: einfach123\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. Funktion und Zweck der Targeting API
      2. Zugang zur Targeting API
      3. Response
        1. Response-Aufbau
        2. Response-Attribute
      4. Fehlermeldungen
      5. Darstellung von Smart Messages mit der Targeting API

1 Funktion und Zweck der Targeting API

Die Targeting API dient der Personalisierung von Webseiten in Echtzeit. Die Personalisierung findet  in dem Moment statt, wenn der Besucher auf die Webseite kommt.

Bei der Targeting API handelt es sich um einen REST-Service, der sich in Content Management- oder Shop-Systeme integrieren lässt.

Mit Hilfe der übertragenen Daten können je nach Kundeninteresse automatisch Webseiteninhalte dynamisch generiert oder ausgetauscht werden. Auf diese Weise hilft die etracker Targeting API nicht nur dabei, die User Experience zu verbessern, sondern auch die Konversionsrate und den Umsatz zu steigern.

2 Zugang zur Targeting API (TAPI)

Folgende Voraussetzungen müssen erfüllt sein, um die etracker Targeting API nutzen zu können:

      • Gewünschte Targeting-Daten müssen von etracker erfasst und über Events (mittels eCommerce API) oder Bestellparameter beim Seitenaufruf übergeben werden.
        Bestellungen, Product Performance Events (‚Produkt gesehen‘, ‚Produkt in Warenkorb gelegt‘ und/oder ‚Produkt bestellt‘).
      • Die gewünschten Targeting-Daten (Attribute) sind von etracker konfiguriert.

Um die Schnittstelle aufzurufen, schicken Sie einen Request an die URI der Targeting API. Sie können die Schnittstelle im Frontend mittels JavaScript oder im Backend über HTTPS aufrufen. Pro Session genügt eine Abfrage (zu Beginn der Session).

      • Der Request an die Schnittstelle muss zwei Parameter enthalten:
        et
        übergibt den Account-Schlüssel 2, den Sie in der etracker Applikation unter Einstellung > Setup/Tracking Code finden. Der Account-Schlüssel 2 ist Base64 encodiert.
      • _et_coid
        übergibt den First-Party Cookie aus der Domain des etracker Kunden.
Hinweis:
Sie können die _et_coid auch per JavaScript ermitteln.
Für Testzwecke können Sie die Cookie-ID _et_coid per Firebug aus der Webseite entnehmen.
https://ws.etracker.com/api/rest/v2/realtime/user?et=<Account-Schlüssel>&_et_coid=<CookieId>

Beispiel:

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

3 Response

Hinweis:
Wenn ein Besucher eine Webseite das erste Mal besucht, kann es aus technischen Gründen bis zu einer halben Stunde dauern, bis die Targeting API ein neues Nutzerprofil zur Verfügung stellt.

3.1 Response-Aufbau

In ihrem Response stellt die Schnittstelle Nutzerprofildaten bereit. Der Response wird im JSON-Format zur Verfügung gestellt und zwar in Tabellenform mit n Spalten für die Attributnamen (Header) und n Zeilen für die Attributwerte (Data). Die Anzahl der Zeilen ist abhängig von der Größe des Nutzerprofils.

Die JSON-Response-Struktur sieht aus wie folgt:

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

Beispiel mit Standardattributen:

{   "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-Attribute

Über die konfigurierten Attribute werden die Nutzerprofildaten bereitgestellt. etracker konfiguriert die Attribute beim Kauf des Produktes nach den Wünschen des Kunden. Zur Zeit sind maximal zehn Attribute erlaubt.

Hinweis:
Es existieren zur Zeit zehn Standardattribute, die auch in den Testing & Targeting Reports ausgewertet werden.

etracker stellt folgende Attribute bereit:

3.2.1 Allgemeine Attribute

AttributBesuchshäufigkeit
Attributnamevisit_count_seg
BeschreibungStandardattribut mit Kategorien für die Anzahl der bisherigen Besuche.
DatentypString
Attributwerte (Beispiel)″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_01″
(Nur ein Besuch) (Standardwert)
″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_02″
(Niedrig = 2 Besuche)
″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_03″
(Mittel = 3-4 Besuche)
″STC_CC_ATTR_VALUE_VISIT_COUNT_SEG_04″
(Hoch = 5 und mehr Besuche)

Um die folgenden Attribute auszuwerten, muss der UserAgent vom Client Request mit dem http-Header ‚User-Agent‘ an die TAPI übermittelt werden.

Beispiel Übermittlung Client User-Agent
User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0

AttributBrowser
Attributnamedevice_browser
BeschreibungName des Browsers, der in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)″Firefox″

 

AttributBrowser Version
Attributnamedevice_browser_version
BeschreibungVersion des Browsers, der in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)″37″

 

AttributHersteller
Attributnamedevice_manufacturer
BeschreibungHersteller des Gerätes, das in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)″Apple″

 

AttributGerätebezeichnung
Attributnamedevice_model
BeschreibungBezeichnung des Gerätes, das in der aktuellen Session auf die Website zugegriffen hat. Wird nur für mobile Geräte ausgegeben.
DatentypString
Attributwerte (Beispiel)″iPad″

 

AttributBetriebssystem
Attributnamedevice_os
BeschreibungBetriebssystem, das in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)″Windows″

 

AttributBetriebssystemversion
Attributnamedevice_os_version
BeschreibungVersion des Betriebssystems, das in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)″7″

 

AttributGerätetyp
Attributnamedevice_type
BeschreibungStandardattribut, das den Typ des Gerätes beschreibt, das in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte″STR_CC_ATTR_VALUE_DEVICE_TYPE_DESKTOP″
(Wert für device_type = Desktop)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_MOBILE_PHONE″
(Wert für device_type = Handy)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_TABLET″
(Wert für device_type = Tablet)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_OTHERS″
(Wert für device_type = Andere)

 

AttributGerätetyp (Detail)
Attributnamedevice_type_detail
BeschreibungStandardattribut, das den Gerätetyp, wenn möglich, genauer bezeichnet.
DatentypString
Attributwerte″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_GAME_CONSOLE″
(Wert für device_type_detail = Spielekonsole)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_NON_SMARTPHONE″
(Wert für device_type_detail = Non-Smartphone)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_SMARTTV″
(Wert für device_type_detail = SmartTV)
″STR_CC_ATTR_VALUE_DEVICE_TYPE_DETAIL_SMARTPHONE″
(Wert für device_type_detail = Smartphone)

3.2.2 Geo-Attribute

Die Targeting API (TAPI) bietet die Möglichkeit, den Standort eines Webseitenbesuchers ohne die Lokalisierungs-API des Browers zu verwenden. Mittels eines GeoIP-Auflösungsdienstes erfolgt eine Zurückverfolgung bis zum Internetprovider. Die TAPI liefert Informationen zum Standort des Besuchers in Bezug auf Landes-, Bundeslands- und Stadtebene.

Um die folgenden Attribute auszuwerten muss die Client IP vom Client Request mit dem http-Header ‚X-Forwarded-For‘ an die TAPI übermittelt werden.

Beispiel Übermittlung Client IP
X-Forwarded-For: 31.19.38.145

AttributLand
Attributnamegeolocation_country
BeschreibungLand, aus dem der Besucher in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)Deutschland

 

AttributRegion
Attributnamegeolocation_state
BeschreibungRegion, aus der der Besucher in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)Hamburg

 

AttributStadt
Attributnamegeolocation_city
BeschreibungStadt, aus der der Besucher in der aktuellen Session auf die Website zugegriffen hat.
DatentypString
Attributwerte (Beispiel)Hamburg

3.2.3 eCommerce-Attribute

Hinweis:
Um die eCommerce-Attribute nutzen zu können, muss eine erweiterte Datenerfassung in die zu messende Website integriert werden. Nur so können Events wie z. B. ‚Produkt gesehen‘, ‚Produkt in den Warenkorb gelegt‘ oder ‚Produkt bestellt‘ über die eCommerce API an etracker übergeben werden.

Profilinformationen

AttributKunden-Id
Attributnamecustomer_id
BeschreibungKundennummer, eindeutige ID eines Kunden
DatentypString
Attributwerte (Beispiel)″345565″

 

AttributKundengruppe
Attributnamecustomer_group
BeschreibungGruppe, zu der ein Kunde lt. eCommerce API gehört
DatentypString
Attributwerte (Beispiel)″Stammkunde″

 

AttributKäufertyp
Attributnamepurchaser_type
BeschreibungStandardattribut zur Kategorisierung des Käufers entsprechend der ABC-Analyse
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_PURCHASER_TYPE_1″
(Kein Kauf) (Standardwert)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_2″
(Nur ein Kauf)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_3″
(C = Unwichtiger Kunde)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_4″
(B = Wichtiger Kunde)
″STC_CC_ATTR_VALUE_PURCHASER_TYPE_5″
(A = Sehr wichtiger Kunde)

 

AttributScore Value
Attributennamescore_values
BeschreibungScore ist eine Ganzzahl, die die Relevanz des Interesses an einem Produkt beschreibt. Die Übergabe erfolgt über ein optionales Property 'score' im Product-Objekt der eCommerce API.
Beispiel:
Sie möchten Besucher, die bereits Interesse an einem bestimmten Produkt gezeigt haben, ein besonderes Angebot unterbreiten. Das Angebot soll nur den Besuchern ausgepielt werden, welche bereits in einem bestimmten Umfang Interesse an diesem Produkt und im Produktbereich gezeigt haben. Das Interesse kann durch Score-Werte, die auf den besuchten Produktseiten oder Produktbereichsseiten vergeben werden, abgebildet werden. Als Interessierter an einem Produkt wird dann der Besucher betrachtet, der eine aufaddierte Score in einem bestimmten Zeitraum (z. B. in den letzten 4 Wochen) für ein Produkt gesammelt hat.
DatentypArray mit Objekten.
Innerhalb der Objekte gibt es den Datentyp 'String'
(JSON Property ''product_name'')
und den Datentyp 'Number'
(JSON Properties 'accumulated_value_last_7_days',' accumulated_value_last_4_weeks',' accumulated_value_last
'und 'number_of_values')
Attributwerte[
{
"Weisse Schokolade": {
"values": [{
"accumulated_value": 1000
}, {
"accumulated_value_last_7_days": 100
}, {
"accumulated_value_last_4_weeks": 900
}, {
"accumulated_value_last": 100
}],
"number_of_values": 3
}
},
...
}
]

Bestellinformationen

AttributErster Lead
Attributnamelead_first_tm
BeschreibungZeitpunkt der ersten Bestellung (Lead)
Datentyp/MemberMillisekunden-Timestamp, der angibt, wann der Lead auftrat
Attributwerte (Beispiel)″1400592736149400″

 

AttributErster Sale
Attributnamesale_first_tm
BeschreibungZeitpunkt des ersten Kaufs (Sale)
Datentyp/MemberMillisekunden-Timestamp, der angibt, wann der Sale auftrat
Attributwerte (Beispiel)″1400592736149400″

 

AttributLetzter Lead
Attributnamelead_last_tm
BeschreibungZeitpunkt der letzten Bestellung (Lead).
Datentyp/MemberMillisekunden-Timestamp, der angibt, wann der Lead auftrat
Attributwerte (Beispiel)″1400592736149400″

 

AttributLetzter Sale
Attributnamesale_last_tm
BeschreibungZeitpunkt des letzten Kaufs (Sale)
Datentyp/MemberMillisekunden-Timestamp, der angibt, wann der Sale auftrat
Attributwerte (Beispiel)″1400592736149400″

 

AttributZeit seit letzter Bestellung
Attributnametime_since_last_order_segment
BeschreibungStandardattribut zur Kategorisierung nach Zeitintervallen zwischen Bestellungen
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_01″
(Keine Bestellung) (Standardwert)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_02″
(1-30 Tage)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_03″
(31-90 Tage)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_04″
(91 Tage - 12 Monate)
″STC_CC_ATTR_VALUE_TIME_SINCE_LAST_ORDER_SEG_05″
(Mehr als 12 Monate)

 

AttributAnzahl Leads
Attributnamelead_number_of_orders
BeschreibungAnzahl von Bestellungen (Leads) in einem festgelegten Zeitraum
DatentypNumber
Attributwerte (Beispiel)″16″

 

AttributAnzahl Sales
Attributnamesale_number_of_orders
BeschreibungAnzahl von Käufen (Sales) in einem festgelegten Zeitraum
DatentypNumber
Attributwerte (Beispiel)″12″

 

AttributSumme Leads
Attributnamelead_sum_order_price
BeschreibungWarenwert der Bestellung (Lead) in EURO Cents
DatentypNumber
Attributwerte (Beispiel)″120192″

 

AttributSumme Sale
Attributnamesale_sum_order_price
BeschreibungWarenwert des Kaufs (Sale) in EURO Cents
DatentypNumber
Attributwerte (Beispiel)″100190″

 

AttributZeit zwischen Leads
Attributnamelead_avg_time_between_orders
BeschreibungDurchschnittlicher Abstand zwischen den Bestellungen (Leads) in Millisekunden
DatentypNumber
Attributwerte (Beispiel)″120102″

 

AttributZeit zwischen Sales
Attributnamesale_avg_time_between_orders
BeschreibungDurchschnittlicher Abstand zwischen den Käufen (Sales) in Millisekunden
DatentypNumber
Attributwerte (Beispiel)″16036865125″

 

AttributProduktmenge Lead
Attributnamelead_total_number_of_articles
BeschreibungGesamtstückzahl in der Bestellung (Lead)
DatentypNumber
Attributwerte (Beispiel)″40″

 

AttributProduktmenge Sale
Attributnamesale_total_number_of_articles
BeschreibungGesamtstückzahl des Kaufs (Sale)
DatentypNumber
Attributwerte (Beispiel)″16″

 

AttributDurchschnittlicher Bestellwert
Attributnameavg_order_value_seg
BeschreibungStandardattribut, das die Höhe durchschnittlicher Bestellwerte in EURO erfasst
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_AVG_ORDER_VALUE_SEG_01″
(0-10) (Standardwert)
″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)

Produktinformationen

Attribute zu ProduktkategorienTop 10-Produktkategorien „Warenkorb“
Top 10-Produktkategorien „Gekauft“
Top 10-Produktkategorien „Gesehen“
Attributnamebasket_products_categories
sale_bought_products_categories
viewed_products_categories
BeschreibungTop 10-Liste von Produktkategorien, die angibt, aus welchen Produktkategorien
- die meisten Produkte in den Warenkorb gelegt wurden,
- die meisten Produkte gekauft wurden,
- die meisten Produkte angeschaut wurden.

Alle Listen sind gleich aufgebaut. Die JSON Property 'rank' gibt den Platz in der Top 10-Liste an, wobei „1“ der beste Platz ist. Der Timestamp zeigt an, wann es zuletzt Änderungen gab, der Counter zeigt an, wie oft die Produktkategorie aufgerufen wurde.
DatentypArray mit Objekten.
Innerhalb der Objekte gibt es den Datentyp 'String'
(JSON Property 'category_name')
und den Datentyp 'Number'
(JSON Properties 'timestamp','rank' und 'counter')
Attributwerte (Beispiel)[


{ "timestamp": "1416921576121300", "rank": "3", "category_name": "Sonstiges", "counter": "3" }
,
{ "timestamp": "1416921576121300", "rank": "1", "category_name": "Geometrische Körper", "counter": "9" }
,
{ "timestamp": "1416921567909000", "rank": "2", "category_name": "Lebensmittel", "counter": "2" }


]

(Die Produktkategorie "Geometrische Körper" hat in Bezug auf das betrachtete Attribut den besten Platz erreicht. Für das Attribut "basket_products_categories" würde dies bedeuten, dass aus der Kategorie "Geometrische Körper" die meisten Produkte in den Warenkorb gelegt wurden.)

 

Produkt-AttributeTop 10-Produkte „Warenkorb“
Top 10-Produkte „Gekauft“
Top 10-Produkte „Gesehen“
Attributnamebasket_products
sale_bought_products
viewed_products
BeschreibungTop 10-Liste von Produkten, die angibt, welche Produkte
- am häufigsten in den Warenkorb gelegt wurden,
- am häufigsten gekauft wurden,
- am häufigsten angeschaut wurden.

Alle Listen sind gleich aufgebaut. Die JSON Property „rank“ gibt den Platz in der Top 10-Liste an, wobei „1“ der beste Platz ist. Der Timestamp zeigt an, wann es zuletzt Änderungen gab, der Counter zeigt an, wie oft das Produkt aufgerufen wurde.
DatentypArray mit Objekten.
Innerhalb der Objekte gibt es den Datentyp 'String'
(JSON Properties 'category_<0-3>' und 'product_name')
und den Datentyp 'Number'
(JSON Properties 'timestamp', 'rank' , 'product_id' und 'counter'
Attributwerte (Beispiel)[


{ "timestamp": "1416921567909000", "rank": "1", "product_id": "6450", "category_3": "lecker", "category_1": "Süßigkeiten", "counter": "1", "product_name": "weiße Schokolade", "category_2": "schokoladiges", "category_0": "Lebensmittel" }
,

{ "timestamp": "1416921567909000", "rank": "2", "product_id": "6451", "category_3": "lecker", "category_1": "Süßigkeiten", "counter": "1", "product_name": "Zartbitter Schokolade", "category_2": "schokoladiges", "category_0": "Lebensmittel"}


]

(Das Produkt „weiße Schokolade“ mit der ID „6450“ hat in Bezug auf das betrachtete Attribut den besten Platz erreicht. Für das Attribut „sale_bought_products“ würde dies bedeuten, dass die weiße Schokolade häufiger als andere Produkte verkauft wurde.)

3.2.4 Engagement & Lead Attribute

AttributZeit seit letztem Besuch
Attributnamefrequency_seg
BeschreibungStandardattribut, das Zeitintervalle zwischen Besuchen beschreibt
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_FREQUENCY_SEG_01″
(Weniger als 1 Tag) (Standardwert)
″STC_CC_ATTR_VALUE_FREQUENCY_SEG _02″
(1-7 Tage)
″STC_CC_ATTR_VALUE_FREQUENCY_SEG _03″
(8-30 Tage)
″STC_CC_ATTR_VALUE_FREQUENCY_SEG _04″
(Mehr als 30 Tage)

 

AttributErster Besuch
Attributnameengagement_lifetime
BeschreibungZeitpunkt des ersten Besuchs
Datentyp/MemberMillisekunden-Timestamp, der angibt, wann der Besuch auftrat
Attributwerte (Beispiel)″1404217686586200″

 

AttributLetzter Besuch
Attributnameengagement_recency
BeschreibungZeitpunkt des letzten Besuchs
Datentyp/MemberMillisekunden-Timestamp, der angibt, wann der Besuch auftrat
Attributwerte (Beispiel)″1404480183492400″
Hinweis:
Um die folgende Top 10-Liste für Bereiche oder Seiten nutzen zu können, müssen die Parameter für Seitennamen und Bereiche im Parameterblock des Tracking Codes übergeben werden.
Attribute für FavoritenTop 10-Liste für Bereiche oder Seiten
Attributnameengagement_favorites_area,
engagement_favorites_page
BeschreibungTop 10-Liste, die angibt, welche Bereiche/Seiten am häufigsten besucht werden. Jeder Bereich/jede Seite hat einen Timestamp und einen Rank vom Typ Number. Der Timestamp zeigt an, wann es zuletzt Änderungen gab.
DatentypArray mit Objekten.
Innerhalb der Objekte gibt es den Datentyp 'String'
(JSON Properties 'page' und 'area')
und den Datentyp 'Number'
(JSON Properties 'timestamp' und 'rank')
Attributwerte
(Beispiel für Seitenfavoriten)
[
{
"timestamp": "1415627028457600",
"rank": "1",
"page": "dmexco"
},
{
"timestamp": "1415713855503100",
"rank": "3",
"page": "Index"
},
{
"timestamp": "1415713855436000",
"rank": "2",
"page": "Targeting Suite"
}
]
(Die Index-Seite hat den Rank 3)

 

AttributNewsletter-Abonnent
Attributnameis_newsletter_recipient
BeschreibungStandardattribut, das angibt, ob ein Besucher sich für den Newsletter registriert hat.
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_NEWSLETTER_1″
(Ja)
″STC_CC_ATTR_VALUE_NEWSLETTER_2″
(Nein) (Standardwert)

3.2.5 Statusattribute

AttributWiederkehrender Besucher
Attributnamevisitor_type
BeschreibungStandardattribut, das angibt, ob ein Besucher wiederkehrt (oder neu ist)
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_VISITOR_TYPE_1″
(Ja)
″STC_CC_ATTR_VALUE_VISITOR_TYPE_2″
(Nein) (Standardwert)

 

AttributKunde
Attributnamecustomer_type
BeschreibungStandardattribut, das angibt, ob ein Besucher Kunde ist
DatentypString
Attributwerte″STC_CC_ATTR_VALUE_CUSTOMER_TYPE_1″
(Ja)
″STC_CC_ATTR_VALUE_ CUSTOMER _TYPE_2″
(Nein) (Standardwert)

4 Fehlermeldungen

Error CodeHTTP Status CodeError MessageFehlermeldung
3504The request timed out.Timeout des Requests
4403The access to the requested resource has been denied.Zugang zur Ressource verweigert
5500An internal server error occurred.Interner Server-Fehler
10400The secure code is missing (parameter et).Account-Schlüssel fehlt (Parameter et)
11400The passed secure code is invalid.Account-Schlüssel nicht korrekt
12404Could not get a valid user mapping for the passed _et_coid cookie or _et_coid request parameter.Targeting API für Kunden nicht aktiviert
16400The requested API version is not supported.Nicht unterstützte API-Version
99500An unexpected error ocurred.Unerwarteter Fehler

5 Darstellung von Smart Messages mit der Targeting API

Auf GitHub stellt etracker ein jQuery-Plugin für die Darstellung von Smart Messages zur Verfügung. Mit dem Plugin jquery.smartmessage wird gezeigt wie Exit-Intent, Attention Grabber oder Greeter Messages implementiert werden können. Das Plugin fragt die Targeting API für Nutzerprofile ab und nutzt für das Tracking etracker Analytics.

c Remarketing Feed

1 Funktion und Zweck des etracker Remarketing Feed

Die Remarketing Feed-Schnittstelle zwischen etracker und E-Mail-Marketing-Systemen ist unidirektional. Das heißt, etracker Daten werden an das E-Mail-Marketing-System übergeben.

Die Datenübergabe findet in 5-Minuten-Intervallen statt. Jeder Datensatz wird stets nur einmal an das E-Mail-Marketing-System übertragen. Die Übertragung erfolgt über einen SFTP-Server, dessen Zugangsdaten der Anbieter des E-Mail-Marketing-Systems etracker zur Verfügung stellt. Das kurze Austauschintervall ermöglicht einen zeitnahen Versand von Erinnerungs-E-Mails.

Wenn die unten genannten Voraussetzungen erfüllt sind, können über den etracker Remarketing Feed Segmentdaten und Empfänger-IDs für Remarketing-Zwecke an E-Mail-Marketing-Systeme übergeben werden.

2 Voraussetzungen für den Einsatz des Remarketing Feeds

Folgende Voraussetzungen müssen erfüllt sein, um den etracker Remarketing Feed nutzen zu können:

      • Product Performance Events (Produkt gesehen, Produkt in Warenkorb gelegt und/oder Produkt bestellt) werden mittels etracker eCommerce API an etracker übertragen.
      • Empfänger-IDs werden über den Ziel-Link (Kampagnen-Link) aus E-Mailings an etracker übergeben. Damit das funktioniert, müssen die Kampagnen-Links in Mailings mit HTTP-GET Parametern angereichert werden.
        Dadurch kann einerseits der Erfolg der Mailings gemessen und andererseits können fortan Besuchsdaten Mailing-Empfängern zugeordnet werden.
      • SFTP-Austausch zwischen etracker und dem E-Mail-Marketing-System ist eingerichtet.
      • Kampagne mit Template(s) und Regelwerk ist im E-Mail-Marketing-System angelegt. D.h. das E-Mail-Marketing-System kann aus den Events von etracker passende Regeln bzw. Trigger ableiten.
      • Shopsystem bzw. CRM unterstützen je nach Kampagne (Promotion) persistente Warenkörbe sowie je nach Bedarf Rabatt-Gutscheine u.ä.

Die Übertragung von pseudonymisierten Empfänger-IDs und anderen Mailing-Informationen (Attributen) an etracker erfolgt über URL-Parameter, die an die Kampagnen-Links der Mailings angehängt werden.

Das minimale Attribut-Set besteht aus vier Attributen:

AttributParameterBeschreibung
Mediumetcc_medBeschreibt den Typ/Kanal einer Kampagne bzw. eine Traffic-Quelle (SEO, SEA, Type-In, Link/Referrer, Social Media, E-Mail).
Kampagneetcc_cmpDient zur Unterscheidung verschiedener Werbeaktionen, um diese besser vergleichen zu können. Im Fall von Mailings werden z. B. unterschiedliche Mailing-Namen oder Aussendungszeiten erfasst.
MailingIDetcc_midDie an etracker übergebene Mailing-ID (siehe oben).
EmpfängerIDetcc_ridEin per Mailing übergebener Parameter (HTTP-GET, etcc_rid), der einem Besucher entspricht (siehe oben).

Ein Link für E-Mail-Marketing könnte z. B. folgendermaßen aussehen:
www.zieldomain.de?etcc_med=E-Mail&etcc_cmp=Newsletter_Juni&etcc_mid=123&etcc_rid=12345

Die damit übertragene Empfänger-ID lautet hier 12345 und wird der Mailing-ID 123 zugeordnet.

Wir empfehlen, die Empfänger-ID mit allen System-E-Mails wie Bestellbestätigungen, Lieferhinweisen Newsletter-Registrierungsbestätigungen usw. mitzusenden, um eine möglichst vollständige Zuordnung von Empfängern über längere Zeiträume und unterschiedliche Geräte hinweg zu ermöglichen.

3 Segmente

Die Standardsegmente für eCommerce-Anwendungen sind Teilmengen von Analysedaten, die in Bezug auf eine Besucheraktion eine identische Merkmalsausprägung haben. Die betrachteten Besucheraktionen sind Produktansichten (productViews), Bestellungen (orders) sowie Warenkorbabbrüche (abandonments). Das Segment der Produktansichten enthält alle Besucher, die sich in einem bestimmten Zeitraum ein Produkt angesehen haben. Analog betrachten wir Bestellungen und Warenkorbabbrüche.

Die Erfassung der Besucheraktionen (Events) erfolgt mittels eCommerce API in etracker Analytics. Die eCommerce API muss entsprechend in die Website eingebaut sein.

4 Datenformat

Das Datenformat ist spezifisch für die eCommerce-Anwendungsfälle. Es werden UTF-8-Zeichensatz und URL-Kodierung genutzt.

Hinweis:
Aufgrund von Übertragungsfehlern und URL-Verfälschungen können Daten in Ausnahmen fehlerhaft sein.
Nr.NameDatentypBeschreibung
1dateStringDatum, zu dem die Aktion (das Event) stattgefunden hat. Im Falle eines productViews z. B. der Zeitpunkt, zu dem der Besucher sich das Produkt angesehen hat. Das Format ist YYYY-MM-DD HH:mm:SS. Zeitzone ist stets CET/CEST.
2etcc_ridStringEmpfänger-ID (HTTP-Parameter etcc_rid), die über den Kampagnen-Link einer E-Mail an etracker übergeben wurde. Entspricht einem Besucher.
3etcc_midInteger, 64 Bit, long Die an etracker übergebene Mailing-ID (HTTP-Parameter etcc_mid). Dieses Feld kann leer sein, wenn die Aktion (das Event) auf Grund von Übertragungsfehlern oder URL-Manipulationen keinem Mailing mehr zugeordnet werden kann.
In etracker kann eingestellt werden, ob die Zuordnung einer Konversion zu einer Kampagne nach dem Prinzip 'First Ad' (first click wins) oder 'Last Ad' (last click wins) erfolgt. Je nach Customer Journey ist das Feld der Mailing-ID mit einer Kampagne belegt (Konversion wird einem Mailing zugeordnet) oder leer.
4eventtypeStringTyp des Events. Es sind drei Standardwerte möglich: 'abandonment', 'order' oder 'productView'.
5contextStringProduktnummer (SKU Stock Keeping Unit).
6categoryStringDurch Schrägstriche getrennte Kategorie-Informationen, die über die eCommerce API an etracker übergeben wurden.
7pricefloatBrutto-Preis des Produktes.
8quantityInteger, 32 BitAnzahl der Produkte für diesen Eventtype (z. B. Anzahl der Produkte in der Bestellung). Multipliziert mit dem Preis ergibt sich der Gesamtbetrag für diesen Eventtype.
9BestellnummerStringWert aus dem eCommerce System, der zeigt, welche Positionen zu einer Bestellung gehören. Gehören mehrere Zeilen in diesem Export zu einer Bestellung, ist die Bestellnummer stets gleich. Unterschiedliche Bestellnummern verweisen auf verschiedene Bestellungen.
10Session-IDStringID der Besucher-Session. Über diesen Parameter können Produkte in einem abgebrochenen Warenkorb identifiziert werden. Werden für Produktansichten ebenfalls Session-IDs des Besuchers übermittelt, können zusammenhängende Produktansichten identifiziert werden. Ist die Nummer hier gleich, handelt es sich um Produkte aus einem Warenkorb oder Ansichten aus einer Sitzung.

Die Dateien werden gemäß der folgenden Konvention benamt:

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

Die Bezeichnung des <etracker_string> ist frei wählbar und dient dazu, eindeutige Dateien zu erzeugen. Das Datum sollte stets den Beginn der Daten aus dem Intervall anzeigen.

Der Anbieter des E-Mail-Marketing-Systems richtet einen Ordner für die Dateien ein und gibt den Pfad an etracker weiter.

d Externe Erstellung von Test-Accounts

1 Startvoraussetzungen

Für die Zuordnung der extern angelegten Test-Accounts wird eine etracker Partner-ID benötigt. Diese erhalten Sie im Rahmen eines Partnervertrages von Ihrem etracker Account Manager. Die Partner-ID wird bei der Erstellung eine Test-Accounts mit übergeben und garantiert die sichere Zuordnung zum Partner.

In den folgenden Beispielen dient die Partner-ID 1111 als Platzhalter und muss durch die Ihnen zugewiesene ID ersetzt werden.

Alle Code-Beispiele finden Sie auch in der rein technischen Online-Dokumentation unter: https://application.etracker.com/docs/index.php?apiName=backoffice#

Sollten Sie dieser folgen wollen, verwenden Sie bitte folgende Login-Daten:

Benutzername:    apiDocumentation

Passwort:             -etracker215-

Für den „Try it out!“-Button nutzen Sie bitte folgenden Benutzernamen ohne Passwort:

fbc45d3f099c5f46a51b880e92db7120

2 Externe Anlage von Test-Accounts

Für die externe Anlage eines etracker Test-Accounts muss beim Absenden des Partner-Formulars (oder beim entsprechenden Auslöser auf der Partnerseite) ein JSON-Objekt dynamisch mit Werten gefüllt und an etracker gesendet werden. Das folgende Beispiel zeigt die Übergabe der Variablen, die mindestens übergeben werden müssen.

2.1 Übergabe der Variablen

{  "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" }

Es wird im etracker Backend-System ein Test-Account mit den Produkten “etracker Analytics Enterprise Edition“ und „etracker Optimiser Enterprise Edition“ angelegt. Der Test-Account wird dem Partner mit der von Ihnen angegebenen ID zugeordnet.

Die generierte Account-ID und ein Link für die Passwort-Vergabe werden automatisch an die übergebene E-Mail-Adresse, hier test@test.de, gesendet.

2.2 JSON-Objekt senden

Das JSON-Objekt muss per POST-Methode an folgende URL und Benutzernamen gesendet werden:

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

2.3 Test-Account Erstellung mit ‚RESTClient‘

Die erfolgreiche Übergabe der Parameter für einen Test-Account kann mit dem ‚RESTClient‘-Plugin für Firefox komfortabel getestet werden (https://addons.mozilla.org/de/firefox/addon/restclient/ ).

Diese Eingaben sind hierfür notwendig:

1. Die Methode ‚Post‘ auswählen und die o.g. URL angeben:

test-account_2-3_erstellung-mit-restclient

2. Der zu verwendende Header im Plugin ist der o.g. Benutzername:

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

3. Das JSON-Objekt in den Body des Plugins einfügen:

Z. B. die minimale Übergabe an Variablen aus Punkt 2.1.

2.4 Alle möglichen Variablen im JSON-Objekt

Folgende Informationen können bei der Erstellung eines Test-Accounts neben den Pflichtvariablen an etracker übergeben werden:

{   "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" }

Falls die optionalen Parameter nicht gefüllt werden, müssen Default-Werte gesetzt oder die Variable weggelassen werden.

Hier eine Darstellung aller möglichen Parameterwerte.

{ 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 Mögliche Fehlermeldungen

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)

Das Single Sign-On beschreibt eine Schnittstelle, um einen Benutzer des CMS direkt in etracker einzuloggen.

Was bedeutet das? – Ein Beispiel

etracker Daten, wie die Anzahl der Besucher eines Onlineshops, werden exportiert und stehen dem Anwender in seinem CMS/ Shopsystem zur Verfügung. Dieser Anwender möchte weitere Information zu der Herkunft der Besucher erhalten. Über einen Link in dem CMS/Shopsystem gelangt Dieser direkt in die etracker Applikation in einen Report, der die Herkunft der Shop-Besucher ausweist, ohne sich bei etracker einloggen zu müssen.

Integration

Der Login erfolgt mit Hilfe eines POST Aufrufs der URL https://application.etracker.com/login.php mit dem Body im folgenden Format:

  • username= Name des Accounts
  • password= Passwort
  • cmsLogin= CMS2
  • targetUrl= Pfad zur aufzurufenden Seite (optional)

# Beispiel mit curl:

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

# Beispiel mit TargetUrl

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

Der Response enthält eine URL, die 60 Sekunden gültig ist und einen direkten, einmaligen Aufruf in die etracker Applikation ermöglicht.

Die TargetUrl lässt sich aus der Adresse der etracker Applikation kopieren. Hierfür wird der Teil nach der Raute kopiert:

Beispiel:
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.

War dieser Artikel hilfreich?

Ja Nein

Sie sind bereits Kunde und haben
eine konkrete Support-Anfrage?