Cómo extender SaveTo Wishlist Pro con hooks y la API REST

¿Necesitas cambiar cómo se comporta SaveTo Wishlist Pro sin editar el plugin? Puedes hacerlo con hooks de WordPress y la API REST del plugin. Este artículo enumera los hooks y rutas que puedes usar, con los argumentos que cada uno pasa y breves ejemplos de PHP. Todo aquí se aplica a SaveTo Wishlist Pro 1.0.4.

Antes de empezar

SaveTo Wishlist Pro se ejecuta sobre SaveTo Wishlist Lite, por lo que ambos plugins deben estar activos. Coloca tu código de hook en un pequeño plugin personalizado o en un plugin indispensable, no en los archivos de SaveTo Wishlist Pro, porque las actualizaciones del plugin reemplazan esos archivos.

Cada nombre de hook de Pro comienza con stwpro_. Los hooks para el plugin gratuito se cubren en Cómo extender SaveTo Wishlist con hooks y la API REST.

Los hooks y filtros a continuación se enumeran con los argumentos que pasan. Cuando agregues un filtro, establece el número de argumentos aceptados para que coincida, o WordPress solo te pasará el primer argumento. Devuelve el primer argumento (o una copia modificada del mismo) de cada filtro.

Rutas de la API REST

Todas las rutas de SaveTo Wishlist Pro usan el espacio de nombres saveto-wishlist-pro/v1, por lo que la URL completa se ve así https://example.com/wp-json/saveto-wishlist-pro/v1/analytics/products-insight.

Quién puede llamar a las rutas

Las rutas de análisis, automatización, listas de deseos predeterminadas y licencias sirven a las propias pantallas de administración del plugin y pueden cambiar. Solo responden a solicitudes de un usuario conectado que tenga la capacidad manage_options (administradores por defecto). Cualquier otra persona recibe un error 401 o 403. Envía la solicitud con una sesión de inicio de sesión normal de WordPress y un nonce REST, o con cualquier otro método de autenticación REST que tu sitio admita.

Las rutas de lectura de análisis, las rutas de automatización y las rutas de licencias también tienen un límite de tasa por usuario. Las solicitudes de lectura (GET) obtienen 300 solicitudes por minuto. Todos los demás métodos obtienen 60 solicitudes por minuto. Cuando te excedes, la ruta devuelve un error 429 con el código rate_limit_exceeded. Puedes cambiar los límites con el filtro stwpro_api_rate_limit, cubierto a continuación.

Rutas de análisis

La ruta base es /analytics.

Las respuestas de análisis se almacenan en caché durante una hora por defecto. Una llamada exitosa a /analytics/refresh limpia la caché, por lo que la siguiente lectura devuelve datos actualizados.

Este ejemplo lee los productos de tendencia de los últimos 30 días desde el navegador, en un script que se ejecuta en una pantalla de administración de 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 );
} );

Rutas de automatización

La ruta base es /automations. Las cuatro rutas requieren un administrador y tienen límites de tasa.

Rutas de listas de deseos por defecto

La ruta base es /default-wishlists. Todas las rutas requieren un administrador.

Ruta de webhook

La ruta /webhook/wishlist-created es diferente de las otras. No utiliza un inicio de sesión de WordPress. Utiliza la clave API del webhook, enviada en la cabecera x-api-key o el parámetro de consulta api_key, y responde 401 cuando la clave falta o es incorrecta. Una solicitud POST activa la acción stwpro_wishlist_created. Una solicitud GET con un parámetro wishlist_id devuelve una lista de deseos pública y publicada. Para obtener detalles de configuración y seguridad, lee Cómo conectar herramientas externas usando webhooks de listas de deseos y Cómo proteger el punto final de la API de webhook de SaveTo Wishlist Pro.

Filtros para la comprobación de permisos de administrador

Por ejemplo, esto aumenta el límite de escritura a 120 solicitudes por minuto:

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

Ganchos de automatización

Las automatizaciones conectan un disparador, como un producto que sale a la venta, a una acción, como el envío de un correo electrónico. Estos ganchos te permiten añadir tus propias acciones y cambiar lo que envían las acciones integradas.

Añade tu propia acción de automatización

Dos filtros trabajan juntos. Usa stwpro_automation_actions para añadir tu acción a la lista de acciones, y usa stwpro_automation_action_handlers para decir qué función la ejecuta. Los tipos de acción integrados son send_email, call_webhook y update_user_meta.

WordPress llama a tu manejador con cinco argumentos: las automatizaciones activas de ese tipo para el disparador, los datos de la automatización, el objeto de contexto del disparador, un booleano para la condición de categoría de producto y una matriz de parámetros adicionales.

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.
    }
}

Cambia quién recibe un correo electrónico de automatización

Dos filtros establecen el destinatario del correo electrónico. stwpro_automation_filter_email_to_customer se ejecuta una vez por propietario de la lista de deseos para el producto en oferta y el producto de vuelta en stock disparadores. stwpro_automation_filter_email_to se ejecuta para todos los demás disparadores. Con ambos filtros, una dirección vacía o inválida omite el correo electrónico.

Este ejemplo envía todos los correos electrónicos de automatización a una dirección de prueba en un sitio de staging, y omite a los clientes que se dieron de baja:

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 );

Cambia el contenido y los datos de la automatización

Estos cuatro filtros pasan el valor que filtras primero. Los siguientes argumentos son el registro de automatización, la configuración de la acción, el contexto del disparador, los datos de la variable resuelta y los parámetros adicionales. Se ejecutan antes de que el plugin reemplace las etiquetas de variable, por lo que tus cambios aún pueden contener etiquetas como {customer_name}.

Tres filtros más tienen sus propios argumentos:

Para los datos de variables de cada disparador, usa uno de estos filtros. Todos pasan $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

Ganchos de análisis

Umbrales de nivel y segmento de cliente

La analítica de clientes clasifica a cada cliente destacado en una categoría. Un cliente alcanza una categoría cuando se cumplen ambos números: la cantidad de artículos en la lista de deseos y el importe total gastado. El plugin comprueba las categorías de platino a bronce, y los clientes que no cumplen ninguna son clientes habituales. Cada filtro toma un argumento, el valor predeterminado, y devuelve un número.

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

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

Otros filtros de analítica cambian los segmentos de clientes y las listas que se muestran en las pantallas de analítica:

Datos de analítica, caché y actualización

Los umbrales anteriores se leen cuando se calculan las analíticas. Si cambias uno y la pantalla no cambia, actualiza las analíticas para que los resultados en caché se reconstruyan.

Ganchos de listas de deseos predeterminadas

Estos ganchos controlan las listas de deseos que Pro crea automáticamente para los nuevos usuarios.

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

Otros ganchos

add_filter( 'stwpro_show_powered_by_in_email', '__return_false' );

Preguntas frecuentes

¿Puedo llamar a las rutas de análisis o automatización desde fuera de WordPress?
Solo como administrador conectado. Estas rutas comprueban la capacidad manage_options y sirven a las pantallas propias del plugin, así que utiliza los hooks anteriores para cualquier cosa que deba permanecer estable. Para sistemas externos, utiliza la ruta del webhook con su clave API.

¿Por qué mis cambios de umbral no se muestran en la pantalla de análisis?
Los resultados del análisis se almacenan en caché, durante una hora por defecto. Actualiza el análisis, o acorta la caché con los filtros de duración de caché, y se aplicarán los nuevos umbrales.

¿Necesitas ayuda?

Si tienes alguna pregunta o encuentras algún problema, estamos aquí para ayudarte.

• Usuarios premium: Abrir un ticket de soporte
• Usuarios gratuitos: Visita nuestro foro comunitario