Ampliando PrimoCRM

Todo lo ampliable en PrimoCRM se recopila a través de un filtro de WordPress, por lo que tu complemento se registra en él sin modificaciones en el núcleo. Estos son los patrones que también utilizan las características Pro de primera parte. 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, luego 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 campo del núcleo (un método type() y la lógica de renderizado y sanitizació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ístrala 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 origen, por lo que un complemento defectuoso no puede hacer que el importador falle. El complemento gratuito incluye fuentes CSV y FluentCRM como referencias. 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 WP_Error en caso de fallo, o el valor entrante para pasar el envío de largo. Así es exactamente como se conectan los proveedores ESP Pro.

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

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

Añadir campos y operadores al creador de condiciones

Amplía 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 de 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 activador de automatización

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

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

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 autorregistra en primocrm_automation_triggers

        // Engancha la acción de envío de tu propio complemento de formularios:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Metadatos que listan el activador en el selector de automatizaciones.
    public function getTrigger()
    {
        return [
            'category'    => 'Forms',
            'label'       => 'SuperForms Submitted',
            'description' => 'Fires when a SuperForms form is submitted',
            '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 use este activador.
        $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 complemento de formularios se haya cargado, para que se autorregistre.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

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

Cuando el complemento principal no está instalado

No hay nada que desbloquear: un activador registrado es un activador funcional. Lo que sí debes gestionar es la ausencia de tu propio complemento principal. Registra el activador de todos modos y asígnale una cadena requires_plugin, y PrimoCRM lo listará como no disponible, indicando lo que necesita, en lugar de dejar un vacío silencioso en el selector:

add_filter( 'primocrm_automation_triggers', function ( $triggers ) {
    if ( isset( $triggers['superforms_submitted'] ) || defined( 'SUPERFORMS_VERSION' ) ) {
        return $triggers;
    }
    $triggers['superforms_submitted'] = array(
        'label'           => 'Super Forms Submitted',
        'category'        => 'Forms',
        'description'     => 'Fires when a Super Forms form is submitted',
        'requires_plugin' => 'Super Forms',
    );
    return $triggers;
}, 99 );

Ejecutar con una prioridad tardía para que el activador real, registrado en 10, gane siempre.

Registrar una acción

Las acciones personalizadas siguen la misma estructura contra primocrm_automation_actions (amplía la clase de acción base, descríbela e implementa su paso). Utiliza las acciones del núcleo bajo includes/modules/automations/Actions como referencias de trabajo. La misma regla de requires_plugin se aplica cuando tu acción necesita un complemento principal.

Integración desde un sistema externo

Si el sistema de integración no se ejecuta en el mismo sitio de WordPress, utiliza la API REST en lugar de una clase de activador. Crea o actualiza un contacto con una solicitud 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 activadores son las superficies compatibles y mantienen tu integración funcionando a través de actualizaciones.

Inyectar interfaz de administración

La aplicación de administración es una aplicación de página única de React, y los filtros de wp.hooks son la forma de colocar tus propias pantallas dentro de ella. Hay puntos de unión para pestañas de Ajustes, pestañas de Informes, acciones de filas de campañas, pasos del asistente de campañas, paneles de detalles de campañas y editores de correo electrónico, todos listados en Acciones y Filtros.

Cada uno devuelve descriptores con devoluciones de llamada de montaje en lugar de elementos de React, por lo que tu interfaz de usuario se renderiza en su propia raíz y tu versión de React no tiene por qué coincidir con la de PrimoCRM. No añadas una página de administración independiente; utiliza los puntos de unión y tu característica aterrizará donde el usuario ya está trabajando.