etracker
Analytics Editionen / Preise Live-Demo
etracker
Optimiser Editionen / Preise Live-Demo
Preise Academy Blog

Entwickler-APIs

  1. REST-Report API v3
  2. Targeting API
  3. Remarketing Feed
  4. Externe Erstellung von Test-Accounts

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:

{
  "CCWRPage":"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/CCWRPage/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 ‚CCWRPage‘ 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/CCWRPage/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/CCWRPage/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/CCWRPage/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 CMS 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

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 2>
 &_et_coid=<CookieId>

Beispiel:

https://ws.etracker.com/api/rest/v2/realtime/user?et=c%2FvZgay2SaHf8iVpHdFEyFCUB3NDirFUJnpHCGPWKI0%3D&_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)
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 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)

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.3 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": "3",
"page": "dmexco"
},
{
"timestamp": "1415713855503100",
"rank": "1",
"page": "Index"
},
{
"timestamp": "1415713855436000",
"rank": "2",
"page": "Targeting Suite"
}
]
(Die Index-Seite hat den Rank 1)
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.4 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

 

 

 

 

 

Sie haben diesen Artikel bereits bewertet.

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