L’Abilities API de WordPress donne à chaque plugin une façon unique de décrire ce qu’il sait faire, pour que d’autres morceaux de code puissent le trouver et l’appeler sans apprendre l’API propre à chaque plugin. Vireo enregistre ses rapports comme des abilities. Votre plugin, un thème, un script WP-CLI ou un outil d’IA peut les appeler et obtenir les mêmes chiffres que le tableau de bord.
Il faut WordPress 6.9 ou une version plus récente, où l’Abilities API fait partie du cœur.
Ce qui est disponible
Les abilities de Vireo sont dans la catégorie vireo-analytics et portent des noms du type vireo-analytics/get-.... Le plugin gratuit en enregistre 23 ; Vireo Pro ajoute les siennes, dont get-revenue-forecast et get-subscriptions pour les boutiques. Toutes sont en lecture seule. La référence de l’API les liste toutes avec leurs paramètres d’entrée.
Pour les lister en PHP :
foreach ( wp_get_abilities() as $ability ) {
if ( 0 === strpos( $ability->get_name(), 'vireo-analytics/' ) ) {
echo $ability->get_name() . ': ' . $ability->get_label() . "\n";
}
}
Ou en REST, avec un mot de passe d’application :
curl -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/wp-abilities/v1/abilities?category=vireo-analytics&per_page=50"
Chaque entrée inclut le schéma d’entrée de l’ability, ce qui vous permet de voir ce qu’elle accepte.
En exécuter une en PHP
$ability = wp_get_ability( 'vireo-analytics/get-top-pages' );
$result = $ability ? $ability->execute( array( 'limit' => 2 ) ) : null;
if ( is_wp_error( $result ) ) {
error_log( $result->get_error_message() );
} else {
foreach ( $result['rows'] as $page ) {
printf( "%d %s\n", $page['pageviews'], $page['title'] );
}
}
execute() renvoie les données sous forme de tableau PHP, ou une WP_Error. En JSON :
{"rows":[
{"post_id":4,"path":"/2026/10/11/how-to-pack-for-a-month/","title":"How to pack for a month","pageviews":6,"visitors":6},
{"post_id":6,"path":"/2026/10/11/pricing/","title":"Pricing","pageviews":3,"visitors":3}
]}
Ce que l’on obtient
Chaque ability renvoie un objet, jamais une liste brute :
- Les abilities qui renvoient une liste la placent sous
rows: statistiques par jour, par heure, pages les plus vues, principaux référents, sources de trafic, pays, événements, vitals, annotations et objectifs. Quand il n’y a rien à signaler, la réponse est{"rows": []}. - Les autres renvoient leur propre objet, comme
get-totalsavecpageviews,visitors,days,avg_dailyet, depuis la version 0.13.0,avg_time_on_page_seconds,timed_viewsetbounce_rate_percent.
La forme est la même que vous appeliez l’ability en PHP, en REST ou via MCP. La référence de l’API indique ce que renvoie chacune.
En exécuter une en REST
Les abilities en lecture seule s’exécutent avec GET sur /wp-json/wp-abilities/v1/abilities/{name}/run. Le nom garde son slash. Passez les entrées en paramètres de requête, sous la forme input[...] :
curl -g -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/wp-abilities/v1/abilities/vireo-analytics/get-totals/run?input[start]=2026-09-12&input[end]=2026-10-11"
{"pageviews":15,"visitors":15,"days":30,"avg_daily":1,"avg_time_on_page_seconds":null,"timed_views":0,"bounce_rate_percent":null}
Le -g de curl l’empêche d’interpréter les crochets comme un motif.
Sans aucune entrée, une ability utilise ses valeurs par défaut :
curl -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/wp-abilities/v1/abilities/vireo-analytics/get-traffic-sources/run"
Ce qui renvoie une erreur :
POSTrenvoie 405, « Read-only abilities require GET method. »?input={"limit":1}en une seule chaîne JSON renvoie 400, « input is not of type object ». Utilisezinput[limit]=1.- Une entrée que l’ability ne déclare pas renvoie 400, par exemple « foo is not a valid property of Object ».
Entrées et valeurs par défaut
startetend, au formatYYYY-MM-DD, couvrent par défaut les 30 derniers jours dans le fuseau horaire de votre site. Contrairement aux routes REST/stats/, ils sont facultatifs.limitva de 1 à 100. Chaque ability a sa propre valeur par défaut.- Certaines abilities demandent une entrée de plus, comme
post_idpourget-post-statsouhostpourget-referrer-detail. La référence indique lesquelles. - Tout le reste est refusé. Une clé d’entrée non déclarée fait renvoyer à
execute()uneWP_Erroravec le codeability_invalid_input, au lieu d’être ignorée.
Permissions
Une ability s’exécute avec l’utilisateur courant, et Vireo vérifie la même capability que le tableau de bord, view_vireo_analytics. En PHP, c’est la personne connectée pour la requête. Pour une tâche cron ou WP-CLI, il n’y a pas d’utilisateur tant que vous n’en définissez pas un :
wp_set_current_user( $user_id_with_dashboard_access );
Sans la capability, execute() renvoie une WP_Error avec le code ability_invalid_permissions, et REST répond 401 ou 403.
Les abilities de Pro demandent aussi une licence Vireo Pro active, et celles des boutiques demandent qu’une boutique compatible soit active : WooCommerce, Easy Digital Downloads, FluentCart, Freemius, Paid Memberships Pro, Restrict Content, MemberPress, LifterLMS, GiveWP ou SureCart. Quand ces conditions ne sont pas réunies, les abilities ne sont pas enregistrées, donc wp_get_ability() renvoie null. get-goals est enregistrée partout par le plugin gratuit et répond dès que Pro est actif.
Pour restreindre encore l’accès, par exemple à une liste d’utilisateurs, utilisez le filtre vireo_abilities_permission_callback. Il peut refuser un appel, mais il ne peut pas l’accorder à un utilisateur sans la capability.
Chaînes venant des visiteurs
Les chemins, les termes de recherche, les référents et les valeurs d’événements peuvent être définis par n’importe qui envoie une requête à votre site. Avant qu’une ability les renvoie, Vireo retire les caractères de contrôle, les retours à la ligne et les crochets, et raccourcit les valeurs trop longues. Vous pouvez les montrer sans risque à un modèle d’IA comme des données, mais dans votre propre HTML, traitez-les comme du texte non fiable : échappez-les comme toute saisie utilisateur.