API des Groupes de Contrôle

Un groupe de contrôle est une part réservée des utilisateurs d’une application qui ne reçoit jamais de messages marketing, afin que l’effet de la messagerie puisse être mesuré par rapport à lui. Cette API gère les groupes de contrôle et répond à l’appartenance par utilisateur. Utilisez-la pour reproduire les actions de Paramètres > Groupes de contrôle du Panneau de Contrôle depuis vos propres systèmes, ou pour vérifier si des ID utilisateur spécifiques sont exclus avant un envoi ou une importation.

URL de base

https://rpc-api.svc-nue.pushwoosh.com

Tous les points de terminaison sont servis via HTTPS. Les requêtes et les réponses utilisent application/json sauf indication contraire.

Authentification

Chaque requête doit inclure un en-tête Authorization avec votre jeton d’API Serveur :

Authorization: Api YOUR_API_TOKEN

Conventions

• Nommage des champs : les corps de requête et les paramètres de requête/chemin acceptent le lowerCamelCase (par exemple, controlGroupCode, userIds), et le serveur décode l’une ou l’autre casse. Les réponses sont toujours encodées en utilisant les noms de champs proto, en snake_case (application_id, in_control_group, etc.). Les exemples de réponse et la référence de l’objet Groupe de contrôle ci-dessous utilisent cette casse.
• code : chaque réponse de groupe de contrôle contient son propre code, généré lors de la Création. Passez ce code en tant que controlGroupCode à Get, UpdatePercentage, UpdateCountries, Rename, Disable, Reshuffle, ForceUpdateCalculation, GetCalculationStatus, GetAnalytics, et CheckControlGroupMembership.
• Plusieurs groupes : une application peut avoir plusieurs groupes de contrôle. Chaque groupe activé exclut des utilisateurs de tous les envois marketing dans ses propres pays et son propre tag, indépendamment des autres groupes, et les groupes peuvent se chevaucher. Un envoi ne sélectionne pas de groupe. Le groupe avec un name vide est le groupe original de l’application et fonctionne de la même manière.

Réponses d’erreur

Statut HTTP	Signification
400 Bad Request	Argument invalide, tel qu’un percentage en dehors de 1–20, userIds vide ou dépassant 1 000 entrées, un code de pays non reconnu, scopeValues défini sans scopeTag, scopeTag désignant un tag que le compte n’a pas, ou une entrée de scopeValues que UpdateSettings rejette (voir ci-dessous). Également retourné (en tant que FailedPrecondition sur le réseau) par UpdatePercentage, UpdateCountries, UpdateSettings, Disable, Reshuffle, et Delete sur un groupe de contrôle appartenant à l’exclusion propre d’une campagne, conformément à l’avertissement ci-dessous. Reshuffle seul refuse également de cette manière sur un groupe désactivé (percentage 0).
401 Unauthorized	En-tête Authorization manquant ou invalide.
403 Forbidden	L’application ou le groupe de contrôle n’appartient pas au compte de l’appelant.
404 Not Found	Le groupe de contrôle ou l’application n’a pas été trouvé.
409 Conflict	Create a utilisé un name qui existe déjà dans l’application.
500 Internal Server Error	Échec inattendu côté serveur.

Points de terminaison

Méthode	Chemin	Description
GET	/api/applications/{code}/control_groups	Lister les groupes de contrôle d’une application
POST	/api/applications/{code}/control_groups	Créer un groupe de contrôle
GET	/api/applications/{code}/control_groups/{control_group_code}	Obtenir un seul groupe de contrôle
POST	/api/applications/{code}/control_groups/{control_group_code}	Redimensionner un groupe de contrôle
POST	/api/applications/{code}/control_groups/{control_group_code}/countries	Redéfinir la portée d’un groupe de contrôle à un ensemble de pays
POST	/api/applications/{code}/control_groups/{control_group_code}/settings	Appliquer en un seul appel la taille, la portée par pays et par tag, et le mode de durée de vie
POST	/api/applications/{code}/control_groups/{control_group_code}/display_name	Renommer un groupe de contrôle
POST	/api/applications/{code}/control_groups/{control_group_code}/disable	Désactiver un groupe de contrôle
POST	/api/applications/{code}/control_groups/{control_group_code}/reshuffle	Remanier un groupe de contrôle
POST	/api/applications/{code}/control_groups/{control_group_code}/recalculate	Forcer le recalcul de la taille d’un groupe de contrôle
GET	/api/applications/{code}/control_groups/{control_group_code}/calculation_status	Sonder un calcul de taille en cours
GET	/api/applications/{code}/control_groups/{control_group_code}/analytics	Obtenir les analyses Contrôle vs Traitement
GET	/api/applications/{code}/control_groups/{control_group_code}/cycles	Lister les cycles clos du groupe
POST	/api/applications/{code}/control_groups/{control_group_code}/membership	Vérifier l’appartenance pour un lot d’ID utilisateur
DELETE	/api/applications/{code}/control_groups/{control_group_code}	Supprimer un groupe de contrôle

Lister

Liste chaque groupe de contrôle configuré pour une application, le groupe original sans nom en premier.

GET /api/applications/{code}/control_groups

Paramètres de chemin

Paramètre	Type	Description
code	string	Le code d’application pour lequel lister les groupes de contrôle.

Réponse

Champ	Type	Description
control_groups	tableau d’objets Groupe de contrôle	Chaque groupe de contrôle configuré pour l’application.

Créer

Crée un groupe de contrôle nommé pour une application et le retourne avec son code généré. Le nouveau groupe exclut des utilisateurs de tous les envois marketing dans ses propres pays et son propre tag, parallèlement aux autres groupes activés de l’application.

POST /api/applications/{code}/control_groups

Corps de la requête

Paramètre	Type	Requis	Description
code	string	Oui	Le code d’application dans lequel créer le groupe.
name	string	Oui	Nom du groupe, jusqu’à 64 caractères et sans deux-points. Doit être unique au sein de l’application. Fait partie de la clé d’appartenance, il ne change donc jamais.
percentage	integer	Oui	Taille de l’exclusion en pourcentage, de 1 à 20.
segment	string	Non	Expression Seglang sur laquelle mesurer le groupe. Omettre pour mesurer sur l’ensemble de la base.
countries	tableau de chaînes	Non	Codes de pays ISO-3166-1 alpha-2 en minuscules pour limiter la portée de l’exclusion. Omettre pour tous les pays. Les codes sont insensibles à la casse en entrée.
scopeTag	string	Non	Un tag de type chaîne ou booléen auquel limiter l’exclusion, combiné par ET avec countries. Omettre pour aucune portée par tag. Voir Portée par tag ci-dessous.
scopeValues	tableau de chaînes	Voir note	Valeurs de scopeTag qui placent un utilisateur dans la portée. Requis si scopeTag est défini, et doit être vide dans le cas contraire.
displayName	string	Non	Nom affiché par le Control Panel, jusqu’à 64 caractères. Omettre pour afficher name.

Exemple de requête

{
  "code": "XXXXX-XXXXX",
  "name": "Q3 holdout",
  "percentage": 10
}

Réponse

Retourne { "group": { ... } }, le nouvel objet Groupe de contrôle.

Obtenir

Retourne un groupe de contrôle par son code, avec sa taille d’exclusion, sa génération et les décomptes d’utilisateurs associés.

GET /api/applications/{code}/control_groups/{control_group_code}

Paramètres de chemin

Paramètre	Type	Description
code	string	Le code d’application auquel le groupe appartient.
control_group_code	string	Le code du groupe de contrôle.

Réponse

Champ	Type	Description
group	Objet Groupe de contrôle	Le groupe de contrôle demandé.
total_users	integer	Tous les utilisateurs de l’application.
control_group_users	integer	Utilisateurs actuellement exclus.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS ou TASK_STATUS_COMPLETED.
has_data	boolean	Indique si les chiffres de taille mis en cache sont déjà disponibles.

UpdatePercentage

Définit le pourcentage d’exclusion (1–20) d’un groupe de contrôle. Le redimensionnement conserve tous les membres existants : l’exclusion s’agrandit ou se rétrécit autour d’eux plutôt que d’être redéfinie. Remplacé par UpdateSettings, qui applique en un seul appel la taille, la portée et le mode de durée de vie, mais toujours pris en charge.

POST /api/applications/{code}/control_groups/{control_group_code}

Attention

Une campagne peut créer son propre échantillon témoin, qui est aussi un groupe de contrôle mais n’apparaît pas dans Lister. Ce point de terminaison, ainsi que UpdateCountries, UpdateSettings, Disable, Reshuffle et Delete, refusent tous de le modifier, retournant à la place 400 Bad Request (« le groupe de contrôle appartient à une campagne et ne peut être modifié »).

Corps de la requête

Paramètre	Type	Requis	Description
percentage	integer	Oui	Nouvelle taille d’exclusion en pourcentage, de 1 à 20.

Réponse

Un objet vide en cas de succès : {}.

UpdateCountries

Définit les pays auxquels un groupe de contrôle est limité. La modification de la portée redémarre la mesure de l’uplift, car la population comparée change. L’exclusion elle-même n’est pas redéfinie. Remplacé par UpdateSettings, qui définit aussi une portée par tag, mais toujours pris en charge.

POST /api/applications/{code}/control_groups/{control_group_code}/countries

Corps de la requête

Paramètre	Type	Requis	Description
countries	tableau de chaînes	Oui	Codes de pays ISO-3166-1 alpha-2 en minuscules. Une liste vide élargit le groupe à tous les pays. Les codes sont insensibles à la casse en entrée.

Exemple de requête

{
  "countries": ["us", "ca", "gb"]
}

Réponse

Un objet vide en cas de succès : {}.

UpdateSettings

Applique en un seul appel la taille, la portée par pays et par tag, et le mode de durée de vie d’un groupe de contrôle. Une modification qui change les utilisateurs exclus ou la durée de l’exclusion (taille, portée, mode, période de renouvellement ou date de fin) clôt le cycle en cours et en démarre un nouveau. Envoyer les valeurs actuelles ne change rien. Refuse un groupe de contrôle appartenant à l’exclusion propre d’une campagne, de la même manière que UpdatePercentage.

POST /api/applications/{code}/control_groups/{control_group_code}/settings

Corps de la requête

Paramètre	Type	Requis	Description
percentage	integer	Oui	Taille de l’exclusion en pourcentage, de 1 à 20.
countries	tableau de chaînes	Non	Codes de pays ISO-3166-1 alpha-2 en minuscules. Une liste vide élargit le groupe à tous les pays.
scopeTag	string	Non	Un tag de type chaîne ou booléen auquel limiter l’exclusion, combiné par ET avec countries. Vide supprime la portée par tag. Voir Portée par tag ci-dessous.
scopeValues	tableau de chaînes	Voir note	Valeurs de scopeTag qui placent un utilisateur dans la portée. Requis si scopeTag est défini, et doit être vide dans le cas contraire.
mode	string	Non	Durée de vie de l’appartenance : CONTROL_GROUP_MODE_PERMANENT (par défaut), CONTROL_GROUP_MODE_AUTO_REFRESH ou CONTROL_GROUP_MODE_EXPERIMENT.
refreshPeriodDays	integer	Voir note	Nombre de jours entre deux redéfinitions, de 7 à 365. Requis avec CONTROL_GROUP_MODE_AUTO_REFRESH, et doit être omis dans le cas contraire.
endsAt	string (RFC 3339)	Voir note	Moment où une expérience s’arrête, au moins 30 jours à l’avance. Requis avec CONTROL_GROUP_MODE_EXPERIMENT, et doit être omis dans le cas contraire.

Chaque champ est appliqué tel qu’envoyé, comme pour UpdateCountries : un countries vide élargit le groupe à tous les pays, et un scopeTag vide supprime la portée par tag.

Réponse

Retourne { "group": { ... } }, l’objet Groupe de contrôle mis à jour.

Portée par tag

Un groupe de contrôle peut exclure uniquement les utilisateurs dont la valeur d’un tag de type chaîne ou booléen fait partie d’un ensemble que vous choisissez, combiné par ET avec countries si les deux sont définis. Définissez-la avec Create ou UpdateSettings.

• scopeTag désigne le tag ; vide signifie aucune portée par tag. Il ne peut pas être Country : la portée par pays utilise countries, pas un tag.
• scopeValues liste les valeurs de scopeTag qui sont dans la portée. Au moins une est requise lorsque scopeTag est défini, et aucune ne peut être répétée. Les valeurs d’un tag de type chaîne ne peuvent pas être des chaînes vides. Les valeurs d’un tag booléen doivent chacune être "true" ou "false".
• Un appareil sans valeur pour scopeTag est hors de la portée, comme un appareil sans tag Country.
• L’appartenance elle-même ne change pas : la formule qui attribue les utilisateurs n’est pas modifiée par la portée. La portée par tag et par pays sont toutes deux une vérification par appareil appliquée en plus, qui restreint les appareils d’un utilisateur sélectionné réellement exclus, et non les utilisateurs que la formule sélectionne.
• Un tag de niveau utilisateur est copié sur chacun des appareils de cet utilisateur lorsqu’il est défini ; la vérification au niveau de l’appareil ci-dessus couvre donc aussi les tags de niveau utilisateur, et pas seulement ceux de niveau appareil.
• Modifier scopeTag, ou modifier scopeValues en tant qu’ensemble (un simple changement d’ordre ne compte pas), clôt le cycle en cours avec CONTROL_GROUP_CYCLE_CLOSE_REASON_RESCOPED, comme pour une modification de countries. Désactiver un groupe conserve sa portée par tag, comme il conserve déjà countries.

Renommer

Définit le nom que le Control Panel affiche pour un groupe de contrôle. name fait partie de la clé d’appartenance et ne change pas : le groupe conserve donc les mêmes utilisateurs et son cycle en cours.

POST /api/applications/{code}/control_groups/{control_group_code}/display_name

Corps de la requête

Paramètre	Type	Requis	Description
code	string	Oui	Le code d’application auquel le groupe appartient.
controlGroupCode	string	Oui	Le code du groupe de contrôle.
displayName	string	Non	Nouveau nom, jusqu’à 64 caractères et unique au sein de l’application. Envoyez une chaîne vide pour afficher à nouveau name.

Réponse

Retourne { "group": { ... } }, l’objet Groupe de contrôle renommé.

Désactiver

Désactive un groupe de contrôle, en le conservant ainsi que sa génération, de sorte que sa réactivation restaure la même exclusion plutôt que d’en créer une nouvelle.

POST /api/applications/{code}/control_groups/{control_group_code}/disable

Réponse

Un objet vide en cas de succès : {}.

Remanier

Redéfinit l’exclusion d’un groupe de contrôle en incrémentant sa génération. C’est le seul moyen d’obtenir un échantillon différent : l’appartenance est déterministe, donc la désactivation et la réactivation reproduisent exactement le même.

POST /api/applications/{code}/control_groups/{control_group_code}/reshuffle

Attention

Refuse un groupe désactivé (percentage 0) avec 400 Bad Request (« le groupe de contrôle n’est pas activé »). Le remanier ne ferait que déplacer une exclusion dans laquelle personne ne se trouve, et consommerait silencieusement une génération.

Réponse

Champ	Type	Description
generation	integer	La génération du groupe après le remaniement.

ForceUpdateCalculation

Démarre un nouveau décompte de la taille d’un groupe de contrôle. Les chiffres précédemment mis en cache continuent d’être servis jusqu’à la fin du nouveau décompte. Sondez GetCalculationStatus pour suivre la progression.

POST /api/applications/{code}/control_groups/{control_group_code}/recalculate

Réponse

Un objet vide en cas de succès : {}.

GetCalculationStatus

Sonde uniquement les décomptes d’utilisateurs changeants d’un groupe de contrôle pendant l’exécution d’un calcul de taille.

GET /api/applications/{code}/control_groups/{control_group_code}/calculation_status

Réponse

Champ	Type	Description
total_users	integer	Tous les utilisateurs de l’application.
control_group_users	integer	Utilisateurs exclus, comptés sur l’ensemble de l’application.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS ou TASK_STATUS_COMPLETED.
has_data	boolean	Indique si les chiffres de taille mis en cache sont disponibles.

GetAnalytics

Retourne les analyses précalculées Contrôle vs Traitement pour un groupe de contrôle.

Note

Une tâche nocturne calcule les analyses de chaque groupe activé, nommé ou non. Un groupe mesuré sur un segment n’a pas encore d’analyses.

GET /api/applications/{code}/control_groups/{control_group_code}/analytics

Paramètres de requête

Paramètre	Type	Requis	Description
windowDays	string	Non	Préréglage de la fenêtre rétrospective : WINDOW_DAYS_3, WINDOW_DAYS_7 ou WINDOW_DAYS_30.

Réponse

Champ	Type	Description
events	tableau d’objets	Une entrée par événement suivi, chacune avec event, treatment et control (users, conversions, conversion_rate, events_per_user), uplift_pct, incremental_events, percent_of_treatment, z_score, p_value, confidence_pct et significance (SIGNIFICANCE_NOT_ENOUGH_DATA, SIGNIFICANCE_NOT_SIGNIFICANT ou SIGNIFICANCE_SIGNIFICANT).

ListControlGroupCycles

Liste les cycles clos d’un groupe de contrôle, du plus récent au plus ancien. Chaque cycle est l’appartenance avec laquelle le groupe a fonctionné entre deux modifications de paramètres, avec les paramètres à partir desquels il a été défini. Le cycle en cours (actuel) ne figure pas dans cette liste. Ses paramètres se trouvent sur l’objet Groupe de contrôle lui-même.

GET /api/applications/{code}/control_groups/{control_group_code}/cycles

Réponse

Champ	Type	Description
cycles	tableau d’objets Cycle de groupe de contrôle	Du plus récent au plus ancien.

Objet Cycle de groupe de contrôle

Champ	Type	Description
cycle_number	integer	Séquentiel au sein du groupe ; le cycle_number du groupe lui-même est celui qui suit le dernier cycle clos ici.
mode	string	Mode de durée de vie dans lequel le groupe a fonctionné pendant ce cycle : CONTROL_GROUP_MODE_PERMANENT, CONTROL_GROUP_MODE_AUTO_REFRESH ou CONTROL_GROUP_MODE_EXPERIMENT.
generation	integer	La génération du groupe pendant ce cycle.
percentage	integer	Taille de l’exclusion pendant ce cycle.
countries	tableau de chaînes	Portée par pays pendant ce cycle ; vide correspond à tous les pays.
started_at / ended_at	string (RFC 3339)	Période pendant laquelle ce cycle a fonctionné.
close_reason	string	Raison pour laquelle le cycle s’est terminé : CONTROL_GROUP_CYCLE_CLOSE_REASON_ROLLOVER, _EXPIRED, _RESHUFFLED, _RESIZED, _RESCOPED, _MODE_CHANGED ou _DISABLED.
scope_tag	string	Tag auquel l’exclusion du cycle était limitée, combiné par ET avec countries. Vide en l’absence de portée par tag et pour tout cycle clos avant l’existence de la portée par tag, même si le groupe en a eu une par la suite.
scope_values	tableau de chaînes	Valeurs de scope_tag qui placent un utilisateur dans la portée pendant ce cycle ; défini uniquement avec scope_tag.

CheckControlGroupMembership

Indique pour chaque ID utilisateur s’il est actuellement exclu par un groupe de contrôle. L’appartenance est calculée à partir de l’ID seul. Aucun enregistrement utilisateur n’est lu, donc un ID que l’application n’a jamais vu reçoit également une réponse, et un groupe désactivé répond false pour chaque ID plutôt qu’une erreur. Un groupe avec une portée par pays ou par tag n’exclut un utilisateur que si l’un de ses appareils est dans cette portée ; un ID jamais vu (aucun appareil) renvoie donc false ici, alors que le même ID renverrait true sur un groupe sans portée. Utilisez cette méthode au lieu d’exporter tout le groupe pour vérifier les utilisateurs d’un envoi ou d’une importation spécifique.

POST /api/applications/{code}/control_groups/{control_group_code}/membership

Corps de la requête

Paramètre	Type	Requis	Description
userIds	tableau de chaînes	Oui	ID utilisateur à vérifier, au maximum 1 000 par appel.

Exemple de requête

{
  "userIds": ["user-1", "user-2", "user-3"]
}

Réponse

Champ	Type	Description
users	tableau d’objets	Une entrée par ID demandé, dans l’ordre où ils ont été fournis (doublons inclus). Chacune a user_id (chaîne) et in_control_group (booléen).

Exemple de réponse

{
  "users": [
    { "user_id": "user-1", "in_control_group": false },
    { "user_id": "user-2", "in_control_group": true },
    { "user_id": "user-3", "in_control_group": false }
  ]
}

Supprimer

Supprime entièrement un groupe de contrôle. Il cesse d’exclure des utilisateurs, et ses statistiques ne peuvent plus être ouvertes. Les autres groupes de l’application continuent de fonctionner.

DELETE /api/applications/{code}/control_groups/{control_group_code}

Attention

Cette action est irréversible. Pour cesser d’exclure des utilisateurs tout en conservant le groupe, sa génération et son historique, désactivez-le plutôt.

Réponse

Un objet vide en cas de succès : {}.

Objet Groupe de contrôle

Champ	Type	Description
code	string	Code du groupe de contrôle (format XXXXX-XXXXX), stable pendant toute la durée de vie du groupe.
name	string	Nom du groupe, partie de la clé d’appartenance. Vide correspond au groupe original, sans nom, de l’application.
display_name	string	Nom affiché par le Control Panel. Vide affiche name, et le groupe sans nom comme Global.
segment	string	Expression Seglang sur laquelle le groupe est mesuré ; vide correspond à l’ensemble de la base.
percentage	integer	Taille de l’exclusion en pourcentage, de 1 à 20. Zéro signifie que le groupe est désactivé.
enabled	boolean	Indique si le groupe exclut actuellement des utilisateurs.
generation	integer	Incrémenté à chaque remaniement ; 0 signifie jamais remanié.
last_modified_at	string (RFC 3339)	Date de la dernière modification des paramètres du groupe.
last_modified_by	string	E-mail de l’utilisateur qui a modifié le groupe en dernier.
application_id	integer	ID numérique de l’application, la première partie de la clé d’appartenance <application_id>:<generation>:<name>:<user_id> que CheckControlGroupMembership hache pour décider si un utilisateur est exclu.
countries	tableau de chaînes	Codes de pays ISO-3166-1 alpha-2 en minuscules auxquels l’exclusion est limitée. Vide correspond à tous les pays.
scope_tag	string	Tag auquel l’exclusion est limitée, combiné par ET avec countries ; vide signifie aucune portée par tag. Voir Portée par tag.
scope_values	tableau de chaînes	Valeurs de scope_tag qui placent un utilisateur dans la portée ; un tag booléen utilise "true" et "false".

Sujets connexes

Groupes de contrôle (guide produit)

API de Segmentation (Filtres)