التحليلات والأحداث

لا لوحات بيانات في LaRecipe، ولا يخزّن أي حركة زيارات. بل يغذّي الأدوات التي تستخدمها أصلًا. لتضيف أداة، اذكرها تحت integrations.analytics في مدخل المجموعة في config/larecipe.php، فيطبع LaRecipe وسوم السكربت الخاصة بها في رأس كل صفحة من المجموعة:

'sets' => [
    'docs' => [
        // route, source and access as usual
        'integrations' => ['analytics' => [
            'plausible' => ['domain' => 'docs.acme.dev'],
        ]],
    ],
],

وسوم السكربت ترى القرّاء الذين تشغّل متصفحاتهم JavaScript. أما الوكلاء فلا يشغّلون سكربت التحليلات أبدًا، لذا يطلق LaRecipe أيضًا حدث Laravel لكل صفحة ونسخة Markdown و llms.txt ومهارة واستدعاء MCP يقدّمه. استمع إلى هذه الأحداث لترى كل حركة الزيارات لديك.

يشغّل هذا الموقع GA4: يضبط ملف config/larecipe.php الخاص به المفتاح ga4 تحت integrations.analytics في مجموعة docs.

تكاملات التحليلات

يفحص LaRecipe كل قيمة مقابل الشكل الذي يستخدمه مزوّدها قبل أن تصل إلى الصفحة، ويُسقط الوسم الذي لا تناسب قيمه. يجب أن تكون مصادر السكربتات عناوين https، ولا يمكن لأي إعداد أن يضيف كودًا مضمّنًا إلى الصفحة. وحين يضبط تطبيقك قيمة nonce لسياسة أمان المحتوى (Content Security Policy) عبر LaRecipe::useCspNonce()، يحملها كل وسم.

ويجوز لمجموعة المستودع أيضًا أن تعرّف التكاملات في ملف larecipe.json الخاص بها، بالمفاتيح نفسها.

{
  "integrations": {
    "analytics": {
      "plausible": { "domain": "docs.acme.dev" }
    }
  }
}

تقييم الصفحات

تنتهي كل صفحة بالسؤال «هل كانت هذه الصفحة مفيدة؟»، مع «نعم» و «لا»، وتعليق اختياري يصل إلى 2,000 حرف. تحتاج هذه الأداة إلى JavaScript. ولا يخزّن LaRecipe أي إجابة. بل إن كل إجابة:

1. تطلق FeedbackSubmitted مع الصفحة والإجابة والتعليق ونوع الطلب، و source مضبوط على reader. وتطلق أداة MCP submit_feedback الحدث نفسه و source مضبوط على agent، فتصل تقييمات الوكلاء بالطريقة نفسها.
2. تُبلَّغ إلى أداة التحليلات، حين يكون هناك تكامل مضبوط. تحصل التحليلات على الصفحة والإصدار واللغة والإجابة والمصدر. أما التعليق فلا يذهب إلا إلى المستمعين في Laravel لديك.

أوقف هذه الأداة بضبط feedback.enabled على false في config/larecipe.php. فيزيل ذلك الأداة ومسارها وأداة MCP submit_feedback.

تقييم الإجابات

حين يكون Ask AI مفعّلًا، تحمل كل إجابة مكتملة زرّي إعجاب وعدم إعجاب. يُرسل التصويت إلى مسار التقييم نفسه مع السؤال الذي كانت الإجابة له، فيصل FeedbackSubmitted و source مضبوط على ask و question معبّأ، والصفحة هي التي سأل منها القارئ. وتحصل التحليلات لديك على حدث larecipe:feedback نفسه، بالمصدر ask. ويتبع الزرّان feedback.enabled أيضًا.

الأحداث

يطلق LaRecipe حدث Laravel لكل نوع من الطلبات التي يقدّمها. وهي موجودة في LaRecipe\Domains\Delivery\Events.

كل واحد منها يحمل kind: إما human أو crawler أو agent، ويُحدَّد من وكيل المستخدم في الطلب ومن كونه يطلب Markdown أم لا. ولا يُستخدم هذا النوع إلا في الأحداث؛ ولا يغيّر أبدًا ما يقدّمه LaRecipe. وتجد في مرجع الأحداث القواعد الدقيقة وحقول كل حدث.

استمع إليها كأي حدث Laravel، وأرسلها إلى حيث تشاء: واجهة برمجة أداة التحليلات من جهة الخادم، أو صف في جدول خاص بك، أو سجل.

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Log;
use LaRecipe\Domains\Delivery\Events\PageViewed;

class ForwardDocsTraffic implements ShouldQueue
{
    public function handle(PageViewed $event): void
    {
        // People already reach your client-side analytics. Skip LaRecipe's own export and doctor runs too.
        if ($event->kind === 'human' || str_starts_with((string) $event->userAgent, 'LaRecipe-')) {
            return;
        }

        Log::info('Docs page viewed', [
            'set' => $event->set,
            'version' => $event->page->version,
            'locale' => $event->page->locale,
            'path' => $event->page->path,
            'format' => $event->format,
            'kind' => $event->kind,
            'user_agent' => $event->userAgent,
        ]);
    }
}

التالي

• البحث: اعثر بالحدث SearchPerformed على الأسئلة التي لا يجيب عنها توثيقك بعد.
• مرجع الأحداث: كل حدث وحقوله وكيف يُحدَّد نوع الطلب.
• واجهات الوكلاء: الملفات التي يقرؤها الوكلاء، والأحداث التي يطلقها كل منها.