Statistik-API

info Dies ist die neueste Version der Statistiken-API. Die Verbesserungen der Version v4 umfassen:

Verwendung von HTTP Basic Authentication zur Autorisierung des Zugriffs. Dadurch kann die gesamte API-Anfrage mit gängigen HTTP-Tools wie curl und Browser-Erweiterungen durchgeführt werden.
Die Push-Inhalte werden im JSON-Format bereitgestellt.

Überblick

Die Statistiken-API v4 bietet verschiedene Funktionen zur Datenabfrage rund um Push-Nachrichten, Nutzerstatistiken und Lebenszyklusstatus.

Authentifizierungsprüfung

Weitere Informationen finden Sie unter Authentifizierungsmethode.

Push-Nachrichtenstatistiken

Abfrage der Statistiken für jeden Lebenszyklusstatus einer Nachrichten-ID.
Die Statistiken jeder Push-Nachricht werden höchstens einen Monat gespeichert.

API-Endpunkt

GET v4/messages/details

Beispiel für eine Anfrage

curl -v https://webpushapi-sgp.engagelab.com/v4/messages/details?message_ids=1613113584,1229760629 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/messages/details?message_ids=1613113584,1229760629 HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              curl -v https://webpushapi-sgp.engagelab.com/v4/messages/details?message_ids=1613113584,1229760629 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/messages/details?message_ids=1613113584,1229760629 HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrageparameter

Schlüsselwort	Typ	Option	Beschreibung
message_ids	String	erforderlich	Nachrichten-ID(s), mehrere message_ids durch Komma getrennt. Es sind maximal 100 message_ids zulässig.

Beispiel für eine Antwort

< HTTP/1.1 200 OK < Content-Type: application/json { "1083008": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 1, "clicks": 0, "sub": { "notification": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 1, "clicks": 0, "sub_web": { "engageLab_web": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "chrome": { "targets": 1, "sent": 1, "delivered": 1, "impressions": 1, "clicks": 0 }, "safari": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "firefox": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "edge": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 }, "other": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 } } }, "message": { "targets": 0, "sent": 0, "delivered": 0, "impressions": 0, "clicks": 0 } }, "plan_id": "engageLab_msg", "pushContent": { "message": { "title": "msg", "content": "push" } } } }

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "1083008": {
        "targets": 1,
        "sent": 1,
        "delivered": 1,
        "impressions": 1,
        "clicks": 0,
        "sub": {
            "notification": {
                "targets": 1,
                "sent": 1,
                "delivered": 1,
                "impressions": 1,
                "clicks": 0,
                "sub_web": {
                    "engageLab_web": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "chrome": {
                        "targets": 1,
                        "sent": 1,
                        "delivered": 1,
                        "impressions": 1,
                        "clicks": 0
                    },
                    "safari": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "firefox": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "edge": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    },
                    "other": {
                        "targets": 0,
                        "sent": 0,
                        "delivered": 0,
                        "impressions": 0,
                        "clicks": 0
                    }
                }
            },
            "message": {
                "targets": 0,
                "sent": 0,
                "delivered": 0,
                "impressions": 0,
                "clicks": 0
            }
        },
        "plan_id": "engageLab_msg",
        "pushContent": {
            "message": {
                "title": "msg",
                "content": "push"
            }
        }
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Die erfolgreiche Antwort ist ein JSON-Objekt, wobei der Schlüssel jeweils die Nachrichten-ID ist. Jede Nachricht enthält die Statistiken für jede Phase des Lebenszyklus:

Schlüsselwort	Typ	Option	Beschreibung
targets	Int64	erforderlich	Anzahl der Zielgeräte, die nach Wirksamkeitsprüfung für das Pushen ausgewählt wurden.
sent	Int64	erforderlich	Anzahl der Geräte, an die der EngageLab-Server die Aufgabe tatsächlich erfolgreich gesendet hat.
delivered	Int64	erforderlich	Anzahl der tatsächlichen Zustellungen an das Web-Endgerät (nach 5 Tagen nicht mehr gezählt).
impressions	Int64	erforderlich	Anzahl der erfolgreichen Anzeigen der Benachrichtigung auf dem Endgerät.
clicks	Int64	erforderlich	Anzahl der Klicks durch Nutzer:innen nach erfolgreicher Anzeige.
sub	Objekt	erforderlich	Aufschlüsselung der statistischen Daten: - notification: Zusammenfassung der Benachrichtigungsarten. - message: Zusammenfassung benutzerdefinierter Nachrichten.
plan_id	String	erforderlich	Push-Plan-ID, die den Push-Plan-Typ identifiziert, zu dem die Nachricht gehört.
pushContent	Objekt	erforderlich	Details zum Push-Inhalt, inkl. Informationen für verschiedene Plattformen: - android: Android-Push-Inhalt (z. B. Titel, Inhalt) - ios: iOS-Push-Inhalt (Titel, Inhalt, Untertitel) - message: Benutzerdefinierter Nachrichteninhalt (Titel, Inhalt)

Indikatoren

Schlüsselwort	Typ	Option	Beschreibung
sub_web	Objekt	optional	Zusammengefasste Statistik der verschiedenen Push-Kanäle im Web
engageLab_web	Objekt	optional	Statistik für den EngageLab-Kanal
chrome	Objekt	optional	Statistik für den Chrome-Kanal
safari	Objekt	optional	Statistik für den Safari-Kanal
firefox	Objekt	optional	Statistik für den Firefox-Kanal
edge	Objekt	optional	Statistik für den Edge-Kanal
other	Objekt	optional	Statistik für andere Kanäle

Nutzerstatistiken

Liefert relevante statistische Daten zu Nutzern innerhalb eines bestimmten Zeitraums der letzten 2 Monate: inklusive neue Nutzer, neue Nutzer:innen, Online-Nutzer, Online-Nutzer:innen und aktive Nutzer, aktive Nutzer:innen.
Zeiteinheit: HOUR, DAY, MONTH

API-Endpunkt

GET v4/status/users

Beispiel für eine Anfrage

curl -v https://webpushapi-sgp.engagelab.com/v4/status/users?time_unit=DAY&start=2014-06-10&duration=3 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/users?time_unit=&start=&duration= HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/users?time_unit=DAY&start=2014-06-10&duration=3 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/users?time_unit=&start=&duration= HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrageparameter

Schlüsselwort	Typ	Option	Beschreibung
time_unit	String	optional	Zeiteinheit: HOUR, DAY, MONTH
start	String	optional	Startzeitpunkt: - Bei Stunde: Startzeit inkl. Tag, z. B. 2006-01-02T15 - Bei Tag: Startdatum, z. B. 2022-06-11 - Bei Monat: Startmonat, z. B. 2022-06
duration	String	optional	Zeitraum: - Bei Tag: Anzahl der Tage - Es können nur Nutzerinformationen der letzten 60 Tage abgefragt werden. Bei Zeiteinheit HOUR werden nur die Ergebnisse des aktuellen Tages ausgegeben.

Beispiel für eine Antwort

< HTTP/1.1 200 OK < Content-Type: application/json { "time_unit": "DAY", "start": "2014-06-10", "duration": 3, "items": [{ "time": "2014-06-12", "web": { "new": 1, "active": 1, "online": 2 } }] }

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "time_unit": "DAY",
    "start": "2014-06-10",
    "duration": 3,
    "items": [{
        "time": "2014-06-12",
        "web": {
      "new": 1,
            "active": 1,
            "online": 2
    }
    }]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Erfolgreiche Antwort ist ein JSON-Objekt:

Schlüsselwort	Typ	Option	Beschreibung
time_unit	String	erforderlich	Zeiteinheit: HOUR, DAY, MONTH
start	String	erforderlich	Startzeitpunkt: - Bei Stunde: Startzeit inkl. Tag, z. B. 2022-06-11 09 - Bei Tag: Startdatum, z. B. 2022-06-11 - Bei Monat: Startmonat, z. B. 2022-06
duration	String	erforderlich	Zeitraum: - Bei Tag: Anzahl der Tage - Es können nur Nutzerinformationen der letzten 60 Tage abgefragt werden. Bei Zeiteinheit HOUR werden nur die Ergebnisse des aktuellen Tages ausgegeben.
items	JSON Array	erforderlich	Statistische Ergebnisse im Zeitraum entsprechend der Dauer

items:
- web: Zusammengefasste Statistik der Web-Plattform

Schlüsselwort	Typ	Option	Beschreibung
new	Int64	optional	Neue Nutzer
online	Int64	optional	Online-Nutzer
active	Int64	optional	Aktive Nutzer

Abfrage des Nachrichten-Lebenszyklusstatus

Abfrage des Lebenszyklusstatus einer Push-Nachricht für das entsprechende Gerät unter einer Nachrichten-ID.
Die Statistiken jeder Push-Nachricht werden höchstens einen Monat gespeichert.

API-Endpunkt

GET v4/status/message

Beispiel für eine Anfrage

curl -v https://webpushapi-sgp.engagelab.com/v4/status/message?message_id=1613113584&registration_ids=1507bfd3a7c568d4761,1618cfd3a7c568d4761,17259fd3a7c568d4371 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/status?message_id=&registration_ids= HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/message?message_id=1613113584&registration_ids=1507bfd3a7c568d4761,1618cfd3a7c568d4761,17259fd3a7c568d4371 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/status?message_id=&registration_ids= HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrageparameter

Schlüsselwort	Typ	Option	Beschreibung
message_id	String	erforderlich	Nachrichten-ID
registration_ids	String	erforderlich	Registrierungs-ID(s), mehrere IDs durch Komma getrennt. Es sind maximal 1.000 registration_ids zulässig.

Beispiel für eine Antwort

< HTTP/1.1 200 OK < Content-Type: application/json { "1507bfd3a7c568d4761": { "itime": 1762331775, "channel": "FCM", "status": "delivered" }, "17259fd3a7c568d4371": { "error_message": "Die „registration_id“ gehört nicht zum appkey", "error_code": 21003 }, "17259fd3a7c568d4787":{ "itime": 1762331775, "status": "sent_failed", "error_code": 401, "error_message": "Token ist ungültig", "channel": "FCM" }, "17259fd3a7c568d4372": { "error_code": 21061, "error_message": "Kein effektiver Status" } }

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "1507bfd3a7c568d4761": {
        "itime": 1762331775,
        "channel": "FCM",
        "status": "delivered"
    },
    "17259fd3a7c568d4371": {
        "error_message": "Die „registration_id“ gehört nicht zum appkey",
        "error_code": 21003
    },
    "17259fd3a7c568d4787":{
        "itime": 1762331775,
        "status": "sent_failed",
        "error_code": 401,
        "error_message": "Token ist ungültig",
        "channel": "FCM"		
    },
    "17259fd3a7c568d4372": {
        "error_code": 21061,
        "error_message": "Kein effektiver Status"
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlerantwort

{ "error": { "code": 21003, "message": "Parameterwert ist ungültig" } }

              
              {
  "error": {
    "code": 21003,
    "message": "Parameterwert ist ungültig"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Die erfolgreiche Antwort ist ein JSON-Objekt mit dem aktuellen Status jeder Registrierungs-ID unter dieser Push-Nachricht. Bei Ausnahmen wird die Fehlermeldung im Feld „error_message“ ausgegeben.

Schlüsselwort	Typ	Option	Beschreibung
status	String	optional	Wertebereich: plan, target_valid, target_invalid, sent, sent_failed, delivered, delivered_failed, impression, click
error_message	String	optional	Fehlermeldung

Batch-Abfrage Nachrichten-Lebenszyklusstatus

Batch-Abfrage des Nachrichten-Lebenszyklusstatus für eine einzelne Registrierungs-ID unter jeder Nachrichten-ID. Wenn mehrere Registrierungs-IDs unter derselben Nachrichten-ID existieren, werden die entsprechenden Nachrichten-IDs in „multi_regid_message_ids“ zurückgegeben.
Statistiken jeder Push-Nachricht werden höchstens einen Monat gespeichert.

API-Endpunkt

GET v4/status/batch/message

Beispiel für eine Anfrage

curl -v https://webpushapi-sgp.engagelab.com/v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" < GET /v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 HTTP/1.1 < Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              curl -v https://webpushapi-sgp.engagelab.com/v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1"

< GET /v4/status/batch/message?message_ids=1613113584,1613113585,1613113586 HTTP/1.1
< Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrageparameter

Schlüsselwort	Typ	Option	Beschreibung
message_ids	String	erforderlich	Nachrichten-IDs, mehrere message_ids durch Komma getrennt. Es sind maximal 100 message_ids zulässig.

Antwortparameter

Die erfolgreiche Antwort ist ein Array-Objekt; jeder Eintrag steht für den aktuellen Status unter einer einzelnen Nachrichten-ID (und ggf. einer einzelnen Registrierungs-ID). Bei Fehlern wird „error_message“ ausgegeben.

Schlüsselwort	Typ	Option	Beschreibung
message_id	String	erforderlich	Die Nachrichten-ID
registration_id	String	optional	Die abgefragte Registrierungs-ID
status	String	optional	Wertebereich: plan, target_valid, target_invalid, sent, sent_failed, delivered, delivered_failed, impression, click
itime	Int64	optional	Zeitpunkt des Status-Updates (Sekunden)
channel	String	optional	Kanal, über den die Nachricht gepusht wurde
error_message	String	optional	Fehlermeldung, nur bei bestimmten Statuswerten verfügbar
error_code	Int64	optional	Fehlerstatus-Code, nur bei bestimmten Statuswerten verfügbar

Beispiel für eine Antwort

Erfolgreiche Antwort

< HTTP/1.1 200 OK < Content-Type: application/json [ { "message_id": "261585110", "error_message": "Mehrere „registration_id“ unter derselben „message_id“ gefunden.", "error_code": 21003 }, { "message_id": "261585123", "registration_id": "170976fa8ab73279b2f", "status": "click", "itime": 1766047747, "channel": "EngageLab" }, { "message_id": "1613113585", "error_message": "Die „message_id“ ist ungültig oder existiert nicht.", "error_code": 21003 } ]

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
[
  {
    "message_id": "261585110",
    "error_message": "Mehrere „registration_id“ unter derselben „message_id“ gefunden.",
    "error_code": 21003
  },
  {
    "message_id": "261585123",
    "registration_id": "170976fa8ab73279b2f",
    "status": "click",
    "itime": 1766047747,
    "channel": "EngageLab"
  },
  {
    "message_id": "1613113585",
    "error_message": "Die „message_id“ ist ungültig oder existiert nicht.",
    "error_code": 21003
  }
]

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlerantwort

{ "error": { "code": 21003, "message": "Parameterwert ist ungültig" } }

              
              {
  "error": {
    "code": 21003,
    "message": "Parameterwert ist ungültig"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antworten auf API-Anfragen

HTTP-Status

Referenz: HTTP-Status-Code

Geschäftscodes der Rückgabe

Code	Beschreibung	HTTP-Status-Code
0	Erfolg	200
21001	Methode nicht unterstützt oder URL-Fehler	404
21003	Parameterwert ist ungültig	400
23001	Basic Authentication fehlgeschlagen	401
23002	Parameter fehlt!	400
23004	Wert von time_unit passt nicht zum Startwert!	400
23007	Es können nur message_id der letzten 30 Tage abgefragt werden!	400
23100	Serverfehler	500
27000	Server-Antwortzeit überschritten, bitte später erneut versuchen	500
27201	msgid existiert nicht oder gehört nicht zu dieser Anwendung	400