Callback-API

Übersicht

Die Statusdaten von Nachrichten werden an das Geschäftssystem des Unternehmens übermittelt und können dort für statistische Analysen genutzt werden.

Callback-Adresse

Das Unternehmen muss eine Callback-Adresse zum Empfang von Nachrichtenstatus-Änderungen hinterlegen. Aktuell gibt es keine Web-Oberfläche dafür. Bitte wenden Sie sich an das technische Personal von Engagelab, um die Callback-Adresse einzurichten.

Überprüfung der Gültigkeit der Callback-Adresse

Beim Konfigurieren der Callback-Adresse im Push-Backend unter Anwendungseinstellungen wird eine POST-Anfrage mit einem zufällig generierten 8-stelligen String als echostr im Request-Body gesendet. Sie müssen den Wert von echostr im Response-Body zurückgeben, wie im folgenden Format:

Request Body:

{ "echostr": "12345678" }

              
              {
    "echostr": "12345678"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Response Body:

12345678

12345678

Diesen Codeblock im schwebenden Fenster anzeigen

Sicherheitsmechanismus

Dient der Client-Authentifizierung, optional.

Um sicherzustellen, dass die Nachrichten tatsächlich von Engagelab stammen, können Sie die Quelle der POST-Daten authentifizieren. Alternativ können Sie die POST-Daten auch direkt ohne Authentifizierung verarbeiten.

Das Authentifizierungsverfahren ist wie folgt:

Konfigurieren Sie im Engagelab-Backend für die Callback-Adresse einen Callback-Benutzernamen (username) und ein Callback-Secret (secret).

Lesen Sie X-CALLBACK-ID aus dem Request-Header, wie im folgenden Beispiel:

X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

              
              X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

Diesen Codeblock im schwebenden Fenster anzeigen

Bedeutung:

timestamp: Zeitstempel der Callback-Nachricht (Standardformat)
nonce: Zufallszahl
signature: Signatur-Information

Die Signatur wird wie folgt gebildet:

signature=HMAC-SHA256(secret, timestamp+nonce+username)

              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortmechanismus

Nachdem der Entwickler-Service den Callback von Engagelab empfangen hat, muss innerhalb von 3 Sekunden wie folgt geantwortet werden:

Erfolgreich empfangen: Der HTTP-Statuscode muss 200 oder 204 sein, eine Antwortnachricht ist nicht erforderlich.
Empfang fehlgeschlagen: Der HTTP-Statuscode muss 5XX oder 4XX sein und eine Antwortnachricht enthalten. Das Format ist wie folgt:

{ "code": 2002, "message": "error" }

              
              {
    "code": 2002,
    "message": "error"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Feld	Typ	Erforderlich	Beschreibung
`code`	int	Optional	Fehlercode
`message`	string	Optional	Fehlerdetails

Erklärung der Callback-Felder

Nachrichten-Body

Feldname	Typ	Erforderlich	Beschreibung
`total`	int	Erforderlich	Anzahl der in diesem Callback enthaltenen Nachrichten
`rows`	array	Erforderlich	Liste mit Detailinformationen zu den Nachrichtenstatus-Änderungen, enthält die untenstehenden Felder

Felder des `rows`-Arrays

Feldname	Typ	Erforderlich	Beschreibung
`message_id`	string	Erforderlich	Eindeutige Kennung der Nachricht
`from`	string	Optional	Absender, Standard ist appkey
`to`	string	Optional	Empfängerkennung (z. B. `registrationID`)
`server`	string	Erforderlich	Name des Nachrichtendienstes, mögliche Werte: `WebPush`
`channel`	string	Erforderlich	Nachrichtenkanal, mögliche Werte: `EngageLab`, `Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`
`custom_args`	object	Optional	Beim Erstellen der Nachricht übergebene benutzerdefinierte Parameter, werden unverändert zurückgegeben
`itime`	int	Erforderlich	Zeitstempel des Statusereignisses, kann mit `message_status` kombiniert werden
`status`	object	Erforderlich	Statusinformationen zur Nachricht, enthält die folgenden Felder:

Felder des `status`-Objekts

Feldname	Typ	Erforderlich	Beschreibung
`message_status`	string	Erforderlich	Nachrichtenstatus, mögliche Werte: `target_valid`, `sent`, `delivered`, `click`, `target_invalid`, `sent_failed`, `delivered_failed`, `no_click`
`status_data`	object	Optional	Benutzerdefinierte Statusdaten, enthält die folgenden Felder:
`channel_message_id`	string	Optional	Nachrichten-ID aus Drittanbieter-Kanälen
`ntf_msg`	int	Erforderlich	Nachrichtentyp, mögliche Werte: `1: Benachrichtigung`, `2: Benutzerdefinierte Nachricht`, `7: In-App-Nachricht`
`platform`	string	Erforderlich	Push-Plattform, mögliche Werte: `b: Web`
`uid`	int	Erforderlich	UID des Empfängers der Push-Nachricht
`app_version`	string	Erforderlich	App-Version mit SDK-Integration, gemeldet durch SDK
`channel`	string	Erforderlich	App-Kanal mit SDK-Integration, gemeldet durch SDK
`msg_time`	int	Erforderlich	Zeitpunkt der erfolgreichen API-Anfrage zum Senden der Nachricht
`time_zone`	string	Erforderlich	Zeitzone der Organisation
`loss_valid_type`	int	Optional	Ohne Bedeutung, kann ignoriert werden
`plan_user_total`	int	Optional	Ohne Bedeutung, kann ignoriert werden
`callback_type`	int	Optional	Ohne Bedeutung, kann ignoriert werden
`error_code`	int	Optional	Fehlercode, nur im Fehlerfall vorhanden
`error_detail`	object	Optional	Detaillierte Fehlerinformationen, nur im Fehlerfall, enthält folgende Felder:
`message`	string	Optional	Beschreibung des Fehlergrundes, nur für FCM-Kanal relevant
`loss`	object	Optional	Verlustinformationen, enthält folgende Felder:
`loss_source`	string	Optional	Quelle des Verlusts, mögliche Werte: `EngageLab`, `Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Other`
`loss_step`	int	Optional	Verluststufe, mögliche Werte: `1: Plan-Ziel → Gültiges Ziel`, `2: Gültiges Ziel → Gesendet`, `3: Gesendet → Zugestellt`, `4: Zugestellt → Klick`

Nachrichtenstatus-Werte

Statuswert	Bedeutung	Beschreibung
`target_valid`	Gültiges Ziel	Gilt als gültig, wenn in den letzten 365 Tagen aktiv
`sent`	Erfolgreich gesendet	Erfolgreich an den Server gesendet
`delivered`	Erfolgreich zugestellt	Zustellung basierend auf echtem Callback
`click`	Vom Nutzer geklickt	Vom SDK gemeldeter Klick des Nutzers
`target_invalid`	Ungültiges Ziel	Gilt als ungültig gemäß Verluststufe 1
`sent_failed`	Senden fehlgeschlagen	Gilt als ungültig gemäß Verluststufe 2
`delivered_failed`	Zustellung fehlgeschlagen	Gilt als fehlgeschlagen gemäß Verluststufe 3
`no_click`	Klick fehlgeschlagen	Gilt als fehlgeschlagen gemäß Verluststufe 4, nur für In-App-Nachrichten

Callback-Inhalt

Callback-Methode: POST
Content-Type: application/json

Beispiel

Request Header

POST /developer_define_url HTTP/1.1 Content-Type: application/json

              
              POST /developer_define_url HTTP/1.1
Content-Type: application/json

Diesen Codeblock im schwebenden Fenster anzeigen

Request Body

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", // Nachricht-ID auf EngageLab-Seite "from": "", // Absender "to": "", // Empfänger, registrationID "server": "WebPush", "channel": "Chrome", "custom_args": {}, // Die beim Erstellen übergebenen Parameter "itime": 1640707579, // z. B. Zeitpunkt der Zustellung "status": { // Felder bei Erfolg "message_status": "delivered", // Nachrichtenstatus "status_data": { // Benutzerdefinierte Daten "channel_message_id": "wamid.123321abcdefed==", // Optional, Drittanbieter-Nachrichten-ID "ntf_msg": 1, // Nachrichtentyp "platform": "a", // Push-Plattform "uid": 100, // Nutzer-ID für Push "app_version": "", // App-Version mit SDK-Integration "channel": "", // App-Kanal mit SDK-Integration "msg_time": 1640707579, // Zeitpunkt der erfolgreichen API-Anfrage "time_zone": "+8", // Zeitzone der Organisation "loss_valid_type": 0, // Ohne Bedeutung "plan_user_total": 0, // Ohne Bedeutung "callback_type": 0 // Ohne Bedeutung }, // Felder bei Fehler "error_code": 0, // Fehlercode – entsprechend dem Lebenszyklus-Fehlercode "error_detail": { "message": "" // Fehlergrund }, "loss": { "loss_source": "vivo", "loss_step": 1 } // Verluststufe und -quelle } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861", // Nachricht-ID auf EngageLab-Seite
            "from": "", // Absender
            "to": "", // Empfänger, registrationID
            "server": "WebPush",
            "channel": "Chrome",
            "custom_args": {}, // Die beim Erstellen übergebenen Parameter
            "itime": 1640707579, // z. B. Zeitpunkt der Zustellung
            "status": {
                // Felder bei Erfolg
                "message_status": "delivered", // Nachrichtenstatus    
                "status_data": { // Benutzerdefinierte Daten
                    "channel_message_id": "wamid.123321abcdefed==", // Optional, Drittanbieter-Nachrichten-ID
                    "ntf_msg": 1, // Nachrichtentyp
                    "platform": "a", // Push-Plattform
                    "uid": 100, // Nutzer-ID für Push    
                    "app_version": "", // App-Version mit SDK-Integration 
                    "channel": "", // App-Kanal mit SDK-Integration   
                    "msg_time": 1640707579, // Zeitpunkt der erfolgreichen API-Anfrage
                    "time_zone": "+8", // Zeitzone der Organisation 
                    "loss_valid_type": 0, // Ohne Bedeutung
                    "plan_user_total": 0, // Ohne Bedeutung 
                    "callback_type": 0 // Ohne Bedeutung
                },
                // Felder bei Fehler
                "error_code": 0, // Fehlercode – entsprechend dem Lebenszyklus-Fehlercode
                "error_detail": {
                    "message": "" // Fehlergrund
                },
                "loss": {
                    "loss_source": "vivo",
                    "loss_step": 1
                } // Verluststufe und -quelle
            }
        }
    ]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Parameterbeschreibung

Wert	Bedeutung
`target_valid`	Gültiges Ziel
`sent`	Erfolgreich gesendet
`delivered`	Erfolgreich zugestellt
`click`	Vom Nutzer geklickt
`target_invalid`	Ungültiges Ziel
`sent_failed`	Senden fehlgeschlagen
`delivered_failed`	Zustellung fehlgeschlagen

Verluststufen

Plan-Ziele → Gültige Ziele
Gültige Ziele → Gesendet
Gesendet → Zugestellt
Zugestellt → Klicks

Hinweis:
1. Klicks und Zustellungen können bei einigen Kanälen doppelt gezählt werden, Sie können eine eigene Duplikaterkennung durchführen.
2. Die Anzahl der Zustellungen und Anzeigen wird 5 Tage nach erfolgreicher Zustellung nicht mehr rückwirkend angepasst.

Callback-API

Übersicht

Callback-Adresse

Überprüfung der Gültigkeit der Callback-Adresse

Sicherheitsmechanismus

Antwortmechanismus

Erklärung der Callback-Felder

Nachrichten-Body

Felder des rows-Arrays

Felder des status-Objekts

Nachrichtenstatus-Werte

Callback-Inhalt

Beispiel

Request Header

Request Body

Parameterbeschreibung

Verluststufen

Felder des `rows`-Arrays

Felder des `status`-Objekts