Comment étendre SaveTo Wishlist Pro avec des hooks et l'API REST

Besoin de modifier le comportement de SaveTo Wishlist Pro sans éditer le plugin ? Vous pouvez le faire avec les hooks WordPress et l'API REST du plugin. Cet article répertorie les hooks et les routes que vous pouvez utiliser, avec les arguments que chacun passe et de courts exemples PHP. Tout ce qui est ici s'applique à SaveTo Wishlist Pro 1.0.4.

Avant de commencer

SaveTo Wishlist Pro fonctionne sur SaveTo Wishlist Lite, donc les deux plugins doivent être actifs. Placez votre code de hook dans un petit plugin personnalisé ou un plugin must-use, pas dans les fichiers de SaveTo Wishlist Pro, car les mises à jour du plugin remplacent ces fichiers.

Chaque nom de hook Pro commence par stwpro_. Les hooks du plugin gratuit sont couverts dans Comment étendre SaveTo Wishlist avec des hooks et l'API REST.

Les hooks et filtres ci-dessous sont répertoriés avec les arguments qu'ils passent. Lorsque vous ajoutez un filtre, définissez le nombre d'arguments acceptés pour qu'il corresponde, sinon WordPress ne vous passe que le premier argument. Retournez le premier argument (ou une copie modifiée de celui-ci) de chaque filtre.

Routes de l'API REST

Toutes les routes SaveTo Wishlist Pro utilisent l'espace de noms saveto-wishlist-pro/v1, donc l'URL complète ressemble à https://example.com/wp-json/saveto-wishlist-pro/v1/analytics/products-insight.

Qui peut appeler les routes

Les routes d'analyse, d'automatisation, de listes de souhaits par défaut et de licence servent les propres écrans d'administration du plugin, et elles peuvent changer. Elles ne répondent qu'aux requêtes d'un utilisateur connecté qui a la capacité manage_options (administrateurs par défaut). Toute autre personne reçoit une erreur 401 ou 403. Envoyez la requête avec une session de connexion WordPress normale et un nonce REST, ou avec toute autre méthode d'authentification REST que votre site prend en charge.

Les routes de lecture d'analyse, les routes d'automatisation et les routes de licence ont également une limite de débit par utilisateur. Les requêtes de lecture (GET) obtiennent 300 requêtes par minute. Toutes les autres méthodes obtiennent 60 requêtes par minute. Lorsque vous dépassez la limite, la route renvoie une erreur 429 avec le code rate_limit_exceeded. Vous pouvez modifier les limites avec le filtre stwpro_api_rate_limit, couvert ci-dessous.

Routes d'analyse

Le chemin de base est /analytics.

Les réponses d'analyse sont mises en cache pendant une heure par défaut. Un appel réussi à /analytics/refresh efface le cache, de sorte que la prochaine lecture renvoie des données fraîches.

Cet exemple lit les produits tendance des 30 derniers jours depuis le navigateur, dans un script qui s'exécute sur un écran d'administration WordPress :

wp.apiFetch( {
    path: '/saveto-wishlist-pro/v1/analytics/products-insight?period=30days',
} ).then( ( data ) => {
    console.log( data.most_popular, data.trending, data.recently_added );
} );

Routes d'automatisation

Le chemin de base est /automations. Les quatre routes nécessitent un administrateur et sont limitées en débit.

Routes des listes de souhaits par défaut

Le chemin de base est /default-wishlists. Toutes les routes nécessitent un administrateur.

Route Webhook

La route /webhook/wishlist-created est différente des autres. Elle n'utilise pas de connexion WordPress. Elle utilise la clé API webhook, envoyée dans l'en-tête x-api-key ou le paramètre de requête api_key, et elle répond 401 si la clé est manquante ou incorrecte. Une requête POST déclenche l'action stwpro_wishlist_created. Une requête GET avec un paramètre wishlist_id renvoie une liste de souhaits publique et publiée. Pour les détails de configuration et de sécurité, lisez Comment connecter des outils externes en utilisant les webhooks de liste de souhaits et Comment sécuriser le point de terminaison de l'API webhook SaveTo Wishlist Pro.

Filtres pour les autorisations de route

Par exemple, ceci augmente la limite d'écriture à 120 requêtes par minute :

add_filter( 'stwpro_api_rate_limit', function ( $limit, $request, $is_read ) {
    return $is_read ? $limit : 120;
}, 10, 3 );

Crochets d'automatisation

Les automatisations connectent un déclencheur, comme un produit en promotion, à une action, comme l'envoi d'un e-mail. Ces crochets vous permettent d'ajouter vos propres actions et de modifier ce que les actions intégrées envoient.

Ajouter votre propre action d'automatisation

Deux filtres fonctionnent ensemble. Utilisez stwpro_automation_actions pour ajouter votre action à la liste des actions, et utilisez stwpro_automation_action_handlers pour spécifier quelle fonction l'exécute. Les types d'actions intégrés sont send_email, call_webhook et update_user_meta.

WordPress appelle votre gestionnaire avec cinq arguments : les automatisations actives de ce type pour le déclencheur, les données d'automatisation, l'objet de contexte du déclencheur, un booléen pour la condition de catégorie de produit et un tableau de paramètres supplémentaires.

add_filter( 'stwpro_automation_actions', function ( $actions ) {
    $actions['send_to_crm'] = __( 'Send to my CRM', 'my-plugin' );
    return $actions;
} );

add_filter( 'stwpro_automation_action_handlers', function ( $handlers ) {
    $handlers['send_to_crm'] = 'my_plugin_process_crm_automations';
    return $handlers;
} );

function my_plugin_process_crm_automations( $automations, $automation_data, $context_data, $category_condition, $params ) {
    foreach ( $automations as $automation ) {
        // Send $automation_data to your CRM here.
    }
}

Changer qui reçoit un e-mail d'automatisation

Deux filtres définissent le destinataire de l'e-mail. stwpro_automation_filter_email_to_customer s'exécute une fois par propriétaire de liste de souhaits pour les déclencheurs de produit en promotion et de retour en stock. stwpro_automation_filter_email_to s'exécute pour tous les autres déclencheurs. Avec les deux filtres, une adresse vide ou invalide ignore l'e-mail.

Cet exemple envoie tous les e-mails d'automatisation à une adresse de test sur un site de staging, et ignore les clients qui se sont désabonnés :

add_filter( 'stwpro_automation_filter_email_to', function ( $email_to ) {
    if ( 'production' !== wp_get_environment_type() ) {
        return '[email protected]';
    }
    return $email_to;
}, 10, 1 );

add_filter( 'stwpro_automation_filter_email_to_customer', function ( $email_to, $action_data, $per_customer_data ) {
    $customer_id = (int) ( $per_customer_data['customer_id'] ?? 0 );
    if ( $customer_id && get_user_meta( $customer_id, 'no_wishlist_alerts', true ) ) {
        return '';
    }
    return $email_to;
}, 10, 3 );

Modifier le contenu et les données de l'automatisation

Ces quatre filtres transmettent la valeur que vous filtrez en premier. Les arguments suivants sont l'enregistrement de l'automatisation, les paramètres de l'action, le contexte du déclencheur, les données de la variable résolue et les paramètres supplémentaires. Ils s'exécutent avant que le plugin ne remplace les balises de variable, de sorte que vos modifications peuvent toujours contenir des balises telles que {customer_name}.

Trois filtres supplémentaires ont leurs propres arguments :

Pour les données de variable de chaque déclencheur, utilisez l'un de ces filtres. Ils transmettent tous $variable_data, $trigger_type, $context_data.

• stwpro_automation_data_wishlist_created
• stwpro_automation_data_item_added_to_wishlist
• stwpro_automation_data_item_removed_from_wishlist
• stwpro_automation_data_product_on_sale
• stwpro_automation_data_product_back_in_stock

Hooks d'analyse

Seuils de niveau et de segment client

L'analyse client place chaque client le plus actif dans une catégorie. Un client atteint un niveau lorsque les deux conditions sont remplies : le nombre d'articles sur la liste de souhaits et le montant total dépensé. Le plugin vérifie les niveaux du platine au bronze, et les clients qui ne correspondent à aucun sont considérés comme réguliers. Chaque filtre prend un argument, la valeur par défaut, et renvoie un nombre.

add_filter( 'stwpro_admin_platinum_threshold', function () {
    return 10;
} );

add_filter( 'stwpro_admin_platinum_spent_threshold', function () {
    return 2500;
} );

D'autres filtres d'analyse modifient les segments de clients et les listes affichées sur les écrans d'analyse :

Données analytiques, cache et actualisation

Les seuils ci-dessus sont lus lors du calcul des analyses. Si vous en modifiez un et que l'écran ne change pas, actualisez les analyses afin que les résultats mis en cache soient reconstruits.

Crochets de listes de souhaits par défaut

Ces crochets contrôlent les listes de souhaits que Pro crée automatiquement pour les nouveaux utilisateurs.

add_action( 'stwpro_after_seed_default_wishlists', function ( $user_id, $created, $list ) {
    update_user_meta( $user_id, 'default_wishlists_created', $created );
}, 10, 3 );

Autres hooks

add_filter( 'stwpro_show_powered_by_in_email', '__return_false' );

Questions fréquemment posées

Puis-je appeler les routes d'analyse ou d'automatisation depuis l'extérieur de WordPress ?
Uniquement en tant qu'administrateur connecté. Ces routes vérifient la capacité manage_options et servent les propres écrans du plugin, alors basez-vous sur les hooks ci-dessus pour tout ce qui doit rester stable. Pour les systèmes externes, utilisez la route webhook avec sa clé API.

Pourquoi mes modifications de seuil ne s'affichent-elles pas sur l'écran d'analyse ?
Les résultats d'analyse sont mis en cache, pendant une heure par défaut. Actualisez l'analyse, ou raccourcissez le cache avec les filtres de durée de cache, et les nouveaux seuils s'appliquent.

Besoin d'aide ?

Si vous avez une question ou rencontrez un problème, nous sommes là pour vous aider.

• Utilisateurs premium : Ouvrir un ticket de support
• Utilisateurs gratuits : Visitez notre forum communautaire