PrimoCRM erweitern

Alles, was in PrimoCRM erweiterbar ist, wird über einen WordPress-Filter erfasst, sodass sich Ihr Add-on ohne Änderungen am Core darin registriert. Dies sind auch die Muster, die von Erst-Anbieter-Pro-Funktionen verwendet werden. Die vollständige Liste finden Sie unter Aktionen und Filter.

Auf ein Ereignis reagieren

Die einfachste Erweiterung besteht darin, auf etwas zu reagieren, das passiert ist. Verwenden Sie die Aktions-Hooks.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Sync the tag change to an external system.
}, 10, 2 );

Einen benutzerdefinierten Formularfeldtyp registrieren

Fügen Sie eine Klasse hinzu, die das Feld-Interface implementiert, und registrieren Sie sie dann bei primocrm_form_field_types.

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

Ihre Klasse implementiert dasselbe Interface wie die Core-Feldtypen (eine type()-Methode sowie Render- und Bereinigungslogik). Verwenden Sie die integrierten Felder unter includes/modules/forms/Fields/Types als Referenz. Der neue Typ erscheint dann in der Palette des Formular-Builders. Siehe Feldtypen.

Eine Migrationsquelle registrieren

Eine Migrationsquelle liest ein externes System aus und normalisiert es in PrimoCRM-Kontakte, -Listen, -Tags und benutzerdefinierte Felder. Implementieren Sie den Quell-Contract und registrieren Sie ihn bei primocrm_migration_sources.

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

Die Registry verwirft fehlerhafte Einträge, die das Quell-Interface nicht implementieren, automatisch, 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-Versender bereitstellen

Der Versand wird über den Filter primocrm_smtp_send geleitet. Geben Sie einen “truthy”-Wert zurück, um anzuzeigen, dass Sie den Versand übernommen haben, bei einem Fehler ein WP_Error-Objekt oder den eingehenden Wert, 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; // not ours; let the next handler decide
    }
    $ok = my_esp_send( $atts['to'], $atts['subject'], $atts['message'], $settings );
    return $ok ? true : new WP_Error( 'myesp_failed', 'Send failed' );
}, 10, 4 );

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

Felder und Operatoren für den Bedingungs-Builder hinzufügen

Erweitern Sie den Automatisierungs-Bedingungs-Builder, indem Sie primocrm_condition_options filtern. 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 value',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'Greater than' ];
    return $opts;
} );

Auf diese Weise fügt Pro seine 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 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 hängen Sie sich an Ihr eigenes Ereignis an. Wenn das Ereignis ausgelöst wird, ermitteln Sie den Kontakt und fügen Sie ihn in eine beliebige Automatisierung ein, 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; // find-or-create a contact by email

    public function __construct()
    {
        $this->triggerName  = 'superforms_submitted';
        $this->actionArgNum = 1;
        parent::__construct(); // self-registers into primocrm_automation_triggers

        // Hook YOUR form plugin's own submit action:
        add_action( 'superforms_after_submit', [ $this, 'onSubmit' ], 10, 1 );
    }

    // Metadata that lists the trigger in the automation picker.
    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'] ?? '';

        // Resolve or create the contact (fires primocrm_contact_created on create).
        $contact_id = $this->resolveContactFromForm( $email, $first, $last, 'superforms' );
        if ( ! $contact_id ) {
            return;
        }

        // Enter the contact into every active automation using this trigger.
        $processor = AutomationProcessor::getInstance();
        foreach ( $processor->findAutomationsByTrigger( $this->triggerName ) as $automation ) {
            $processor->enterContact( $automation->id, $contact_id, $this->triggerName );
        }
    }

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

// Instantiate once, after your form plugin has loaded, so it self-registers.
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.

Den Auslöser im Free-Tarif verfügbar machen

Neue Auslöserschlüssel werden standardmäßig als Pro behandelt (Fail-Closed-Prinzip), sodass sie in der Free-Version als gesperrt angezeigt werden. Wenn Ihre Integration im Free-Tarif funktionieren soll, fügen Sie ihren Schlüssel zur Free-Allowlist hinzu:

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

Registrierung einer Aktion

Benutzerdefinierte Aktionen folgen demselben Schema für primocrm_automation_actions (erweitern Sie die Basis-Aktionsklasse, beschreiben Sie sie und implementieren Sie ihren Schritt). Verwenden Sie die Core-Aktionen unter includes/modules/automations/Actions als funktionierende Referenzen und fügen Sie den Schlüssel zu primocrm_free_actions hinzu, wenn er kostenlos sein soll.

Integration aus einem externen System

Wenn das integrierende System nicht auf derselben WordPress-Website ausgeführt wird, verwenden Sie die REST-API anstelle einer Auslöserklasse. Erstellen oder aktualisieren Sie einen Kontakt über einen 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.

Wählen Sie, ob Ihre Funktion kostenlos ist

Alles, was nicht auf der Free-Allowlist steht, wird als Pro eingestuft (Fail-Closed-Prinzip). Wenn Sie einen Auslöser oder eine Aktion hinzufügen, die im Free-Tarif verfügbar sein soll, fügen Sie deren Schlüssel zur Allowlist hinzu.

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

Dasselbe Muster gilt für primocrm_free_actions und, für Mengeneinschränkungen, für primocrm_free_limits.

Admin-UI einbinden

Um der Admin-App einen Einstellungs-Tab oder eine Kampagnen-Zeilenaktion hinzuzufügen, verwenden Sie die JavaScript wp.hooks-Filter primocrm.settings.tabs und primocrm.campaigns.rowActions. Diese geben Deskriptoren mit Einhänge-Callbacks (Mount Callbacks) anstelle von React-Elementen zurück, sodass Ihre Benutzeroberfläche unabhängig von der React-Version in ihrem eigenen Root gerendert werden kann. Siehe Aktionen und Filter.

Tipp

Wenn Ihre Erweiterung zeitintensive 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.