Estendendo o PrimoCRM

Tudo o que é extensível no PrimoCRM é coletado por meio de um filtro do WordPress, para que seu complemento se registre nele sem edições no núcleo. Estes são os padrões que os recursos Pro oficiais também usam. Veja a lista completa em Ações e Filtros.

Reagir a um evento

A extensão mais simples é reagir a algo que aconteceu. Use os ganchos de ação.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Sincroniza a alteração da etiqueta com um sistema externo.
}, 10, 2 );

Registrar um tipo de campo de formulário personalizado

Adicione uma classe que implemente a interface de campo e, em seguida, registre-a em primocrm_form_field_types.

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

Sua classe implementa a mesma interface que os tipos de campo principais (um método type() e lógica de renderização e sanitização). Use os campos internos em includes/modules/forms/Fields/Types como referência. O novo tipo aparecerá na paleta do construtor de formulários. Consulte Tipos de Campo.

Registrar uma fonte de migração

Uma fonte de migração lê um sistema externo e o normaliza em contatos, listas, etiquetas e campos personalizados do PrimoCRM. Implemente o contrato da fonte e registre-o em primocrm_migration_sources.

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

O registro descarta defensivamente qualquer coisa que não implemente a interface da fonte, para que um complemento com falha não possa travar o importador. O plugin Free inclui as fontes CSV e FluentCRM como referências. Consulte De Outro CRM.

Fornecer um remetente de e-mail

O envio é roteado pelo filtro primocrm_smtp_send. Retorne um resultado verdadeiro para indicar que você tratou o envio, um WP_Error em caso de falha ou o valor de entrada para passar o envio adiante. É exatamente assim que os provedores de ESP Pro se conectam.

add_filter( 'primocrm_smtp_send', function ( $result, $provider, $atts, $settings ) {
    if ( $provider !== 'myesp' ) {
        return $result; // não é nosso; deixe o próximo manipulador decidir
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Falha no envio' );
}, 10, 4 );

Quando nenhum manipulador reivindica o envio, o PrimoCRM recorre ao remetente padrão do WordPress, para que um site não configurado ou com assinatura expirada ainda realize entregas. Consulte Envio e Entregabilidade.

Adicionar campos e operadores do construtor de condições

Estenda o construtor de condições de automação filtrando primocrm_condition_options. O valor possui uma matriz fields e uma matriz operators.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'Valor vitalício',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Maior que' ];
    return $opts;
} );

É assim que o Pro adiciona seus campos de comércio. Consulte Condições e Ramificações.

Registrar um gatilho de automação

Os gatilhos são coletados por meio de primocrm_automation_triggers e aparecem no seletor de automação. O caminho suportado é estender BaseTrigger, que se auto-registra nesse filtro para você. É exatamente assim que funcionam as integrações internas do Contact Form 7, WPForms e Fluent Forms.

Estenda BaseTrigger, defina um triggerName exclusivo, descreva o gatilho em getTrigger() e conecte seu próprio evento. Quando o evento for disparado, resolva o contato e insira-o em qualquer automação usando seu gatilho.

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

class SuperFormsSubmittedTrigger extends BaseTrigger
{
    use ResolvesContactFromForm; // localiza ou cria um contato por e-mail

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // se auto-registra em primocrm_automation_triggers

        // Conecte a ação de envio do plugin de formulário SEU:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Metadados que listam o gatilho no seletor de automação.
    public function getTrigger()
    {
        return [
            'category'    => 'Forms',
            'label'       => 'SuperForms Enviado',
            'description' => 'Disparado quando um formulário do SuperForms é enviado',
            'icon'        => 'document-text',
        ];
    }

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

        // Resolve ou cria o contato (dispara primocrm_contact_created na criação).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Insere o contato em todas as automações ativas usando este gatilho.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

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

// Instancie uma vez, após o carregamento do seu plugin de formulário, para que ele se auto-registre.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

Seu gatilho agora aparece no construtor de automações, e um envio cria ou atualiza o contato no PrimoCRM e executa qualquer automação correspondente.

Quando o plugin host não está instalado

Não há nada para desbloquear: um gatilho registrado é um gatilho funcional. O que você precisa gerenciar é a ausência do seu próprio plugin host. Registre o gatilho de qualquer maneira e forneça a ele uma string requires_plugin, e o PrimoCRM o lista como indisponível, informando o que ele precisa, em vez de deixar uma lacuna silenciosa no seletor:

add_filter( 'primocrm_automation_triggers', function ( $triggers ) {
    if ( isset( $triggers['superforms_submitted'] ) || defined( 'SUPERFORMS_VERSION' ) ) {
        return $triggers;
    }
    $triggers['superforms_submitted'] = array(
        'label'           => 'Super Forms Enviado',
        'category'        => 'Forms',
        'description'     => 'Disparado quando um formulário do Super Forms é enviado',
        'requires_plugin' => 'Super Forms',
    );
    return $triggers;
}, 99 );

Execute com uma prioridade tardia para que o gatilho real, registrado em 10, sempre vença.

Registrando uma ação

As ações personalizadas seguem o mesmo formato em relação a primocrm_automation_actions (estenda a classe de ação base, descreva-a e implemente sua etapa). Use as ações principais em includes/modules/automations/Actions como referências funcionais. A mesma regra de requires_plugin se aplica quando sua ação precisa de um plugin host.

Integrando a partir de um sistema externo

Se o sistema de integração não estiver sendo executado no mesmo site WordPress, use a API REST em vez de uma classe de gatilho. Crie ou atualize um contato com um POST /wp-json/primocrm/v1/contacts autenticado. Não escreva nas tabelas de banco de dados do PrimoCRM diretamente; o endpoint REST e as classes de gatilho são as superfícies suportadas e mantêm sua integração funcionando após atualizações.

Injetar IU de administração

O aplicativo de administração é uma aplicação de página única em React, e os filtros wp.hooks são a maneira de inserir suas próprias telas nele. Existem pontos de inserção para abas de Configurações, abas de Relatórios, ações de linha de campanha, etapas do assistente de campanha, painéis de detalhes de campanha e editores de e-mail, todos listados em Ações e Filtros.

Cada um retorna descritores com retornos de chamada de montagem em vez de elementos React, para que sua IU seja renderizada em sua própria raiz e sua versão do React não precise corresponder à do PrimoCRM. Não adicione uma página de administração isolada; use os pontos de inserção e seu recurso chegará onde o usuário já está trabalhando.

Dica

Quando sua extensão realizar trabalhos pesados, como chamar uma API externa ou processar muitas linhas, siga o padrão de trabalhador em segundo plano do PrimoCRM em vez de bloquear a solicitação. Consulte a Visão Geral do Desenvolvedor.