Estendere PrimoCRM

Tutto ciò che è estendibile in PrimoCRM viene raccolto tramite un filtro di WordPress, quindi il tuo componente aggiuntivo vi si registra senza modifiche al codice principale. Questi sono i pattern utilizzati anche dalle funzionalità Pro di prima parte. Vedi l’elenco completo in Azioni e Filtri.

Reagire a un evento

L’estensione più semplice consiste nel reagire a qualcosa che è accaduto. Usa gli hook delle azioni.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Sincronizza la modifica del tag con un sistema esterno.
}, 10, 2 );

Registrare un tipo di campo di modulo personalizzato

Aggiungi una classe che implementa l’interfaccia dei campi, quindi registrala su primocrm_form_field_types.

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

La tua classe implementa la stessa interfaccia dei tipi di campo principali (un metodo type() e la logica di rendering e sanificazione). Usa i campi integrati in includes/modules/forms/Fields/Types come riferimento. Il nuovo tipo apparirà quindi nella tavolozza del generatore di moduli. Vedi Tipi di campo.

Registrare un’origine di migrazione

Un’origine di migrazione legge un sistema esterno e lo normalizza in contatti, liste, tag e campi personalizzati di PrimoCRM. Implementa il contratto dell’origine e registralo su primocrm_migration_sources.

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

Il registro scarta in modo sicuro qualsiasi elemento che non implementa l’interfaccia dell’origine, in modo che un componente aggiuntivo difettoso non possa mandare in crash l’importatore. Il plugin Free include le origini CSV e FluentCRM come riferimento. Vedi Da un altro CRM.

Fornire un mittente di email

L’invio viene instradato attraverso il filtro primocrm_smtp_send. Restituisci un risultato veridico per indicare che hai gestito l’invio, un WP_Error in caso di errore, oppure il valore in arrivo per passare oltre l’invio. Questo è esattamente il modo in cui si collegano i provider ESP Pro.

add_filter( 'primocrm_smtp_send', function ( $result, $provider, $atts, $settings ) {
    if ( $provider !== 'myesp' ) {
        return $result; // non è nostro; lascia decidere al gestore successivo
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Invio non riuscito' );
}, 10, 4 );

Quando nessun gestore richiede l’invio, PrimoCRM ricorre almailer predefinito di WordPress, in modo che un sito non configurato o scaduto riesca comunque a consegnare. Vedi Invio e recapito.

Aggiungere campi e operatori per il generatore di condizioni

Estendi il generatore di condizioni di automazione filtrando primocrm_condition_options. Il valore contiene un array fields e un array operators.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'Valore a lungo termine',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Maggiore di' ];
    return $opts;
} );

Questo è il modo in cui la versione Pro aggiunge i suoi campi per l’e-commerce. Vedi Condizioni e diramazioni.

Registrare un trigger di automazione

I trigger vengono raccolti tramite primocrm_automation_triggers e compaiono nel selettore di automazione. Il percorso supportato consiste nell’estendere BaseTrigger, che si registra automaticamente in quel filtro per te. Questo è esattamente il modo in cui funzionano le integrazioni integrate con Contact Form 7, WPForms e Fluent Forms.

Estendi BaseTrigger, imposta un triggerName univoco, descrivi il trigger in getTrigger() e metti in ascolto il tuo evento. Quando l’evento si attiva, risolvi il contatto e inseriscilo in qualsiasi automazione che utilizza il tuo trigger.

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

class SuperFormsSubmittedTrigger extends BaseTrigger
{
    use ResolvesContactFromForm; // trova o crea un contatto tramite email

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // si registra automaticamente in primocrm_automation_triggers

        // Associa l'azione di invio del plugin del TUO modulo:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Metadati che elencano il trigger nel selettore di automazione.
    public function getTrigger()
    {
        return [
            'category'    => 'Moduli',
            'label'       => 'SuperForms Inviato',
            'description' => 'Si attiva quando viene inviato un modulo SuperForms',
            'icon'        => 'document-text',
        ];
    }

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

        // Risolvi o crea il contatto (attiva primocrm_contact_created alla creazione).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Inserisce il contatto in ogni automazione attiva che utilizza questo trigger.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

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

// Istanzia una volta, dopo che il tuo plugin di moduli è stato caricato, in modo che si auto-registri.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

Il tuo trigger ora viene visualizzato nel generatore di automazioni e un invio crea o aggiorna il contatto su PrimoCRM ed esegue qualsiasi automazione corrispondente.

Quando il plugin host non è installato

Non c’è nulla da sbloccare: un trigger registrato è un trigger funzionante. Ciò che devi gestire è l’assenza del tuo plugin host. Registra comunque il trigger e dagli una stringa requires_plugin, e PrimoCRM lo elencherà come non disponibile, indicando ciò di cui ha bisogno, invece di lasciare un vuoto silenzioso nel selettore:

add_filter( 'primocrm_automation_triggers', function ( $triggers ) {
    if ( isset( $triggers['superforms_submitted'] ) || defined( 'SUPERFORMS_VERSION' ) ) {
        return $triggers;
    }
    $triggers['superforms_submitted'] = array(
        'label'           => 'Super Forms Inviato',
        'category'        => 'Moduli',
        'description'     => 'Si attiva quando viene inviato un modulo Super Forms',
        'requires_plugin' => 'Super Forms',
    );
    return $triggers;
}, 99 );

Esegui con una priorità tardiva in modo che il trigger reale, registrato a 10, vinca sempre.

Registrazione di un’azione

Le azioni personalizzate seguono la stessa forma rispetto a primocrm_automation_actions (estendi la classe di azione di base, descrivila e implementa il suo passaggio). Usa le azioni principali in includes/modules/automations/Actions come riferimenti funzionanti. La stessa regola requires_plugin si applica quando la tua azione richiede un plugin host.

Integrazione da un sistema esterno

Se il sistema di integrazione non è in esecuzione sullo stesso sito WordPress, usa l’ API REST anziché una classe di trigger. Crea o aggiorna un contatto con una richiesta autenticata POST /wp-json/primocrm/v1/contacts. Non scrivere direttamente sulle tabelle del database di PrimoCRM; l’endpoint REST e le classi di trigger sono le superfici supportate e mantengono la tua integrazione funzionante attraverso gli aggiornamenti.

Inserire l’interfaccia utente di amministrazione

L’applicazione di amministrazione è una single-page app in React, e i filtri di wp.hooks sono il modo in cui inserisci le tue schermate al suo interno. Esistono punti di contatto per le schede Impostazioni, le schede Rapporti, le azioni sulle righe delle campagne, i passaggi della procedura guidata delle campagne, i pannelli dei dettagli delle campagne e gli editor di email, tutti elencati in Azioni e Filtri.

Ognuno restituisce descrittori con callback di montaggio anziché elementi React, in modo che la tua UI venga eseguita nel suo root e la tua versione di React non debba necessariamente corrispondere a quella di PrimoCRM. Non aggiungere una pagina di amministrazione indipendente; usa i punti di contatto e la tua funzionalità si posizionerà esattamente dove l’utente sta già lavorando.

Consiglio

Quando la tua estensione esegue operazioni pesanti, come chiamare un’API esterna o elaborare molte righe, segui il pattern del worker in background di PrimoCRM anziché bloccare la richiesta. Vedi la Panoramica per sviluppatori.