Integration für Event-Streaming

Unterstützung durch Entwickler erforderlich

Sie benötigen Hilfe von Ihrem Entwicklungsteam, um die Integration einzurichten. Bitte teilen Sie diese Anleitung mit ihnen.

Integrationsübersicht

Integrationstyp

Quelle: Daten werden von Pushwoosh an Ihr System über HTTP oder gRPC basierend auf konfigurierten Event-Triggern gesendet.

Wie funktioniert die Integration?

Pushwoosh übermittelt Kommunikations-Event-Daten (z. B. Push-/E-Mail-Aktivitäten) an einen vom Kunden definierten Endpunkt. Die Daten werden in Batch-Streams in geplanten Intervallen oder bei Erreichen einer minimalen Batch-Größe gesendet.

Daten werden nur gesendet, wenn sie mit den ausgewählten Events, Plattformen und optionalen Filtern (Kampagnen-/Nachrichtencodes, Live-Aktivität) übereinstimmen. Der Endpunkt des Kunden muss bereit sein, die Daten zu empfangen und optional mit einem Status zu antworten.

Glossar

Endpunkt-URL: Serverseitiger Endpunkt, der den Empfang von Anfragen ermöglicht. Der Client kann bei Bedarf einen Port angeben.

Beispiele:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

Liste der synchronisierten Entitäten

• Kommunikationsstatistik-Events (z. B. Push gesendet, E-Mail zugestellt)
• Post-Events: Events, die Ihre App über postEvent an Pushwoosh sendet und die getrennt von den Kommunikationsstatistik-Events gestreamt werden

Anwendungsfälle

• Echtzeit-Engagement-Tracking

Überwachen Sie Benutzerinteraktionen wie gesendete Push-Nachrichten, geöffnete E-Mails oder zugestellte Nachrichten in Echtzeit, um sofortige Einblicke in die Kampagnenleistung zu erhalten.

• Integration externer Analysen

Streamen Sie Events an Analyseplattformen von Drittanbietern für zentralisierte Berichterstattung und Analyse.

• Automatisierte Benutzer-Workflows

Lösen Sie Aktionen in externen Systemen (wie CRMs oder Marketing-Automatisierungstools) basierend auf dem Benutzerverhalten aus, z. B. das Senden einer Folgenachricht, wenn ein Benutzer eine E-Mail öffnet.

• Synchronisierung der Geräteliste

Entfernen Sie Geräte aus Ihrer eigenen Datenbank, wenn sie keine Nachrichten mehr empfangen können. Siehe Abgemeldete Geräte mit Ihrem System synchronisieren.

Einrichtung der Integration

Um die Integration einzurichten:

1. Gehen Sie in Ihrem Pushwoosh-Konto zu Einstellungen > Integrationen von Drittanbietern, finden Sie die Integration für Event-Streaming und klicken Sie auf Konfigurieren.

2. Füllen Sie in dem sich öffnenden Fenster die erforderlichen Felder aus.

Endpunkt-URL eingeben

Geben Sie im Feld Endpunkt-URL die vollständige URL ein, an die Events gesendet werden sollen, einschließlich Protokoll und Port, falls zutreffend.

Beispiel

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

Events auswählen

Wählen Sie aus dem Dropdown-Menü Events mindestens ein Event aus. Wenn keines ausgewählt ist, schlägt die Validierung fehl. Die Liste der Events wird vom Backend verwaltet und kann sich im Laufe der Zeit ändern.

Anmeldeinformationen für die Autorisierung bereitstellen

Wenn von Ihrem Server gefordert, geben Sie den vollständigen Wert für den Authorization-Header in das Feld Autorisierung ein.

Beispiele:

• Bearer your_token_here

• Basic base64encoded_credentials

Hinweis

Der Wert wird unverändert in den Authorization-Header (HTTP) oder die gRPC-Metadaten eingefügt. Stellen Sie sicher, dass zwischen dem Authentifizierungsschema und dem Token ein Leerzeichen steht.

Transporttyp auswählen

Wählen Sie aus dem Dropdown-Menü Transporttyp das Übertragungsprotokoll für die Event-Übertragung: HTTP oder gRPC. Jedes hat ein spezifisches Verhalten und eine spezifische Konfiguration.

HTTP

Mit dem HTTP-Transporttyp sammelt Pushwoosh Events in einem Batch und sendet ihn, sobald eine der folgenden Bedingungen erfüllt ist:

• 10.000 Events wurden gesammelt, oder

• Seit dem Start des Batches sind 5 Minuten vergangen.

Ein Batch wird in HTTP-Anfragen mit bis zu 100 Events oder 768 KiB zugestellt, je nachdem, welches Limit zuerst erreicht wird.

Nach dem Senden der Daten wird die Verbindung geschlossen, sobald eine erfolgreiche Antwort empfangen wird.

Wenn der Server mit dem Statuscode 5xx, 408 oder 429 antwortet, wiederholt Pushwoosh die Anfrage gemäß der definierten Wiederholungsrichtlinie.

Wiederholungsmechanismus

Versuch	Verzögerung
1.	1 Sekunde
2.	3 Sekunden nach dem 1. Versuch
3.	8 Sekunden nach dem 2. Versuch

Wenn alle Wiederholungsversuche fehlschlagen, behält Pushwoosh die nicht zugestellten Events und versucht es eine Minute später erneut. Events, die Ihr Endpunkt bereits angenommen hat, werden nicht erneut gesendet.

Wenn Ihr Endpunkt mit 400, 413 oder 422 antwortet, teilt Pushwoosh die Anfrage in kleinere Anfragen auf, bis das abgelehnte Event allein gesendet wird, und verwirft dieses Event dann. Jede andere 4xx-Antwort stoppt die Zustellung des Batches: Pushwoosh wiederholt ihn bis zu 2 Stunden lang und verwirft ihn dann.

Wenn Ihr Endpunkt 24 Stunden lang fehlschlägt, ohne Events anzunehmen, pausiert Pushwoosh die Integration. Siehe Pausierte Integration.

Timeout

Das Standard-Timeout für eine Anfrage beträgt 60 Sekunden. Dies kann auf Anfrage über den Support angepasst werden.

Beispiel ansehen

gRPC

Der gRPC-Transporttyp verwendet bidirektionales Streaming für die Datenübertragung. Erfahren Sie mehr in der gRPC-Dokumentation.

Ein Stream wird geöffnet, wenn eine der folgenden Bedingungen erfüllt ist:

• Mindestens 1.000 Events sind zur Auslieferung bereit
• Eine Stunde ist seit dem letzten Öffnen eines Streams vergangen

Der Stream wird geschlossen, nachdem die Events gesendet wurden. Dies stellt sicher, dass nicht für jedes einzelne Event in kurzer Zeit ein neuer Stream geöffnet wird.

Protobuf-Spezifikation ansehen

Wiederholungsmechanismus
Jedes Event enthält eine eindeutige uuid. Wenn ein Event fehlschlägt:

1. Die Antwort muss einen status enthalten, der nicht gleich "Success" ist
2. Die ursprüngliche uuid aus der Anfrage muss enthalten sein

Pushwoosh wird die Zustellung basierend auf dieser Antwort erneut versuchen.

Verbindungseinstellungen

Erweiterte Optionen wie TLS, Keep-Alive oder Wiederholungsrichtlinien werden manuell über den Support konfiguriert und erfordern möglicherweise die Einbeziehung der Entwicklung.

Post-Events aktivieren

Dieser Schalter ist standardmäßig ausgeschaltet, sodass nur Kommunikationsstatistik-Events gestreamt werden. Um auch Events zu streamen, die Ihre App über postEvent an Pushwoosh sendet, schalten Sie den Schalter Post-Events zulassen ein.

Wählen Sie aus dem erscheinenden Feld Post-Events aus, welche Events Ihres Kontos gestreamt werden sollen. Mindestens ein Event ist erforderlich, während der Schalter eingeschaltet ist. Wenn Ihr Konto noch keine Events gesendet hat, ist diese Liste leer, bis Sie postEvent mindestens einmal aufrufen.

Hinweis

Post-Events werden an dieselbe oben eingegebene Endpunkt-URL gesendet und erreichen diese unabhängig von der Plattform: Die Abschnitte Plattformen und Erweiterte Filter unten gelten nur für Kommunikationsstatistik-Events, nicht für Post-Events.

In-App-Impressionen und -Klicks werden ebenfalls über diesen Post-Event-Stream übertragen, als PW_InAppShow und PW_InAppClicked. Wie jedes andere Post-Event erscheint jedes von ihnen erst dann in der Liste Post-Events, nachdem es mindestens einmal für das Konto ausgelöst wurde.

Plattformen auswählen

Wählen Sie im Abschnitt Plattformen mindestens eine Plattform aus, um das Event-Streaming zu aktivieren.

Unterstützte Plattformen umfassen:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• E-Mail, SMS, Line, Xiaomi, WhatsApp

Erweiterte Filter konfigurieren

Verfeinern Sie im Abschnitt Erweiterte Filter die Kriterien für die Event-Zustellung mithilfe von Filtern:

• Live-Aktivitäts-Events: Aktivieren, um Live-Aktivitäts-Events zu empfangen. Diese Events enthalten nur Metadaten, einschließlich live_activity_id.

• Kampagnenfilter: Nach Kampagnencode filtern. Nur Events, die mit diesen Kampagnen verknüpft sind, werden zugestellt.

• Nachrichtenfilter: Nach Nachrichtencode filtern. Nur Events, die mit diesen Nachrichten verknüpfen sind, werden zugestellt.

Nachdem Sie alle erforderlichen Felder ausgefüllt haben, klicken Sie auf die Schaltfläche Anwenden, um Ihre Integration zu speichern und zu aktivieren.

Hinweis

Konfigurationsänderungen werden innerhalb von 15 Minuten nach dem Absenden wirksam.

Tipp

Für erweiterte Einstellungen wie benutzerdefinierte Timeouts oder gRPC-Konfigurationen kontaktieren Sie bitte den Support.

Anfragedetails und Beispiel

Endpunkt	https://exampleclientendpoint.com/webhook_endpoint
HTTP-Anfrage	POST
Authentifizierung	Nein
Anfragetyp	Quelle
Bedeutung der Anfrage	Anfragen an den Webhook-Endpunkt senden
Header	Content-Type: application/json

Beispiel für den Anfrage-Body

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Attribute

Bei Kommunikationsstatistik-Events wird attributes nur für Push-Events gefüllt, mit kanalspezifischem Inhalt (Android, iOS usw.) für die Plattform, an die der Push gesendet wurde. E-Mail- und SMS-Events enthalten nur die Felder der obersten Ebene (event_name, platform, payload usw.). attributes ist für diese Events null. Innerhalb eines gefüllten attributes-Objekts werden Felder außerhalb der eigenen Plattform des Events weggelassen, anstatt als leere Werte gesendet zu werden. Die vollständige Feldliste finden Sie in webhook.proto.

Ein Post-Event trägt seine Attribut-Schlüssel/Wert-Paare stattdessen in attributes.event_attributes. message_code und payload bleiben leer, da ein Post-Event nicht mit einer Nachricht oder Kampagne verknüpft ist.

Vorsicht

attributes.geozone ist veraltet: Die Quelleigenschaft ist ein Objekt, keine Zahl, daher hat dieses Feld nie einen echten Wert enthalten. Lesen Sie die tatsächliche Geozone stattdessen aus attributes.geozone_data. Das alte Feld bleibt im Vertrag für Clients mit bestehenden gRPC-Stubs erhalten.

Antwort
Der Antwort-Body wird ignoriert. Beim HTTP-Transport entscheidet der Antwortcode, ob die Events als zugestellt gelten. Ein 2xx-Code bedeutet, dass Ihr Endpunkt sie angenommen hat.

Abgemeldete Geräte mit Ihrem System synchronisieren

Wenn Sie eine eigene Kopie der Geräteliste führen, zum Beispiel in einem CRM oder einer Kundendatenplattform, streamen Sie das Post-Event PW_DeviceUnregistered, um Geräte zu finden, die Pushwoosh nicht mehr erreichen kann. Pushwoosh sendet dieses Event, wenn ein Gerät sein Push-Abonnement verliert. Die Gründe finden Sie unter PW_DeviceUnregistered.

Gehen Sie von einer bereits eingerichteten Integration aus, in der eine Endpunkt-URL eingetragen und mindestens eine Plattform ausgewählt ist. Dann:

1. Aktivieren Sie in den Integrationseinstellungen Post-Events zulassen. Siehe Post-Events aktivieren.
2. Wählen Sie im Feld Post-Events PW_DeviceUnregistered aus.
3. Um auch über Geräte informiert zu werden, die einen Push-Token erhalten, wählen Sie PW_DeviceRegistered aus.
4. Klicken Sie auf Anwenden. Die Änderung wird innerhalb von 15 Minuten wirksam.

Wie jedes Post-Event erscheint PW_DeviceUnregistered erst in der Liste Post-Events, nachdem es mindestens einmal für das Konto ausgelöst wurde. Siehe Post-Events aktivieren.

Beachten Sie bei der Verarbeitung der Events diese Einschränkungen:

• Ordnen Sie Geräte über hwid oder user_id zu, nicht über den Push-Token. Das Event enthält hwid, user_id und Plattform des Geräts, aber keinen Push-Token und keinen Grund für die Abmeldung. Ein abgelaufener Token und eine Abmeldung über das SDK sehen gleich aus.
• Ein neuer Token für dasselbe Gerät sendet kein Event. PW_DeviceRegistered wird nur ausgelöst, wenn ein Gerät ohne Push-Token einen erhält. Eine Liste, die Geräte nach Push-Token speichert, behält Tokens, die nicht mehr funktionieren, denn wenn ein Gerät einen neuen Token erhält, wird keines der beiden Events ausgelöst.
• Eine E-Mail-Abmeldung löscht das Gerät nicht. Bei E-Mail bleibt die Adresse am Gerät, und Pushwoosh markiert sie nur als abgemeldet. Hat sich der Benutzer über einen Link in einer E-Mail abgemeldet, enthält attributes.event_attributes außerdem message_code und campaign_id dieser E-Mail.

Manche Events erreichen Ihren Endpunkt möglicherweise nie: Ein Event, das Ihr Endpunkt mit 400, 413 oder 422 ablehnt, wird verworfen, ebenso ein Batch, den Ihr Endpunkt 2 Stunden lang weiterhin mit einem anderen 4xx-Code ablehnt (siehe HTTP). Um diese Geräte zu erkennen, exportieren Sie regelmäßig das Segment der Geräte, die Sie ansprechen, als CSV und vergleichen Sie es mit Ihrer Geräteliste. Für den Export eines Segments benötigt Ihre Rolle die Berechtigung Personal data. Wenn Ihr Endpunkt 24 Stunden lang fehlschlägt, wird die Integration pausiert und es kommen keine Events mehr an. Siehe Pausierte Integration.

Pausierte Integration

Wenn Zustellungen an Ihren HTTP-Endpunkt 24 Stunden lang fehlschlagen und der Endpunkt in dieser Zeit keine Events annimmt, pausiert Pushwoosh die Integration:

• Pushwoosh sendet keine Events mehr an den Endpunkt.
• Events, die auf den Versand warten, werden verworfen. Events aus dem pausierten Zeitraum werden nicht nachträglich gesendet.
• Der Kontoinhaber erhält eine E-Mail über die Pausierung. Die Integrationseinstellungen zeigen die Pausierung nicht an, daher ist diese E-Mail die einzige Benachrichtigung.

Ein Event gilt als angenommen, wenn Ihr Endpunkt einen 2xx-Antwortcode zurückgibt. Teilweise Fehler pausieren die Integration nicht: Jedes angenommene Event startet die 24-Stunden-Zählung neu. Integrationen mit dem gRPC-Transport werden nicht pausiert.

So setzen Sie das Streaming fort:

1. Stellen Sie sicher, dass Ihr Endpunkt erreichbar ist und einen 2xx-Antwortcode zurückgibt.
2. Gehen Sie zu Einstellungen > Integrationen von Drittanbietern, finden Sie die Integration für Event-Streaming und klicken Sie auf Konfigurieren.
3. Klicken Sie auf Anwenden. Sie müssen keine Einstellungen ändern. Das Streaming wird innerhalb von 15 Minuten fortgesetzt.

Woher wissen Sie, dass die Integration funktioniert?

Sie werden beginnen, Anfragen von Pushwoosh an Ihrem konfigurierten Endpunkt zu erhalten.