Estendendo o PrimoCRM

Tudo o que é extensível no PrimoCRM é coletado por meio de um filtro do WordPress, para que o seu complemento seja registrado nele sem edições no núcleo. Estes são os padrões que os recursos Pro oficiais também utilizam. 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 tag com um sistema externo.
}, 10, 2 );

Registrar um tipo de campo de formulário personalizado

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

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

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

Registrar uma origem de migração

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

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

O registro descarta preventivamente qualquer item que não implemente a interface de origem, portanto, um complemento defeituoso não pode causar falhas no importador. O plugin Free inclui as origens CSV e FluentCRM como referências. Consulte De Outro CRM.

Fornecer um remetente de e-mail

O envio é direcionado por meio do 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 recebido para repassar o envio. É 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 licença expirada ainda consiga realizar entregas. Consulte Envio e Entregabilidade.

Adicionar campos e operadores ao construtor de condições

Estenda o construtor de condições de automação filtrando primocrm_condition_options. O valor possui um array fields e um array 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ções. O caminho suportado é estender BaseTrigger, que se auto-registra nesse filtro para você. É exatamente assim que funcionam as integrações nativas com Contact Form 7, WPForms e Fluent Forms.

Extenda BaseTrigger, defina um triggerName exclusivo, descreva o gatilho em getTrigger() e conecte o seu próprio evento. Quando o evento for disparado, resolva o contato e insira-o em qualquer automação que utilize o 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; // localizar ou criar 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ções.
    public function getTrigger()
    {
        return [
            'category'    => 'Formulários',
            '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 que utilizam 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 );

O 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.

Disponibilizar o gatilho no plano Free

Novas chaves de gatilho são tratadas como Pro por padrão (bloqueadas por falha), portanto, aparecem como bloqueadas no Free. Se a sua integração deve funcionar no plano Free, adicione a chave dela à lista de permissões do Free:

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

Registrando uma ação

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 e adicione a chave a primocrm_free_actions se ela deve ser gratuita.

Integrando a partir de um sistema externo

Se o sistema de integração não estiver rodando 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 diretamente nas tabelas de banco de dados do PrimoCRM; o endpoint REST e as classes de gatilho são as superfícies suportadas e mantêm sua integração funcionando em futuras atualizações.

Escolher se o seu recurso é gratuito

Tudo o que não estiver na lista de permissões do Free é tratado como Pro (bloqueado por falha). Se você adicionar um gatilho ou ação que deva estar disponível no plano Free, adicione sua chave à lista de permissões.

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

O mesmo padrão se aplica a primocrm_free_actions e, para limites de contagem, a primocrm_free_limits.

Injetar interface de administração

Para adicionar uma aba de Configurações ou uma ação de linha de campanha ao aplicativo administrativo, use os filtros do JavaScript wp.hooks primocrm.settings.tabs e primocrm.campaigns.rowActions. Eles retornam descritores com retornos de chamada (callbacks) de montagem em vez de elementos React, para que a sua interface possa ser renderizada em sua própria raiz, independentemente da versão do React. Consulte Ações e Filtros.

Dica

Quando a sua extensão realizar trabalhos demorados, como chamar uma API externa ou processar muitas linhas, siga o padrão de trabalhador em segundo plano (background worker) do PrimoCRM em vez de bloquear a solicitação. Consulte a Visão Geral para Desenvolvedores.