Intégration Google BigQuery

Assistance d'un développeur requise

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

L’intégration Google BigQuery diffuse les événements de message Pushwoosh sélectionnés vers votre jeu de données BigQuery. Utilisez-la pour analyser les événements du cycle de vie des notifications push, des e-mails et des SMS dans BigQuery, créer des rapports personnalisés ou connecter les données à vos flux d’analyse en aval.

Aperçu de l’intégration

Prérequis

Préparez les éléments suivants avant d’ouvrir la configuration de l’intégration.

1. Utilisez un projet Google Cloud avec la facturation activée. Les crédits d’essai gratuit sont pris en charge. Le bac à sable BigQuery n’est pas suffisant car l’API Storage Write nécessite la facturation.

2. Assurez-vous d’avoir un compte Pushwoosh payant.

Tarification

Vous payez Google directement pour l’utilisation de BigQuery. Pushwoosh ne facture pas l’intégration elle-même.

Pour les tarifs actuels, les niveaux gratuits et les détails régionaux, consultez la tarification de BigQuery.

Les coûts peuvent inclure :

• Ingestion de données : Pushwoosh diffuse les événements avec l’API BigQuery Storage Write.
• Stockage : BigQuery stocke les lignes écrites dans votre table de destination.
• Requêtes : BigQuery facture les requêtes en fonction du modèle de tarification que vous avez choisi.

Type d’intégration

Source : Les données sont envoyées de Pushwoosh à votre jeu de données BigQuery.

Plateformes prises en charge

Pushwoosh diffuse les événements depuis les plateformes iOS, Android, Huawei, Chrome, Safari, Firefox et Web.

Entités synchronisées

Les événements sélectionnés du cycle de vie des notifications push, des e-mails et des SMS sont diffusés vers BigQuery. Pushwoosh écrit une ligne par événement sélectionné dans la table de destination.

Cas d’utilisation

• Analyse des messages en temps quasi réel : analysez les événements du cycle de vie des notifications push, des e-mails et des SMS dans BigQuery peu de temps après leur traitement dans Pushwoosh.
• Rapports personnalisés : créez des rapports BigQuery pour des types d’événements, des applications, des campagnes et des identifiants de message sélectionnés.
• Flux de données en aval : connectez les données d’événements Pushwoosh à vos flux d’analyse, de reporting ou de traitement de données.

Comment fonctionne l’intégration

Après avoir enregistré la configuration, Pushwoosh commence à diffuser les événements de message sélectionnés vers votre table BigQuery en temps quasi réel. Pour chaque événement de message qui transite par Pushwoosh, le système vérifie si le type d’événement est sélectionné dans votre configuration.

Si c’est le cas, Pushwoosh ajoute une nouvelle ligne à votre table de destination. Si la table n’existe pas encore, Pushwoosh la crée automatiquement en utilisant le schéma décrit ci-dessous. Les événements apparaissent généralement dans BigQuery dans les 30 secondes suivant leur traitement dans Pushwoosh.

Configurer l’intégration dans Google Cloud

Choisir un projet Google Cloud

Connectez-vous à la console Google Cloud, puis choisissez ou créez le projet qui détiendra le jeu de données BigQuery.

Conseil

Notez l’ID du projet. Utilisez l’identifiant court, par exemple my-company-12345, et non le nom de projet lisible par l’homme.

Activer les API requises

Dans la console Google Cloud, allez dans API et services → Bibliothèque et activez ces API :

• API BigQuery
• API BigQuery Storage

Pushwoosh utilise ces API pour créer la table de destination et diffuser les événements dans BigQuery.

Créer un compte de service

Pushwoosh utilise le compte de service pour écrire des événements dans votre jeu de données BigQuery.

1. Allez dans IAM et administration → Comptes de service.

2. Cliquez sur Créer un compte de service.

3. Dans Nom du compte de service, saisissez un nom, par exemple, pushwoosh-bigquery.

   Google Cloud génère automatiquement l’ID du compte de service à partir du nom.

   

4. Cliquez sur Créer et continuer.

Accorder les rôles IAM

1. Accordez au compte de service ces rôles IAM :

   • Éditeur de données BigQuery : permet à Pushwoosh de créer la table et d’ajouter des lignes.
   • Utilisateur BigQuery : permet à Pushwoosh d’utiliser l’API Storage Write.
   

Note

Vous pouvez attacher les rôles au niveau du projet ou au niveau du jeu de données. L’accès au niveau du projet est le plus simple à configurer. L’accès au niveau du jeu de données est plus restrictif et recommandé pour la production.

2. Cliquez sur Continuer.

3. Cliquez sur Terminé.

Créer une clé JSON

Pushwoosh utilise la clé JSON pour s’authentifier en tant que compte de service.

1. Ouvrez le compte de service que vous avez créé.

2. Allez dans Clés → Ajouter une clé → Créer une nouvelle clé.

3. Sélectionnez JSON.

Google Cloud télécharge le fichier de clé JSON sur votre ordinateur.

Attention

Conservez le fichier de clé JSON en lieu sûr. Toute personne disposant de ce fichier peut écrire dans votre projet BigQuery. Ne le commitez pas dans git et ne le partagez pas par chat. Pushwoosh stocke la clé chiffrée au repos et ne l’expose pas via l’interface utilisateur après le téléchargement.

Créer un jeu de données

Le jeu de données est l’endroit où Pushwoosh stocke la table des événements diffusés.

1. Dans la console Google Cloud, ouvrez BigQuery.

2. Dans l’Explorateur, sélectionnez le projet que vous avez préparé pour l’intégration.

3. Cliquez sur Créer un jeu de données.

4. Dans ID du jeu de données, saisissez un ID de jeu de données, par exemple pushwoosh_data.

5. Dans Emplacement des données, sélectionnez la région du jeu de données.

6. Cliquez sur Créer un jeu de données.

Configurer l’intégration dans Pushwoosh

1. Dans votre compte Pushwoosh, allez dans Paramètres → Intégrations tierces pour l’application que vous souhaitez connecter.

2. Trouvez Google BigQuery dans la liste des services disponibles et cliquez sur Configurer.

3. Remplissez les champs de configuration.

• ID de projet GCP : saisissez l’ID de projet de Google Cloud, par exemple my-company-12345.
• JSON du compte de service : collez l’intégralité du contenu du fichier de clé JSON que vous avez téléchargé depuis Google Cloud.
• ID du jeu de données : une fois que l’ID de projet GCP et le JSON du compte de service sont remplis, Pushwoosh récupère les jeux de données auxquels votre compte de service peut accéder. Sélectionnez le jeu de données de destination. Si la liste déroulante est vide, vérifiez que le compte de service a l’accès et que le jeu de données existe dans le projet que vous avez spécifié.
• Région du jeu de données : sélectionnez la région de votre jeu de données BigQuery.
• Nom de la table : laissez vide pour utiliser la table par défaut pushwoosh_events. Pushwoosh crée la table avec le schéma décrit ci-dessous.
• Événements : sélectionnez les événements que vous souhaitez diffuser. Vous pouvez modifier cette liste plus tard.
• Diffuser les événements vers BigQuery : activez ce bouton. Désactivez-le pour suspendre la diffusion sans supprimer la configuration.

4. Cliquez sur Tester la connexion.

Pushwoosh valide les informations d’identification auprès de BigQuery sans écrire de données.

Vous pouvez voir l’un de ces statuts de connexion :

• Connexion réussie : les informations d’identification fonctionnent et le compte de service peut accéder au jeu de données.
• auth_failed : la clé JSON est invalide ou révoquée.
• dataset_not_found : l’ID du jeu de données est incorrect ou le compte de service ne peut pas y accéder.
• missing_permission : il manque au compte de service l’un des rôles requis.

5. Cliquez sur Appliquer.

Pushwoosh enregistre la configuration et commence à l’utiliser dans environ 30 secondes. Après cela, les événements sélectionnés commencent à être diffusés vers BigQuery.

Vérifier l’intégration

1. Envoyez une notification push de test, ou déclenchez un autre message qui produit l’un des types d’événements que vous avez sélectionnés.

2. Attendez environ 30 secondes.

3. Ouvrez BigQuery Studio.

4. Allez dans votre projet, puis ouvrez le jeu de données et la table de destination que vous avez configurés. Si vous avez laissé le Nom de la table vide, ouvrez pushwoosh_events.

5. Cliquez sur Aperçu.

Vous devriez voir la ligne de l’événement dans la table.

Schéma de la table

Pushwoosh écrit chaque événement sélectionné comme une ligne distincte dans la table de destination. Pour rendre les requêtes plus rapides et plus faciles à filtrer, la table est partitionnée par jour en utilisant timestamp et clusterisée par app_id et event_kind.

Nom du champ	Type	Description
event_kind	STRING	Type d’événement Pushwoosh, par exemple Push Sent ou Email Opened.
message_id	STRING	Code de message Pushwoosh, tel que l’identifiant de la campagne ou du message.
device_id	STRING	ID matériel Pushwoosh de l’appareil qui a produit l’événement.
user_id	STRING	Votre ID utilisateur externe s’il est connu. Vide pour les appareils anonymes.
timestamp	TIMESTAMP	Heure de l’événement en UTC.
app_id	STRING	Code d’application Pushwoosh.
platform	STRING	Plateforme source, par exemple ios, android ou web.
properties	JSON	Champs d’événements supplémentaires. Utilisez JSON_VALUE pour interroger les champs, comme indiqué ci-dessous.

Interroger les propriétés

La colonne properties stocke des champs d’événements supplémentaires au format JSON. Utilisez JSON_VALUE pour extraire des champs individuels dans vos requêtes.

Par exemple, pour voir quelles campagnes ont généré le plus d’ouvertures au cours des 7 derniers jours, cliquez sur + pour créer une nouvelle requête, collez le SQL ci-dessous, et cliquez sur Exécuter.

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `votre-projet.votre_jeu_de_donnees.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

Pour examiner le nombre d’événements de la dernière heure, exécutez cette requête :

SELECT
  event_kind,
  COUNT(*) AS events
FROM `votre-projet.votre_jeu_de_donnees.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

Mettre à jour l’intégration

Faire une rotation de la clé du compte de service

1. Dans la console Google Cloud, allez dans IAM et administration → Comptes de service.

2. Ouvrez votre compte de service.

3. Allez dans Clés et créez une nouvelle clé JSON.

4. Gardez l’ancienne clé active jusqu’à ce que vous confirmiez que la nouvelle clé fonctionne.

5. Dans Pushwoosh, ouvrez la fenêtre de configuration de Google BigQuery.

6. Collez le nouveau JSON dans JSON du compte de service.

7. Cliquez sur Appliquer.

Pushwoosh valide la nouvelle clé, remplace les informations d’identification stockées et commence à l’utiliser après le prochain rechargement de la configuration, ce qui prend environ 30 secondes.

Après avoir confirmé que les événements continuent de circuler, supprimez l’ancienne clé dans la console Google Cloud.

Changer le jeu de données ou la table de destination

1. Dans Pushwoosh, allez dans Paramètres → Intégrations tierces.

2. Ouvrez les paramètres de Google BigQuery.

3. Sélectionnez un jeu de données différent ou saisissez un nouveau nom de table.

4. Cliquez sur Appliquer.

Pushwoosh rouvre le flux avec la nouvelle destination dans environ 30 secondes. Les lignes déjà écrites restent dans l’ancienne table. Pushwoosh ne remplit pas les données historiques.

Pour conserver la clé du compte de service stockée inchangée lorsque vous mettez à jour d’autres paramètres, laissez JSON du compte de service vide avant de cliquer sur Appliquer.

Dépannage

Problème	Ce qu’il faut vérifier
Le test de connexion échoue avec auth_failed	Le JSON du compte de service est malformé ou la clé a été révoquée dans Google Cloud. Créez une nouvelle clé et collez à nouveau le fichier JSON complet. Le fichier commence par {, se termine par }, et contient un bloc private_key.
Le test de connexion échoue avec dataset_not_found	L’ID du jeu de données est mal orthographié ou n’existe pas dans le projet que vous avez spécifié. Les ID de jeu de données sont sensibles à la casse. Sélectionnez le jeu de données dans la liste déroulante pour éviter les fautes de frappe.
Le test de connexion échoue avec missing_permission	Il manque au compte de service les rôles Éditeur de données BigQuery ou Utilisateur BigQuery. Accordez les deux rôles au niveau du projet, ou accordez-les au niveau du jeu de données pour un accès plus restrictif.
Le test de connexion réussit, mais aucune ligne n’apparaît dans BigQuery	Attendez au moins 30 secondes. Vérifiez que le type d’événement que vous envoyez est sélectionné dans Événements. Par exemple, si seul Push Opened est sélectionné et que personne n’ouvre la notification push, aucune ligne n’apparaît.
La configuration semble correcte, mais la fenêtre modale affiche des champs vides	Rechargez la page. La configuration est récupérée à chaque ouverture de la fenêtre modale et mise en cache pendant 30 secondes par le service sous-jacent. Si vous venez d’enregistrer les paramètres, attendez un moment et ouvrez à nouveau la fenêtre modale.

Note

Pushwoosh enregistre Push Sent, Email Sent et SMS Sent quel que soit le statut de livraison, afin que les agrégats de BigQuery correspondent aux statistiques canoniques de Pushwoosh. Pour Delivered, Opened, Bounced et Unsubscribed, Pushwoosh n’enregistre que les événements réussis.

FAQ

Puis-je utiliser un compte Google Cloud gratuit ?

Oui, tant que la facturation est activée sur le projet. Les crédits d’essai gratuit sont suffisants pour faire fonctionner cette intégration à des volumes typiques pendant toute la période d’essai. Le bac à sable BigQuery sans facturation ne fonctionnera pas car l’API Storage Write nécessite la facturation.

Est-ce que Pushwoosh voit mes données BigQuery ?

Non. Les informations d’identification du compte de service que vous téléchargez autorisent Pushwoosh à écrire dans le jeu de données que vous sélectionnez. Pushwoosh ne lit pas votre jeu de données et n’a aucun accès au reste de votre projet.

Puis-je exporter vers plusieurs jeux de données BigQuery ?

Une seule destination est prise en charge par application. Si vous avez besoin des mêmes événements dans deux jeux de données, configurez une requête planifiée BigQuery dans votre projet pour copier les données de pushwoosh_events dans une autre table.

Puis-je modifier le schéma de la table ?

Le schéma est fixe pour tous les clients. Si vous avez besoin de colonnes supplémentaires, extrayez-les du JSON properties dans vos propres vues ou requêtes planifiées.

Que se passe-t-il si je désactive temporairement l’intégration ?

Désactivez Diffuser les événements vers BigQuery et cliquez sur Appliquer. Pushwoosh arrête d’ajouter des événements pour cette application dans environ 30 secondes.

Les événements produits pendant que l’intégration est désactivée ne sont pas mis en mémoire tampon ni remplis rétroactivement lorsque vous la réactivez. Pushwoosh conserve la configuration, y compris les informations d’identification, le jeu de données et la sélection d’événements.

Comment puis-je supprimer complètement l’intégration ?

Contactez support@pushwoosh.com pour supprimer la configuration de l’intégration. Le jeu de données et les lignes déjà écrites dans BigQuery restent dans votre compte Google Cloud.

Y a-t-il des garanties de livraison ?

L’intégration utilise une livraison “au moins une fois”. En fonctionnement normal, les doublons sont rares. Un redémarrage de processus entre un ajout et une validation peut produire un petit nombre de lignes en double. Dédoublonnez en SQL si votre pipeline en aval nécessite des résultats “exactement une fois”.

Pourquoi n’y a-t-il pas d’événement Push Clicked ?

Pushwoosh expose actuellement Push Sent, Push Delivered et Push Opened pour les notifications push dans cette intégration. Une étape dédiée au clic sur la notification push n’est pas disponible. Les e-mails et les SMS ont leurs propres événements de cycle de vie.