Intégration du streaming d'événements

Assistance d'un développeur requise

Vous aurez besoin de l’aide de votre équipe de développement pour configurer l’intégration. Veuillez partager ce guide avec eux.

Aperçu de l’intégration

Type d’intégration

Source : Les données sont envoyées de Pushwoosh à votre système via HTTP ou gRPC en fonction des déclencheurs d’événements configurés.

Comment fonctionne l’intégration ?

Pushwoosh transmet les données d’événements de communication (par ex., l’activité des notifications push/e-mails) à un point de terminaison défini par le client. Les données sont envoyées en flux par lots à des intervalles programmés ou lorsqu’une taille de lot minimale est atteinte.

Les données ne sont envoyées que si elles correspondent aux événements, plateformes et filtres optionnels sélectionnés (codes de campagne/message, activité en direct). Le point de terminaison client doit être prêt à recevoir et éventuellement à répondre avec un statut.

Glossaire

URL du point de terminaison : Point de terminaison côté serveur qui permet de recevoir des requêtes. Le client peut spécifier un port si nécessaire.

Exemples :

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

Liste des entités synchronisées

• Événements de statistiques de communication (par ex., Push envoyé, E-mail délivré)
• Événements post : événements que votre application envoie à Pushwoosh via postEvent, diffusés séparément des événements de statistiques de communication

Cas d’utilisation

• Suivi de l’engagement en temps réel

  Surveillez les interactions des utilisateurs telles que l’envoi de notifications push, l’ouverture d’e-mails ou la livraison de messages au moment où elles se produisent, permettant une visibilité immédiate sur les performances de la campagne.

• Intégration d’analyses externes

  Diffusez des événements vers des plateformes d’analyse tierces pour un reporting et une analyse centralisés.

• Flux de travail utilisateur automatisés

  Déclenchez des actions dans des systèmes externes (comme les CRM ou les outils d’automatisation du marketing) en fonction du comportement des utilisateurs, par ex., envoyer un message de suivi lorsqu’un utilisateur ouvre un e-mail.

• Synchronisation de la liste des appareils

  Supprimez de votre propre base de données les appareils qui ne peuvent plus recevoir de messages. Consultez Synchroniser les appareils désinscrits avec votre système.

Configuration de l’intégration

Pour configurer l’intégration :

1. Dans votre compte Pushwoosh, allez dans Paramètres > Intégrations tierces, trouvez Intégration du streaming d’événements, et cliquez sur Configurer.

2. Dans la fenêtre qui s’ouvre, remplissez les champs nécessaires.

Saisir l’URL du point de terminaison

Dans le champ URL du point de terminaison, saisissez l’URL complète où les événements seront envoyés, y compris le protocole et le port le cas échéant.

Exemple

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

Sélectionner les événements

Dans le menu déroulant Événements, sélectionnez au moins un événement. Si aucun n’est sélectionné, la validation échouera. La liste des événements est gérée par le backend et peut changer avec le temps.

Fournir les informations d’autorisation

Si votre serveur l’exige, saisissez la valeur complète de l’en-tête Authorization dans le champ Autorisation.

Exemples :

• Bearer your_token_here

• Basic base64encoded_credentials

Note

La valeur est insérée telle quelle dans l’en-tête Authorization (HTTP) ou les métadonnées gRPC. Assurez-vous qu’il y a un espace entre le schéma d’authentification et le jeton.

Choisir le type de transport

Dans le menu déroulant Type de transport, choisissez le protocole de livraison pour la transmission des événements : HTTP ou gRPC. Chacun a un comportement et une configuration spécifiques.

HTTP

Avec le type de transport HTTP, Pushwoosh regroupe les événements dans un lot et l’envoie dès que l’une des conditions suivantes est remplie :

• 10 000 événements ont été collectés, ou

• 5 minutes se sont écoulées depuis le début du lot.

Un lot est livré par requêtes HTTP de 100 événements ou 768 KiB au maximum, selon la limite atteinte en premier.

Après l’envoi des données, la connexion est fermée une fois qu’une réponse réussie est reçue.

Si le serveur répond avec un code d’état 5xx, 408 ou 429, Pushwoosh réessaie la requête selon la politique de relance définie.

Mécanisme de relance

Tentative	Délai
1ère	1 seconde
2ème	3 secondes après la 1ère tentative
3ème	8 secondes après la 2ème tentative

Si toutes les tentatives échouent, Pushwoosh conserve les événements non livrés et les renvoie une minute plus tard. Les événements déjà acceptés par votre point de terminaison ne sont pas renvoyés.

Si votre point de terminaison répond avec 400, 413 ou 422, Pushwoosh divise la requête en requêtes plus petites jusqu’à ce que l’événement refusé soit envoyé seul, puis abandonne cet événement. Toute autre réponse 4xx interrompt la livraison du lot : Pushwoosh le relance pendant 2 heures au maximum, puis l’abandonne.

Si votre point de terminaison continue d’échouer pendant 24 heures sans accepter aucun événement, Pushwoosh met l’intégration en pause. Consultez Intégration en pause.

Délai d’attente

Le délai d’attente par défaut pour une requête est de 60 secondes. Il peut être personnalisé sur demande via le support.

Voir l'exemple

gRPC

Le type de transport gRPC utilise le streaming bidirectionnel pour la transmission des données. Pour en savoir plus, consultez la documentation gRPC.

Un flux est ouvert lorsque l’une des conditions suivantes est remplie :

• Au moins 1 000 événements sont prêts à être livrés
• Une heure s’est écoulée depuis l’ouverture du dernier flux

Le flux est fermé après l’envoi des événements. Cela garantit qu’un nouveau flux n’est pas ouvert pour chaque événement individuel dans un court laps de temps.

Voir la spécification protobuf

Mécanisme de relance Chaque événement inclut un uuid unique. Si un événement échoue :

1. La réponse doit inclure un status différent de "Success"
2. L’uuid original de la requête doit être inclus

Pushwoosh réessayera la livraison en fonction de cette réponse.

Paramètres de connexion

Les options avancées comme TLS, keep-alive, ou les politiques de relance sont configurées manuellement via le support et peuvent nécessiter l’intervention de développeurs.

Activer les événements post

Ce bouton est désactivé par défaut, donc seuls les événements de statistiques de communication sont diffusés. Pour diffuser également les événements que votre application envoie à Pushwoosh via postEvent, activez le bouton Autoriser les événements post.

Dans le champ Événements post qui apparaît, sélectionnez les événements de votre compte à diffuser. Au moins un événement est requis lorsque le bouton est activé. Si votre compte n’a encore envoyé aucun événement, cette liste est vide jusqu’à ce que vous appeliez postEvent au moins une fois.

Note

Les événements post sont envoyés à la même URL de point de terminaison saisie ci-dessus, et l’atteignent quelle que soit la plateforme : les sections Plateformes et Filtres avancés ci-dessous s’appliquent uniquement aux événements de statistiques de communication, et non aux événements post.

Les impressions et les clics in-app transitent également par ce flux d’événements post, sous la forme de PW_InAppShow et PW_InAppClicked. Chacun n’apparaît dans la liste Événements post qu’après s’être déclenché au moins une fois pour le compte, comme tout autre événement post.

Sélectionner les plateformes

Dans la section Plateformes, sélectionnez au moins une plateforme pour activer le streaming d’événements.

Les plateformes prises en charge incluent :

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

Configurer les filtres avancés

Dans la section Filtres avancés, affinez les critères de livraison des événements à l’aide de filtres :

• Événements d’activité en direct : Activez pour recevoir les événements d’activité en direct. Ces événements ne contiennent que des métadonnées incluant live_activity_id.

• Filtres de campagne : Filtrez par code de campagne. Seuls les événements liés à ces campagnes seront livrés.

• Filtres de message : Filtrez par code de message. Seuls les événements liés à ces messages seront livrés.

Après avoir rempli tous les champs obligatoires, cliquez sur le bouton Appliquer pour enregistrer et activer votre intégration.

Note

Les modifications de configuration prendront effet dans les 15 minutes suivant leur soumission.

Conseil

Pour les paramètres avancés tels que les délais d’attente personnalisés ou les configurations gRPC, veuillez contacter le support.

Détails de la requête et exemple

Point de terminaison	https://exampleclientendpoint.com/webhook_endpoint
Requête HTTP	POST
Authentification	Non
Type de requête	Source
Signification de la requête	Envoyer des requêtes au point de terminaison du webhook
En-têtes	Content-Type: application/json

Exemple de corps de requête

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

Attributs

Parmi les événements de statistiques de communication, attributes ne se remplit que pour les événements push, avec un contenu spécifique au canal (Android, iOS, etc.) pour la plateforme à laquelle le push a été envoyé. Les événements E-mail et SMS ne contiennent que les champs de niveau supérieur (event_name, platform, payload, etc.). attributes est null pour ces événements. Dans un objet attributes rempli, les champs en dehors de la plateforme de l’événement sont omis plutôt qu’envoyés comme des valeurs vides. Consultez webhook.proto pour la liste complète des champs.

Un événement post contient ses paires clé/valeur d’attributs dans attributes.event_attributes à la place. message_code et payload restent vides, car un événement post n’est pas lié à un message ou à une campagne.

Attention

attributes.geozone est obsolète : la propriété source est un objet, pas un nombre, donc ce champ n’a jamais contenu de valeur réelle. Lisez la géozone réelle à partir de attributes.geozone_data à la place. L’ancien champ reste dans le contrat pour les clients ayant des stubs gRPC existants.

Réponse Le corps de la réponse est ignoré. Avec le transport HTTP, le code de réponse détermine si les événements sont considérés comme livrés. Un code 2xx signifie que votre point de terminaison les a acceptés.

Synchroniser les appareils désinscrits avec votre système

Si vous conservez votre propre copie de la liste des appareils, par exemple dans un CRM ou une plateforme de données client, diffusez l’événement post PW_DeviceUnregistered pour repérer les appareils que Pushwoosh ne peut plus atteindre. Pushwoosh envoie cet événement lorsqu’un appareil perd son abonnement push. Pour en connaître les raisons, consultez PW_DeviceUnregistered.

Partez d’une intégration déjà configurée, avec une URL de point de terminaison saisie et au moins une plateforme sélectionnée. Ensuite :

1. Dans les paramètres de l’intégration, activez Autoriser les événements post. Consultez Activer les événements post.
2. Dans le champ Événements post, sélectionnez PW_DeviceUnregistered.
3. Pour être également informé des appareils qui obtiennent un jeton push, sélectionnez PW_DeviceRegistered.
4. Cliquez sur Appliquer. La modification prend effet dans les 15 minutes.

Comme tout événement post, PW_DeviceUnregistered n’apparaît dans la liste Événements post qu’après avoir été déclenché au moins une fois pour le compte. Consultez Activer les événements post.

Tenez compte de ces limites lorsque vous traitez les événements :

• Associez les appareils par hwid ou user_id, et non par jeton push. L’événement contient le hwid, le user_id et la plateforme de l’appareil, mais ni le jeton push ni le motif de la désinscription. Un jeton expiré et une désinscription via le SDK sont indiscernables.
• Un nouveau jeton pour le même appareil n’envoie aucun événement. PW_DeviceRegistered n’est déclenché que lorsqu’un appareil sans jeton push en reçoit un. Une liste qui enregistre les appareils par jeton push conserve des jetons qui ne fonctionnent plus, car lorsqu’un appareil obtient un nouveau jeton, aucun des deux événements n’est déclenché.
• Un désabonnement des e-mails ne supprime pas l’appareil. Pour l’e-mail, l’adresse reste sur l’appareil et Pushwoosh la marque seulement comme désabonnée. Lorsque l’utilisateur s’est désabonné via un lien dans un e-mail, attributes.event_attributes contient également le message_code et le campaign_id de cet e-mail.

Certains événements peuvent ne jamais atteindre votre point de terminaison : un événement que votre point de terminaison refuse avec 400, 413 ou 422 est abandonné, tout comme un lot que votre point de terminaison continue de refuser avec un autre code 4xx pendant 2 heures (voir HTTP). Pour repérer ces appareils, exportez régulièrement le segment des appareils que vous ciblez au format CSV et comparez-le à votre liste d’appareils. L’export d’un segment nécessite l’autorisation Personal data dans votre rôle. Si votre point de terminaison continue d’échouer pendant 24 heures, l’intégration est mise en pause et les événements cessent d’arriver. Consultez Intégration en pause.

Intégration en pause

Si les livraisons vers votre point de terminaison HTTP continuent d’échouer pendant 24 heures et que le point de terminaison n’accepte aucun événement pendant cette période, Pushwoosh met l’intégration en pause :

• Pushwoosh cesse d’envoyer des événements au point de terminaison.
• Les événements en attente d’envoi sont abandonnés. Les événements de la période de pause ne sont pas envoyés ultérieurement.
• Le propriétaire du compte reçoit un e-mail concernant la pause. Les paramètres de l’intégration n’affichent pas la pause : cet e-mail est donc la seule notification.

Un événement est considéré comme accepté lorsque votre point de terminaison renvoie un code de réponse 2xx. Les échecs partiels ne mettent pas l’intégration en pause : tout événement accepté relance le décompte de 24 heures. Les intégrations utilisant le transport gRPC ne sont pas mises en pause.

Pour reprendre le streaming :

1. Assurez-vous que votre point de terminaison est joignable et renvoie un code de réponse 2xx.
2. Allez dans Paramètres > Intégrations tierces, trouvez Intégration du streaming d’événements, et cliquez sur Configurer.
3. Cliquez sur Appliquer. Vous n’avez besoin de modifier aucun paramètre. Le streaming reprend dans les 15 minutes.

Comment savoir si l’intégration fonctionne ?

Vous commencerez à recevoir des requêtes de Pushwoosh à votre point de terminaison configuré.