Extender PrimoCRM

Todo lo extensible en PrimoCRM se recopila a través de un filtro de WordPress, por lo que tu complemento se registra en él sin necesidad de modificar el núcleo. Estos son los patrones que también utilizan las características de Pro de primer nivel. Consulta la lista completa en Acciones y Filtros.

Reaccionar a un evento

La extensión más sencilla es reaccionar a algo que ha sucedido. Utiliza los ganchos de acción.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Sincronizar el cambio de etiqueta con un sistema externo.
}, 10, 2 );

Registrar un tipo de campo de formulario personalizado

Añade una clase que implemente la interfaz de campo y, a continuación, regístrala en primocrm_form_field_types.

add_filter( 'primocrm_form_field_types', function ( $fields ) {
    $fields['signature'] = MySignatureField::class;
    return $fields;
} );

Tu clase implementa la misma interfaz que los tipos de campos del núcleo (un método type() y lógica de renderizado y depuración). Utiliza los campos integrados en includes/modules/forms/Fields/Types como referencia. El nuevo tipo aparecerá entonces en la paleta del creador de formularios. Consulta Tipos de campo.

Registrar una fuente de migración

Una fuente de migración lee un sistema externo y lo normaliza en contactos, listas, etiquetas y campos personalizados de PrimoCRM. Implementa el contrato de la fuente y regístralo en primocrm_migration_sources.

add_filter( 'primocrm_migration_sources', function ( $sources ) {
    $sources['mailpoet'] = new MailPoetSource();
    return $sources;
} );

El registro descarta de forma defensiva cualquier elemento que no implemente la interfaz de fuente, por lo que un complemento defectuoso no puede hacer que el importador falle. El plugin Gratuito incluye fuentes CSV y de FluentCRM como referencia. Consulta Desde otro CRM.

Proporcionar un remitente de correo electrónico

El envío se enruta a través del filtro primocrm_smtp_send. Devuelve un resultado verdadero para indicar que has gestionado el envío, un objeto WP_Error en caso de fallo, o el valor entrante para pasar el envío al siguiente. Así es exactamente como se conectan los proveedores ESP de Pro.

add_filter( 'primocrm_smtp_send', function ( $result, $provider, $atts, $settings ) {
    if ( $provider !== 'myesp' ) {
        return $result; // no es nuestro; deja que el siguiente gestor decida
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Envío fallido' );
}, 10, 4 );

Cuando ningún gestor reclama el envío, PrimoCRM recurre al sistema de correo predeterminado de WordPress, por lo que un sitio no configurado o caducado sigue entregando mensajes. Consulta Envío y entregabilidad.

Añadir campos y operadores del creador de condiciones

Extiende el creador de condiciones de automatización filtrando primocrm_condition_options. El valor tiene una matriz fields y una matriz operators.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'Valor del tiempo de vida',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Mayor que' ];
    return $opts;
} );

Así es como Pro añade sus campos de comercio. Consulta Condiciones y ramificación.

Registrar un disparador de automatización

Los disparadores se recopilan a través de primocrm_automation_triggers y aparecen en el selector de automatizaciones. La ruta recomendada es extender BaseTrigger, que se registra automáticamente en ese filtro por ti. Así es exactamente como funcionan las integraciones integradas de Contact Form 7, WPForms y Fluent Forms.

Extiende BaseTrigger, establece un triggerName único, describe el disparador en getTrigger() y vincula tu propio evento. Cuando se dispare el evento, resuelve el contacto e introdúcelo en cualquier automatización que utilice tu disparador.

use PrimoCRM\modules\automations\Triggers\BaseTrigger;
use PrimoCRM\modules\automations\Triggers\Forms\ResolvesContactFromForm;
use PrimoCRM\modules\automations\AutomationProcessor;

class SuperFormsSubmittedTrigger extends BaseTrigger
{
    use ResolvesContactFromForm; // buscar o crear un contacto por correo electrónico

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // se registra automáticamente en primocrm_automation_triggers

        // Vincular la acción de envío propia de TU plugin de formularios:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Metadatos que enumeran el disparador en el selector de automatizaciones.
    public function getTrigger()
    {
        return [
            'category'    => 'Formularios',
            'label'       => 'SuperForms Envíado',
            'description' => 'Se dispara cuando se envía un formulario de SuperForms',
            'icon'        => 'document-text',
        ];
    }

    public function onSubmit( $submission )
    {
        $email = $submission['email'] ?? '';
        $first = $submission['first_name'] ?? '';
        $last  = $submission['last_name'] ?? '';

        // Resolver o crear el contacto (dispara primocrm_contact_created al crear).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Introducir el contacto en cada automatización activa que utilice este disparador.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

    public function handle( ...$args ) {}
}

// Instanciar una vez, después de que tu plugin de formularios se haya cargado, para que se auto-registre.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

Tu disparador ahora aparece en el creador de automatizaciones, y un envío crea o actualiza el contacto de PrimoCRM y ejecuta cualquier automatización coincidente.

Hacer que el disparador esté disponible en el plan Gratuito

Las nuevas claves de los disparadores se tratan como Pro por defecto (fallo cerrado), por lo que aparecen bloqueadas en el plan Gratuito. Si tu integración debe funcionar en el plan Gratuito, añade su clave a la lista blanca de gratuitos:

add_filter( 'primocrm_free_triggers', function ( $keys ) {
    $keys[] = 'superforms_submitted';
    return $keys;
} );

Registrar una acción

Las acciones personalizadas siguen la misma estructura con primocrm_automation_actions (extiende la clase de acción base, descríbela e implementa su paso). Utiliza las acciones principales bajo includes/modules/automations/Actions como referencias funcionales y añade la clave a primocrm_free_actions si debe ser gratuita.

Integración desde un sistema externo

Si el sistema que se integra no se está ejecutando en el mismo sitio de WordPress, utiliza la API REST en lugar de una clase de disparador. Crea o actualiza un contacto con una petición autenticada POST /wp-json/primocrm/v1/contacts. No escribas directamente en las tablas de la base de datos de PrimoCRM; el extremo REST y las clases de disparadores son las superficies compatibles y mantienen tu integración funcionando a través de las actualizaciones.

Elegir si tu característica es gratuita

Todo lo que no esté en la lista blanca de gratuitos se trata como Pro (fallo cerrado). Si añades un disparador o una acción que deba estar disponible en el plan Gratuito, añade su clave a la lista blanca.

add_filter( 'primocrm_free_triggers', function ( $keys ) {
    $keys[] = 'my_custom_trigger';
    return $keys;
} );

El mismo patrón se aplica a primocrm_free_actions y, para los límites de recuento, primocrm_free_limits.

Inyectar interfaz de administración

Para añadir una pestaña de Configuración o una acción de fila de campaña a la aplicación de administración, utiliza los filtros de JavaScript wp.hooks llamados primocrm.settings.tabs y primocrm.campaigns.rowActions. Estos devuelven descriptores con devoluciones de llamada de montaje en lugar de elementos de React, por lo que tu interfaz puede renderizarse en su propia raíz independientemente de la versión de React. Consulta Acciones y Filtros.

Consejo

Cuando tu extensión realice trabajos pesados, como llamar a una API externa o procesar muchas filas, sigue el patrón de trabajador en segundo plano de PrimoCRM en lugar de bloquear la solicitud. Consulta la Descripción general para desarrolladores.