Расширение PrimoCRM

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

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

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

add_action( 'primocrm_contact_tag_added', function ( $tag_id, $contact_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.

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

Отправка писем маршрутизируется через фильтр primocrm_smtp_send. Возвратите истинное значение, чтобы указать, что вы обработали отправку, объект WP_Error в случае ошибки или исходное значение для передачи отправки дальше. Именно так подключаются провайдеры ESP в версии 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 и запускает любую подходящую автоматизацию.

Доступность триггера в бесплатной версии (Free)

Новые ключи триггеров по умолчанию считаются функциями Pro (безопасный отказ по умолчанию), поэтому в бесплатной версии они отображаются заблокированными. Если ваша интеграция должна работать в бесплатном плане, добавьте ее ключ в список разрешенных для Free:

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

Регистрация действия

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

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

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

Выбор доступности функции в бесплатной версии

Все, что не входит в список разрешенных для Free, считается функциями Pro (безопасный отказ по умолчанию). Если вы добавляете триггер или действие, которые должны быть доступны в бесплатном плане, добавьте их ключ в этот список.

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

Тот же паттерн применяется к primocrm_free_actions, а для ограничения лимитов — к primocrm_free_limits.

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

Чтобы добавить вкладку настроек или действие в строке кампании в административной панели, используйте фильтры JavaScript wp.hooks под именами primocrm.settings.tabs и primocrm.campaigns.rowActions. Они возвращают дескрипторы с колбэками монтирования, а не элементы React, поэтому ваш интерфейс может рендериться в собственный корневой элемент независимо от версии React. Смотрите Действия и фильтры.