توسيع PrimoCRM

يتم جمع كل عنصر قابل للتوسيع في PrimoCRM عبر فلتر (مرشح) في ووردبريس، لذلك تقوم الإضافات الخاصة بك بالتسجيل فيه دون أي تعديلات على النواة. هذه هي الأنماط التي تستخدمها أيضاً ميزات الإصدار الاحترافي الأصلي. اطلع على القائمة الكاملة في الإجراءات والفلاتر.

التفاعل مع حدث ما

أبسط عملية توسيع هي التفاعل مع شيء حدث. استخدم خطافات الإجراءات.

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // Sync the tag change to an external system.
}, 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 كمرجع. راجع من نظام إدارة علاقات عملاء آخر.

توفير مرسل بريد إلكتروني

يتم توجيه الإرسال من خلال فلتر primocrm_smtp_send. قم بإرجاع نتيجة صحيحة للدلالة على أنك قمت بمعالجة الإرسال، أو كائن WP_Error عند الفشل، أو القيمة الواردة لتمرير عملية الإرسال. هذه هي الطريقة التي تندمج بها مزودات خدمة البريد الإلكتروني (ESP) الاحترافية تماماً.

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

عندما لا تطالب أي وحدة معالجة بعملية الإرسال، يعود PrimoCRM إلى برنامج مراسلة ووردبريس الافتراضي، بحيث يظل الموقع غير المُكوّن أو منتهي الصلاحية قادراً على التسليم. راجع الإرسال وقابلية التسليم.

إضافة حقول وعوامل تشغيل منشئ الشروط

قم بتوسيع منشئ شروط الأتمتة عن طريق تصفية 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;
} );

هذه هي الطريقة التي يضيف بها الإصدار الاحترافي حقول التجارة الخاصة به. راجع الشروط والتفرع.

تسجيل مشغل أتمتة

يتم جمع المشغلات من خلال 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; // 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 );

يظهر مشغلك الآن في منشئ الأتمتة، ويؤدي تقديم النموذج إلى إنشاء أو تحديث جهة اتصال 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 عندما يحتاج إجراءك إلى إضافة مضيفة.

التكامل من نظام خارجي

إذا كان النظام المدمج لا يعمل على نفس موقع ووردبريس، فاستخدم REST API بدلاً من فئة المشغل. أنشئ أو حدث جهة اتصال باستخدام طلب POST /wp-json/primocrm/v1/contacts موثق. لا تكتب في جداول قاعدة بيانات PrimoCRM مباشرة؛ فالنقطه النهائية لـ REST وفئات المشغل هي الواجهات المدعومة التي تحافظ على عمل تكاملكم عبر التحديثات.

حقن واجهة مستخدم لوحة التحكم

تطبيق لوحة التحكم عبارة عن تطبيق صفحة واحدة بـ React، وتعتبر فلاتر wp.hooks هي الطريقة التي تضع بها شاشاتك الخاصة داخله. توجد نقاط ربط لتبويبات الإعدادات، وتبويبات التقارير، وإجراءات صف الحملة، وخطوات معالج الحملة، ولوحات تفاصيل الحملة ومحررات البريد الإلكتروني، وكلها مدرجة في الإجراءات والفلاتر.

يقوم كل منها بإرجاع مُعرّفات مع ردود اتصال التثبيت بدلاً من عناصر React، لذلك يتم عرض واجهة المستخدم الخاصة بك في الجذر الخاص بها ولا يجب أن تتطابق نسخة React الخاص بك مع نسخة PrimoCRM. لا تقم بإضافة صفحة إدارة مستقلة؛ استخدم نقاط الربط، وستستقر ميزتك حيث يعمل المستخدم بالفعل.

نصيحة

عندما تقوم إضافتك بعمل بطيء، مثل استدعاء واجهة برمجة تطبيقات خارجية أو معالجة العديد من الصفوف، فاتبع نمط عامل الخلفية في PrimoCRM بدلاً من حظر الطلب. راجع نظرة عامة للمطورين.