توسيع PrimoCRM

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

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

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

add_action( 'primocrm_contact_tag_added', function ( $contact_id, $tag_id ) {
    // مزامنة تغيير الوسم مع نظام خارجي.
}, 10, 2 );

تسجيل نوع حقل نموذج مخصص

أضف فئة (class) تنفذ واجهة الحقل، ثم قم بتسجيلها في 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. قم بإرجاع قيمة صحيحة (truthy) للإشارة إلى أنك قمت بمعالجة الإرسال، أو كائن WP_Error عند الفشل، أو القيمة الواردة لتمرير الإرسال إلى الخطوة التالية. هذه هي الطريقة التي تتصل بها موفرات خدمة البريد الإلكتروني (ESP) التابعة للنسخة الاحترافية تماماً.

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', 'فشل الإرسال' );
}, 10, 4 );

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

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

قم بتوسيع منشئ شروط الأتمتة عن طريق فلترة primocrm_condition_options. تحتوي القيمة على مصفوفة fields ومصفوفة operators.

add_filter( 'primocrm_condition_options', function ( $opts ) {
    $opts['fields'][] = [
        'key'   => 'life_time_value',
        'label' => 'القيمة الدائمة',
        'type'  => 'number',
    ];
    $opts['operators'][] = [ 'key' => '>', 'label' => 'أكبر من' ];
    return $opts;
} );

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

تسجيل مشغل أتمتة (Automation Trigger)

يتم جمع المشغلات عبر 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; // العثور على جهة اتصال أو إنشاؤها بواسطة البريد الإلكتروني

    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'    => 'النماذج',
            'label'       => 'تم إرسال نموذج SuperForms',
            'description' => 'يتم تشغيله عند إرسال نموذج SuperForms',
            '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 وتشغيل أي أتمتة مطابقة.

إتاحة المشغل في الخطة المجانية

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

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

تسجيل إجراء (Action)

تتبع الإجراءات المخصصة نفس النمط مقابل primocrm_automation_actions (قم بتوسيع فئة الإجراء الأساسية، ووصفها، وتطبيق خطوتها). استخدم الإجراءات الأساسية الموجودة تحت includes/modules/automations/Actions كمراجع عملية، وأضف المفتاح إلى primocrm_free_actions إذا كان يجب أن يكون مجانياً.

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

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

اختيار ما إذا كانت ميزتك مجانية

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

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

ينطبق نفس النمط على primocrm_free_actions، وبالنسبة لحدود العدد، على primocrm_free_limits.

حقن واجهة مسؤول النظام (Admin UI)

لإضافة علامة تبويب للإعدادات أو إجراء صف صفقة (campaign row action) إلى تطبيق الإدارة، استخدم فلاتر جافاسكريبت wp.hooks وهي primocrm.settings.tabs و primocrm.campaigns.rowActions. تعيد هذه الفلاتر أدوات وصفية مع ردود اتصال للربط (mount callbacks) بدلاً من عناصر React، بحيث يمكن لواجهة المستخدم الخاصة بك العرض داخل جذرها الخاص بغض النظر عن إصدار React. اطلع على الإجراءات والفلاتر.