PrimoCRM erweitern

Alles, was in PrimoCRM erweitert werden kann, wird über einen WordPress-Filter erfasst, sodass sich Ihr Add-on ohne Kernänderungen darin registriert. Dies sind auch die Muster, die von First-Party-Pro-Funktionen verwendet werden. Die vollständige Liste finden Sie unter Aktionen und Filter.

Auf ein Ereignis reagieren

Die einfachste Erweiterung besteht darin, auf ein eingetretenes Ereignis zu reagieren. Verwenden Sie die Aktions-Hooks.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Tag-Änderung mit einem externen System synchronisieren.
}, 10, 2 );

Einen benutzerdefinierten Formularfeldtyp registrieren

Fügen Sie eine Klasse hinzu, die das Felddefinitionsschnittstelle implementiert, und registrieren Sie diese dann unter primocrm_form_field_types.

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

Ihre Klasse implementiert dieselbe Schnittstelle wie die Core-Feldtypen (eine type()-Methode sowie Rendering- und Bereinigungslogik). Nutzen Sie die integrierten Felder unter includes/modules/forms/Fields/Types als Referenz. Der neue Typ erscheint daraufhin in der Formular-Builder-Palette. Weitere Informationen finden Sie unter Feldtypen.

Eine Migrationsquelle registrieren

Eine Migrationsquelle liest ein externes System aus und normalisiert dessen Daten in PrimoCRM-Kontakte, -Listen, -Tags und -Benutzerfelder. Implementieren Sie den Quellvertrag und registrieren Sie ihn unter primocrm_migration_sources.

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

Die Registry verwirft automatisch alles, was die Quell-Schnittstelle nicht implementiert, sodass ein fehlerhaftes Add-on den Importer nicht zum Absturz bringen kann. Das Free-Plugin liefert CSV- und FluentCRM-Quellen als Referenz mit. Siehe Aus einem anderen CRM.

Einen E-Mail-Absender bereitstellen

Der Versand wird über den Filter primocrm_smtp_send geleitet. Geben Sie einen “Truthy”-Wert zurück, um zu signalisieren, dass Sie den Versand übernommen haben, bei einem Fehler ein WP_Error oder den Eingangswert, um den Versand weiterzuleiten. Genau so binden sich die Pro-ESP-Anbieter ein.

add_filter( 'primocrm_smtp_send', function ( $result, $provider, $atts, $settings ) {
    if ( $provider !== 'myesp' ) {
        return $result; // nicht von uns; den nächsten Handler entscheiden lassen
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Versand fehlgeschlagen' );
}, 10, 4 );

Wenn kein Handler den Versand beansprucht, greift PrimoCRM auf den Standard-WordPress-Mailer zurück, sodass eine unkonfigurierte oder abgelaufene Website weiterhin E-Mails zustellt. Siehe Versand und Zustellbarkeit.

Bedingungen-Builder-Felder und -Operatoren hinzufügen

Erweitern Sie den Automatisierungs-Bedingungen-Builder durch Filtern von primocrm_condition_options. Der Wert enthält ein fields-Array und ein operators-Array.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'Lifetime-Wert',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Größer als' ];
    return $opts;
} );

Auf diese Weise fügt Pro seine E-Commerce-Felder hinzu. Siehe Bedingungen und Verzweigungen.

Einen Automatisierungsauslöser registrieren

Auslöser werden über primocrm_automation_triggers gesammelt und erscheinen im Automatisierungs-Auswahlmenü. Der empfohlene Weg ist die Erweiterung von BaseTrigger, der sich automatisch selbst in diesem Filter registriert. Genau so funktionieren die integrierten Integrationen für Contact Form 7, WPForms und Fluent Forms.

Erweitern Sie BaseTrigger, legen Sie einen eindeutigen triggerName fest, beschreiben Sie den Auslöser in getTrigger() und verknüpfen Sie Ihr eigenes Ereignis. Wenn das Ereignis eintritt, ermitteln Sie den Kontakt und übergeben ihn an jede Automatisierung, die Ihren Auslöser verwendet.

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

class SuperFormsSubmittedTrigger extends BaseTrigger
{
    use ResolvesContactFromForm; // Kontakt per E-Mail finden oder erstellen

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // registriert sich automatisch in primocrm_automation_triggers

        // Verknüpfen Sie die Absende-Aktion IHRES Formular-Plugins:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Metadaten, die den Auslöser im Automatisierungs-Auswahlmenü auflisten.
    public function getTrigger()
    {
        return [
            'category'    => 'Formulare',
            'label'       => 'SuperForms gesendet',
            'description' => 'Wird ausgelöst, wenn ein SuperForms-Formular abgesendet wird',
            'icon'        => 'document-text',
        ];
    }

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

        // Kontakt ermitteln oder erstellen (löst primocrm_contact_created beim Erstellen aus).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Den Kontakt in jede aktive Automatisierung einfügen, die diesen Auslöser verwendet.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

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

// Einmal instanziieren, nachdem Ihr Formular-Plugin geladen wurde, damit es sich selbst registriert.
add_action( 'plugins_loaded', function () {
    new SuperFormsSubmittedTrigger();
}, 20 );

Ihr Auslöser wird nun im Automatisierungs-Builder angezeigt, und eine Einsendung erstellt oder aktualisiert den PrimoCRM-Kontakt und führt alle passenden Automatisierungen aus.

Wenn das Host-Plugin nicht installiert ist

Es gibt nichts freizuschalten: Ein registrierter Auslöser ist ein funktionierender Auslöser. Sie müssen lediglich den Fall behandeln, dass Ihr eigenes Host-Plugin abwesend ist. Registrieren Sie den Auslöser trotzdem und geben Sie ihm eine requires_plugin-Zeichenkette, woraufhin PrimoCRM ihn als nicht verfügbar auflistet und angibt, was er benötigt, anstatt eine stille Lücke im Auswahlmenü zu hinterlassen:

add_filter( 'primocrm_automation_triggers', function ( $triggers ) {
    if ( isset( $triggers['superforms_submitted'] ) || defined( 'SUPERFORMS_VERSION' ) ) {
        return $triggers;
    }
    $triggers['superforms_submitted'] = array(
        'label'           => 'Super Forms gesendet',
        'category'        => 'Formulare',
        'description'     => 'Wird ausgelöst, wenn ein Super Forms-Formular abgesendet wird',
        'requires_plugin' => 'Super Forms',
    );
    return $triggers;
}, 99 );

Führen Sie dies mit einer späten Priorität aus, damit der echte Auslöser, der bei 10 registriert wurde, immer gewinnt.

Eine Aktion registrieren

Benutzerdefinierte Aktionen folgen demselben Muster für primocrm_automation_actions (erweitern Sie die Basis-Aktionsklasse, beschreiben Sie sie und implementieren Sie ihren Schritt). Nutzen Sie die Core-Aktionen unter includes/modules/automations/Actions als funktionierende Referenzen. Dieselbe requires_plugin-Regel gilt, wenn Ihre Aktion ein Host-Plugin benötigt.

Integration aus einem externen System

Wenn das integrierende System nicht auf derselben WordPress-Website läuft, verwenden Sie die REST-API anstelle einer Auslöserklasse. Erstellen oder aktualisieren Sie einen Kontakt mit einem authentifizierten POST /wp-json/primocrm/v1/contacts. Schreiben Sie nicht direkt in die Datenbanktabellen von PrimoCRM; der REST-Endpunkt und die Auslöserklassen sind die unterstützten Schnittstellen und sorgen dafür, dass Ihre Integration auch nach Updates funktionsfähig bleibt.

Admin-UI einbinden

Die Admin-App ist eine Single-Page-Anwendung in React, und wp.hooks-Filter sind das Mittel der Wahl, um Ihre eigenen Bildschirme darin zu platzieren. Es gibt Schnittstellen für Einstellungs-Tabs, Berichte-Tabs, Tabellenreihen-Aktionen für Kampagnen, Kampagnen-Assistenten-Schritte, Kampagnendetail-Panels und E-Mail-Editoren, die alle unter Aktionen und Filter aufgeführt sind.

Jede davon gibt Descriptoren mit Mount-Callbacks anstelle von React-Elementen zurück, sodass Ihre Benutzeroberfläche in ihrem eigenen Root gerendert wird und Ihre React-Version nicht mit der von PrimoCRM übereinstimmen muss. Fügen Sie keine eigenständige Admin-Seite hinzu; nutzen Sie die Schnittstellen, damit sich Ihre Funktion dort einfügt, wo der Benutzer ohnehin arbeitet.

Tipp

Wenn Ihre Erweiterung rechenintensive Aufgaben ausführt, wie etwa das Aufrufen einer externen API oder das Verarbeiten vieler Zeilen, folgen Sie dem Background-Worker-Muster von PrimoCRM, anstatt die Anfrage zu blockieren. Siehe die Entwicklerübersicht.