Laravel

Integrate OnyxMetric Analytics with your Laravel application using Blade templates

Integrating OnyxMetric Analytics with your Laravel application is straightforward. You'll typically add the OnyxMetric tracking script to your main Blade layout file.

Get Your Tracking Script

First, you'll need your OnyxMetric tracking script. You can find this in your OnyxMetric dashboard under Site Settings > Tracking Script. It will look something like this:

<script defer src="https://app.onyxmetric.com/api/script.js" data-site-id="YOUR_SITE_ID"></script>

Replace YOUR_SITE_ID with your actual Site ID from your OnyxMetric dashboard.

Locate Your Main Blade Layout File

In a standard Laravel application, you'll have a main layout file that other Blade views extend. This file is often located at:

resources/views/layouts/app.blade.php (common for applications using Laravel's authentication scaffolding)
Or resources/views/layouts/main.blade.php or a similar custom name.
If you're using Laravel Jetstream or Breeze, the main layout file might be in a slightly different location within resources/views/.

Identify the primary layout file that wraps most or all of your site's pages.

Add the Tracking Script to the Layout

Open your main Blade layout file. Paste the OnyxMetric tracking script just before the closing </body> tag.

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ config('app.name', 'Laravel') }}</title>
    {{-- Stylesheets, etc. --}}
    @vite(['resources/css/app.css', 'resources/js/app.js']) {{-- Example for Vite --}}
</head>
<body class="font-sans antialiased">
    {{-- Your page content, often using @yield or <slot> --}}
    @yield('content') 

    {{-- Other scripts --}}

    {{-- OnyxMetric Analytics Script --}}
    @if(app()->environment('production'))
        <script defer src="{{ config('services.onyxmetric.instance_url', 'https://app.onyxmetric.com') }}/api/script.js" data-site-id="{{ config('services.onyxmetric.site_id') }}"></script>
    @endif
</body>
</html>

Explanation:

@if(app()->environment('production')): This Blade directive ensures the script is only included when your Laravel application is running in the production environment. This prevents tracking during local development.
{{ config('services.onyxmetric.instance_url', 'https://app.onyxmetric.com') }}/api/script.js and {{ config('services.onyxmetric.site_id') }}: This is a recommended way to manage your OnyxMetric credentials using Laravel's configuration system. The config('services.onyxmetric.instance_url') should resolve to your OnyxMetric base URL (https://app.onyxmetric.com, or your own domain if you proxy the script), and /api/script.js is appended to it. See step 4 for .env configuration.

If you prefer not to use the config helper immediately, you can hardcode the values:

    {{-- OnyxMetric Analytics Script --}}
    @if(app()->environment('production'))
        <script defer src="https://app.onyxmetric.com/api/script.js" data-site-id="YOUR_SITE_ID"></script>
    @endif

Remember to replace placeholders with your actual script URL and Site ID.

Configure Environment Variables (Recommended)

It's best practice to store your OnyxMetric Site ID and instance URL in your .env file and access them via Laravel's configuration.

a. Add to .env file: Open your .env file and add:

ONYX_INSTANCE_URL=https://app.onyxmetric.com
ONYX_SITE_ID=YOUR_SITE_ID

b. Add to config/services.php: Open (or create if it doesn't exist) config/services.php and add a configuration for OnyxMetric:

<?php

return [
    // ... other services

    'onyxmetric' => [
        'instance_url' => env('ONYX_INSTANCE_URL'),
        'site_id' => env('ONYX_SITE_ID'),
    ],
];

Now, the Blade template code from Step 3 using config('services.onyxmetric.instance_url') and config('services.onyxmetric.site_id') will work correctly.

Make sure to run php artisan config:clear if you've cached your configuration.

Verify Integration

Deploy your Laravel application to your production environment (or set APP_ENV=production locally for testing, but be mindful of tracking local data).
Open your live Laravel website in a browser.
Navigate through a few pages.
Check your OnyxMetric dashboard for incoming data. It might take a few minutes for the first events to appear.

That's it! OnyxMetric Analytics is now integrated with your Laravel application and will only track visits in your production environment.

Get Your Tracking Script

Locate Your Main Blade Layout File

Add the Tracking Script to the Layout

Configure Environment Variables (Recommended)

Verify Integration

On this page