Menu de la documentationUtiliser les abilities de Vireo dans votre propre code

Utiliser les abilities de Vireo dans votre propre code

Listez les abilities de Vireo, exécutez-les en PHP avec wp_get_ability() ou en REST via l'Abilities API, et gérez les permissions et les erreurs.

Sur cette page

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-totals avec pageviews, visitors, days, avg_daily et, depuis la version 0.13.0, avg_time_on_page_seconds, timed_views et bounce_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 :

  • POST renvoie 405, « Read-only abilities require GET method. »
  • ?input={"limit":1} en une seule chaîne JSON renvoie 400, « input is not of type object ». Utilisez input[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

  • start et end, au format YYYY-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.
  • limit va de 1 à 100. Chaque ability a sa propre valeur par défaut.
  • Certaines abilities demandent une entrée de plus, comme post_id pour get-post-stats ou host pour get-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() une WP_Error avec le code ability_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.