Расширение PrimoCRM

Все возможности расширения PrimoCRM собираются через фильтр WordPress, поэтому ваше дополнение регистрируется в системе без изменения основного кода. Именно по такому принципу работают и официальные функции Pro. Полный список смотрите в разделе Экшены и фильтры.

Реакция на событие

Самое простое расширение – это реакция на какое-либо событие. Используйте хуки экшенов.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Синхронизация изменения тега с внешней системой.
}, 10, 2 );

Регистрация пользовательского типа поля формы

Добавьте класс, реализующий интерфейс поля, а затем зарегистрируйте его в фильтре primocrm_form_field_types.

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

Ваш класс реализует тот же интерфейс, что и стандартные типы полей (метод type(), а также логику рендеринга и очистки). В качестве примера используйте встроенные поля в директории includes/modules/forms/Fields/Types. После этого новый тип появится в панели конструктора форм. См. Типы полей.

Регистрация источника миграции

Источник миграции считывает данные из внешней системы и приводит их к формату контактов, списков, тегов и пользовательских полей PrimoCRM. Реализуйте контракт источника и зарегистрируйте его в фильтре primocrm_migration_sources.

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

Реестр автоматически отсеивает всё, что не реализует интерфейс источника, поэтому неисправное дополнение не сможет уронить импортер. Бесплатный плагин поставляется с готовыми источниками CSV и FluentCRM в качестве примеров. См. Из другого CRM.

Предоставление почтового отправителя

Отправка писем маршрутизируется через фильтр primocrm_smtp_send. Верните истинное значение, чтобы показать, что отправка выполнена вами, WP_Error в случае сбоя или входящее значение, чтобы передать отправку дальше. Именно так подключаются провайдеры рассылок в версии Pro.

add_filter( 'primocrm_smtp_send', function ( $result, $provider, $atts, $settings ) {
    if ( $provider !== 'myesp' ) {
        return $result; // не наше; пусть решает следующий обработчик
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Send failed' );
}, 10, 4 );

Если ни один обработчик не взял отправку на себя, PrimoCRM переключается на стандартный почтовый клиент WordPress, поэтому настроенный сайт в любом случае доставит сообщение. См. Отправка и доставляемость.

Добавление полей и операторов конструктора условий

Расширьте конструктор условий автоматизации с помощью фильтра primocrm_condition_options. Значение представляет собой массив с ключами fields и operators.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'Lifetime value',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Greater than' ];
    return $opts;
} );

Именно так в версии Pro добавляются поля коммерческих данных. См. Условия и ветвление.

Регистрация триггера автоматизации

Триггеры собираются через primocrm_automation_triggers и отображаются в средстве выбора автоматизаций. Рекомендуемый подход – расширение класса BaseTrigger, который автоматически регистрируется в этом фильтре за вас. Именно так работают встроенные интеграции с Contact Form 7, WPForms и Fluent Forms.

Расширьте BaseTrigger, задайте уникальный triggerName, опишите триггер в методе getTrigger() и добавьте хук для собственного события. Когда событие срабатывает, найдите или создайте контакт и запустите для него любую автоматизацию, использующую ваш триггер.

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

class SuperFormsSubmittedTrigger extends BaseTrigger
{
    use ResolvesContactFromForm; // поиск или создание контакта по email

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // саморегистрация в primocrm_automation_triggers

        // Хук на действие отправки ВАШЕГО плагина форм:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Метаданные, отображающие триггер в списке выбора автоматизаций.
    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'] ?? '';

        // Находим или создаем контакт (вызывает primocrm_contact_created при создании).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Добавляем контакт во все активные автоматизации, использующие этот триггер.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

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

// Создаем экземпляр после загрузки вашего плагина форм, чтобы произошла саморегистрация.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

Теперь ваш триггер появится в конструкторе автоматизаций, а отправка формы создаст или обновит контакт в PrimoCRM и запустит все подходящие автоматизации.

Если родительский плагин не установлен

Никаких дополнительных преград нет: зарегистрированный триггер является рабочим триггером. О чем действительно стоит позаботиться, так это об отсутствии целевого плагина. Зарегистрируйте триггер в любом случае и укажите для него строковое значение requires_plugin, и тогда PrimoCRM отобразит его как недоступный с указанием необходимых требований, а не оставит пустую строку в списке:

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 );

Выполняйте с низким приоритетом, чтобы настоящий триггер, зарегистрированный на 10-м приоритете, всегда побеждал.

Регистрация экшена

Пользовательские экшены создаются аналогичным образом через primocrm_automation_actions (расширьте базовый класс экшена, опишите его и реализуйте его шаг). Используйте стандартные экшены из директории includes/modules/automations/Actions в качестве рабочих примеров. То же правило с requires_plugin применяется, когда для вашего экшена требуется сторонний плагин.

Интеграция из внешней системы

Если интегрируемая система работает не на том же сайте WordPress, используйте REST API вместо класса триггера. Создайте или обновите контакт с помощью авторизованного запроса POST /wp-json/primocrm/v1/contacts. Не пишите данные напрямую в таблицы базы данных PrimoCRM; эндпоинты REST и классы триггеров являются поддерживаемыми интерфейсами, которые гарантируют работоспособность вашей интеграции после обновлений.

Внедрение интерфейса администратора

Административная панель представляет собой одностраничное приложение на React, а для внедрения ваших собственных экранов используются фильтры wp.hooks. В системе предусмотрены точки подключения для вкладок настроек, вкладок отчетов, действий со строками кампаний, шагов мастера кампаний, панелей детализации кампаний и редакторов писем. Все они перечислены в разделе Экшены и фильтры.

Каждый из них возвращает дескрипторы с колбэками монтирования, а не сами элементы React, поэтому ваш интерфейс рендерится в собственный корневой элемент, и версия React в вашем дополнении не обязана совпадать с версией PrimoCRM. Не добавляйте отдельную страницу администратора; используйте точки подключения, и ваша функция окажется там, где пользователь уже работает.

Совет

Когда ваше расширение выполняет ресурсоемкие задачи, например вызовы внешнего API или обработку большого количества строк, используйте шаблон фонового воркера PrimoCRM вместо блокировки запроса. См. Обзор для разработчиков.