Estendere PrimoCRM

Tutto ciò che è estendibile in PrimoCRM viene raccolto tramite un filtro di WordPress, in modo che il tuo componente aggiuntivo vi si registri senza modifiche al codice principale. Questi sono i pattern utilizzati anche dalle funzionalità Pro native. 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 palette del costruttore 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 protettivo qualsiasi elemento che non implementi 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, o 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 è il 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 ripiega sul mailer predefinito di WordPress, in modo che un sito non configurato o scaduto continui 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 Pro aggiunge i suoi campi commerciali. Vedi Condizioni e diramazioni.

Registrare un trigger di automazione

I trigger vengono raccolti tramite primocrm_automation_triggers e compaiono nel selettore delle automazioni. 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 per Contact Form 7, WPForms e Fluent Forms.

Estendi BaseTrigger, imposta un triggerName univoco, descrivi il trigger in getTrigger() e aggancia il tuo evento. Quando l’evento si attiva, risolvi il contatto e inseriscilo in qualsiasi automazione che utilizzi 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

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

    // Metadati che elencano il trigger nel selettore delle automazioni.
    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;
        }

        // Inserisci 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 registri automaticamente.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

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

Rendere il trigger disponibile nel piano Free

Le nuove chiavi dei trigger sono trattate come Pro per impostazione predefinita (bloccate in caso di fail), quindi appaiono bloccate nel piano Free. Se la tua integrazione deve funzionare nel piano Free, aggiungi la sua chiave all’elenco consentito di Free:

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

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 e aggiungi la chiave a primocrm_free_actions se deve essere gratuita.

Integrazione da un sistema esterno

Se il sistema di integrazione non è in esecuzione sullo stesso sito WordPress, usa le 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 nelle tabelle del database di PrimoCRM; l’endpoint REST e le classi di trigger sono le interfacce supportate e mantengono la tua integrazione funzionante attraverso gli aggiornamenti.

Scegliere se la tua funzionalità è gratuita

Tutto ciò che non si trova nell’elenco consentito di Free viene trattato come Pro (bloccato in caso di fail). Se aggiungi un trigger o un’azione che dovrebbe essere disponibile nel piano Free, aggiungi la sua chiave all’elenco consentito.

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

Lo stesso pattern si applica a primocrm_free_actions e, per i limiti di conteggio, a primocrm_free_limits.

Iniettare l’interfaccia utente di amministrazione

Per aggiungere una scheda Impostazioni o un’azione per riga di campagna all’app di amministrazione, usa i filtri JavaScript wp.hooks primocrm.settings.tabs e primocrm.campaigns.rowActions. Questi restituiscono descrittori con callback di montaggio anziché elementi React, in modo che la tua interfaccia utente possa essere visualizzata nella propria radice indipendentemente dalla versione di React. Vedi Azioni e Filtri.

Consiglio

Quando la tua estensione esegue operazioni onerose, 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.