API de segmentation (Filtres)

createFilter

POST https://api.pushwoosh.com/json/1.3/createFilter

Crée un nouveau filtre.

Corps de la requête

Nom	Requis	Type	Description
auth*	Oui	string	Jeton d’accès API depuis le panneau de contrôle Pushwoosh.
name*	Oui	string	Nom du filtre.
filter_expression*	Oui	string	Expression construite selon les règles du langage de segmentation. Exemple : T(“City”, eq, “Madrid”) pour segmenter les utilisateurs dont la ville est Madrid.
application	Non	string	Code d’application Pushwoosh qui limite le filtre à une application. Avec la livraison à haute vitesse configurée, cela crée un filtre haute vitesse. Sans elle, cela crée un filtre régulier limité à l’application si votre compte requiert des filtres limités à l’application. Sinon, la requête renvoie une erreur 403 : the application parameter creates a High-Speed Delivery filter, and High-Speed Delivery is not enabled for this account. Omettez le paramètre sauf si l’un de ces cas s’applique à vous.
expiration_date	Non	string	Expiration du filtre. Le filtre sera automatiquement supprimé à la date spécifiée, sauf s’il est utilisé dans un préréglage ou un flux RSS.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

Exemple

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// création de filtres pour les fuseaux horaires
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // Jeton d'accès API depuis le panneau de contrôle Pushwoosh
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

POST https://api.pushwoosh.com/json/1.3/listFilters

Renvoie une liste des segments (filtres) disponibles avec leurs conditions.

Corps de la requête

Nom	Requis	Type	Description
auth*	Oui	string	Jeton d’accès API depuis le panneau de contrôle Pushwoosh.
application*	Oui	string	Code d’application Pushwoosh

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

Exemple

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

POST https://api.pushwoosh.com/json/1.3/deleteFilter

Supprime un filtre existant.

Corps de la requête

Nom	Type	Description
auth*	string	Jeton d’accès API depuis le panneau de contrôle Pushwoosh.
name*	string	Nom du filtre.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Exemple

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // Jeton d'accès API depuis le panneau de contrôle Pushwoosh
    "name": "filter name"
  }
}

exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment

Une requête planifiée. Exporte la liste des abonnés qui correspondent aux conditions de filtre spécifiées.

Corps de la requête

Nom	Requis	Type	Description
auth*	Oui	string	Jeton d’accès API depuis le panneau de contrôle Pushwoosh.
filterExpression*	Oui	string	Conditions du filtre
exportData	Non	array	Données à exporter. Valeurs possibles : "hwids", "push_tokens", "users", "tags", "location", "ad_identifiers". L’inclusion de "location" ajoute les colonnes Latitude et Longitude au CSV exporté. Si exportData est omis, Latitude et Longitude sont inclus dans l’exportation par défaut. "ad_identifiers" ajoute les colonnes MADID, Email SHA256 et Phone SHA256 pour créer un fichier source Google Customer Match ou Meta Custom Audience — voir la note sur l’exportation des identifiants publicitaires ci-dessous.
filterCode	Non	string	Code de filtre prédéfini, peut être utilisé à la place de filterExpression. Peut être obtenu depuis l’API /listFilters ou la barre d’adresse de votre navigateur lors de la visualisation du filtre dans le panneau de contrôle.
applicationCode	Requis si vous utilisez filterExpression ou filterCode.	string	Code d’application Pushwoosh
generateExport	Non	boolean	Par défaut, défini sur true, et une réponse contient un lien pour télécharger le fichier. Si false, seul le nombre d’appareils sera envoyé dans la réponse.
format	Non	string	Définit le format du fichier exporté : “csv” ou “json_each_line”. Si omis, le fichier CSV est généré.
tagsList	Non	array	Spécifie les tags à exporter. Pour n’obtenir que les tags spécifiques, le tableau “exportData” doit contenir la valeur “tags”.
includeWithoutTokens	Non	boolean	Définir sur true pour inclure les utilisateurs sans jetons push dans le fichier exporté. La valeur par défaut est false.

200 Réussi

{
  "task_id": "177458"
}

Exemple

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // requis. Jeton d'accès API depuis le panneau de contrôle Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // conditions du filtre, consultez le guide du langage de segmentation pour la syntaxe
  "filterCode": "12345-67890",                              // code de filtre prédéfini, peut être utilisé à la place de filterExpression
  "applicationCode": "00000-AAAAA",                         // Requis si vous utilisez `filterExpression` ou `filterCode`. Code d'application Pushwoosh. Peut être obtenu depuis la requête API /listFilters ou la barre d'adresse de votre navigateur lors de la visualisation du filtre dans le panneau de contrôle.
  "generateExport": true,                                   // si false, seul le nombre d'appareils sera envoyé dans la réponse ; par défaut, une réponse contient un lien pour télécharger le fichier CSV
  "format": "json_each_line",                               // format du fichier pour présenter les données : "csv" – le fichier .csv est téléchargé ; "json" – un fichier JSON avec tous les appareils exportés ; ou "json_each_line" – une ligne JSON pour chaque appareil. Si non spécifié, CSV est le format par défaut.
  "exportData": ["hwids", "tags"],                          // optionnel. Données à exporter. Valeurs possibles : "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // optionnel. Spécifie les tags à exporter. Pour n'obtenir que les tags spécifiques, la valeur "tags" doit être envoyée dans le tableau "exportData" ou "exportData" doit être vide.
  "includeWithoutTokens": true                              // optionnel. Définir sur true pour inclure les utilisateurs sans jetons push dans le fichier exporté. La valeur par défaut est false.
}

Note

Veuillez trouver la référence du langage de segmentation pour écrire des expressions de filtre ici.

Par exemple, pour exporter tous les abonnés d’une application particulière, utilisez les conditions de filtre suivantes :

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // Jeton d'accès API depuis le panneau de contrôle Pushwoosh
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Expression de filtre référençant le segment de l'application
  "applicationCode": "AAAAA-BBBBB"           // Code d'application Pushwoosh requis
}

Attention

Dans la réponse, vous obtiendrez le task_id pour récupérer le fichier résultant. Ensuite, appelez /exportSegment/result avec ce task_id dans le corps de la requête pour récupérer le fichier résultant.

exportSegment results

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

Récupère le lien vers le CSV avec les résultats de /exportSegment.

Corps de la requête

Nom	Type	Description
auth*	String	Jeton d’accès API depuis le panneau de contrôle Pushwoosh.
task_id*	String	Identifiant reçu dans votre réponse /exportSegment.

200 : OK

{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

Passez le “task_id” reçu dans votre réponse /exportSegment dans le corps de la requête /exportSegment/result.

Dans la réponse /exportSegment/result, vous recevrez le paramètre “filename”. Suivez le lien fourni dans la valeur de ce paramètre pour télécharger automatiquement une archive ZIP. Décompressez l’archive pour récupérer le fichier CSV ou JSON (selon le “format” spécifié dans votre requête) contenant les données des appareils.

À partir du 3 avril 2025, une autorisation sera requise pour télécharger le fichier :

• Si vous téléchargez via un navigateur, connectez-vous simplement au panneau de contrôle Pushwoosh pour y accéder.
• Si vous téléchargez via un logiciel serveur, incluez l’en-tête suivant dans votre requête : Authorization: Token YOUR_API_TOKEN

Si vous spécifiez “exportData” dans votre requête /exportSegment, le fichier téléchargé ne contiendra que les données demandées. Par défaut, le fichier contient les données utilisateur suivantes :

Champ	Description	Exemple de valeur
Hwid	ID matériel d’un appareil	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	User ID associant un appareil à un utilisateur particulier. Si aucun User ID n’est attribué, le HWID est utilisé.	user8192
Push Token	Identifiant unique attribué à un appareil par les passerelles de messagerie cloud. En savoir plus	eeeb2fd7…0fc3547
Type	Type de plateforme (entier).	1
Type (humanized)	Type de plateforme (chaîne de caractères).	iOS
Age	Valeur du tag par défaut Age.	29
ApplicationVersion	Valeur du tag par défaut Application Version.	1.12.0.0
City	Valeur du tag par défaut City.	us, boston
TagName	Valeur d’un tag créé dans votre compte.	TagValue

Exportation des identifiants publicitaires

Ajoutez "ad_identifiers" à exportData pour obtenir un fichier formaté pour être téléversé directement comme source Google Customer Match ou Meta Custom Audience. Cette valeur est uniquement optionnelle — elle n’est jamais incluse par défaut, même lorsque exportData est omis. Elle ne prend effet qu’avec format défini sur "csv". La demander avec "json" ou "json_each_line" ne renvoie pas d’erreur, mais les colonnes ci-dessous sont omises silencieusement de ces formats.

Champ	Description
MADID	ID de publicité mobile (GAID ou IDFA), normalisé en minuscules.
Email SHA256	Hash SHA-256 de l’e-mail de l’utilisateur, mis en minuscules et sans espaces avant le hachage.
Phone SHA256	Hash SHA-256 du numéro de téléphone de l’utilisateur au format E.164 avant le hachage.

Une ligne pour un utilisateur sans aucun des trois identifiants est toujours exportée, avec les colonnes MADID, Email SHA256 et Phone SHA256 laissées vides.

Exporter l’activité de l’application par utilisateur

Note

Les statistiques de campagne renvoient les décomptes d’ouvertures/envois agrégés par heure et par plateforme. Il n’y a pas de colonne hwid ou user_id. Pour voir quels utilisateurs ont ouvert l’application et quand, exportez plutôt un segment basé sur l’événement PW_ApplicationOpen.

PW_ApplicationOpen est uniquement pour les mobiles. Pour un projet web, l’exportation de segment ne renvoie aucune ligne, car l’événement ne s’y déclenche jamais.

1. Construisez une expression de filtre sur l’événement PW_ApplicationOpen, limitée à la période dont vous avez besoin. Utilisez les opérateurs de date d’événement, par exemple “ouvert hier” :

Event("AAAAA-BBBBB", "PW_ApplicationOpen", date daysago eq 1)

2. Appelez /exportSegment avec cette filterExpression, applicationCode, et exportData: ["hwids", "users"].
3. Appelez /exportSegment/result avec le task_id retourné pour télécharger le CSV avec les colonnes Hwid et User ID pour chaque appareil qui a ouvert l’application dans cette fenêtre.

Attention

User ID contient l’identifiant que vous assignez à un appareil. Si vous n’en assignez pas, il se rabat sur le HWID. L’exportation vous indique qui a ouvert l’application dans la fenêtre filtrée. Ce n’est pas un journal d’événements par ouverture avec une colonne d’horodatage, donc construisez un segment par jour (ou par fenêtre) si vous avez besoin d’une granularité journalière.