Directus Analytics Integrations: Setup Guide | OpsBlu Docs

Directus Analytics Integrations: Setup Guide

Available integrations for Directus-powered sites including analytics platforms, tag managers, and marketing pixels.

Directus is an open-source headless CMS that wraps any SQL database with a real-time GraphQL/REST API. Since Directus provides only the backend API, all tracking and analytics are implemented in your frontend framework.

Available Integrations

Analytics Platforms

Google Analytics 4

  • Frontend framework implementation
  • Collection-based content tracking
  • Real-time subscription analytics
  • Custom fields for enhanced tracking

Tag Management

Google Tag Manager

Marketing Pixels

Meta Pixel

Directus-Specific Integration Considerations

Database-First Architecture

Directus wraps your existing database:

  • Any SQL Database: MySQL, PostgreSQL, SQLite, etc.
  • Existing Schema: Works with your database structure
  • Real-time Updates: WebSocket subscriptions
  • Directus SDK: Type-safe JavaScript SDK

Collection-Based Tracking

Track content from Directus collections:

import { createDirectus, rest, readItems } from '@directus/sdk';

const client = createDirectus('https://your-directus.com').with(rest());

// Fetch and track content
const articles = await client.request(readItems('articles', {
  fields: ['id', 'title', 'author.name', 'category.name']
}));

// Track article view
gtag('event', 'article_view', {
  article_id: article.id,
  article_title: article.title,
  author: article.author?.name,
  category: article.category?.name,
  collection: 'articles'
});

Common Frontend Frameworks with Directus

Next.js

  • Directus JavaScript SDK integration
  • App Router and Pages Router support
  • Static generation with ISR
  • Real-time updates via subscriptions

Nuxt.js

  • Nuxt Directus module
  • Auto-generated types
  • SSR and SSG support
  • Real-time composables

SvelteKit

  • SDK integration with load functions
  • SSR support
  • Real-time stores
  • Type generation

Astro

  • REST/GraphQL integration
  • Static-first approach
  • Island architecture
  • Content collections integration

Real-time Tracking with Subscriptions

Directus supports real-time updates:

import { createDirectus, realtime } from '@directus/sdk';

const client = createDirectus('https://your-directus.com')
  .with(realtime());

// Subscribe to collection changes
const { subscription } = await client.subscribe('articles', {
  event: 'update',
  query: { fields: ['id', 'title'] }
});

for await (const item of subscription) {
  // Track real-time content updates
  gtag('event', 'content_updated', {
    collection: 'articles',
    item_id: item.id,
    update_type: 'live'
  });
}

Flows for Server-Side Analytics

Use Directus Flows for server-side event tracking:

// Flow trigger: On item create in 'conversions' collection
// Operation: Webhook to server-side analytics

// Example Flow configuration
{
  "trigger": {
    "type": "event",
    "event": "items.create",
    "collection": "conversions"
  },
  "operations": [
    {
      "type": "request",
      "method": "POST",
      "url": "https://www.google-analytics.com/mp/collect",
      "body": {
        "client_id": "{{$trigger.payload.client_id}}",
        "events": [{
          "name": "conversion",
          "params": {
            "value": "{{$trigger.payload.value}}",
            "currency": "{{$trigger.payload.currency}}"
          }
        }]
      }
    }
  ]
}

Relationship Tracking

Track content relationships in Directus:

// Fetch with relationships
const article = await client.request(readItem('articles', id, {
  fields: [
    'id',
    'title',
    { author: ['id', 'name'] },
    { categories: ['id', 'name'] },
    { related_articles: ['id', 'title'] }
  ]
}));

// Track with relationship context
gtag('event', 'content_view', {
  content_id: article.id,
  content_type: 'article',
  has_author: !!article.author,
  category_count: article.categories?.length || 0,
  related_count: article.related_articles?.length || 0
});

Integration Best Practices

1. Use Directus IDs

Track using stable Directus item IDs:

gtag('event', 'content_view', {
  content_id: item.id, // Primary key (stable)
  collection: 'articles',
  content_slug: item.slug // May change
});

2. Track Collection Types

Leverage Directus collection metadata:

gtag('event', 'collection_item_view', {
  collection_name: 'articles',
  item_id: article.id,
  is_singleton: false,
  has_accountability: true
});

3. Handle Translations

For Directus translations:

// Fetch translated content
const article = await client.request(readItem('articles', id, {
  deep: {
    translations: {
      _filter: { languages_code: { _eq: currentLocale } }
    }
  }
}));

gtag('event', 'page_view', {
  content_id: article.id,
  content_locale: currentLocale,
  has_translation: article.translations?.length > 0
});

4. Track User Permissions

Consider Directus permissions in analytics:

// Track content access based on role
gtag('event', 'content_access', {
  content_id: item.id,
  collection: 'articles',
  access_role: currentUser?.role || 'public',
  is_authenticated: !!currentUser
});

5. Monitor API Performance

Track Directus API response times:

const start = performance.now();
const data = await client.request(readItems('articles'));
const duration = performance.now() - start;

gtag('event', 'api_performance', {
  endpoint: 'articles',
  response_time_ms: Math.round(duration),
  item_count: data.length
});

Testing Integrations

Collection Testing:

  • Verify collection item tracking
  • Test relationship data
  • Check translation handling

Real-time Testing:

  • Test subscription events
  • Verify live update tracking
  • Check WebSocket connection handling

Flow Testing:

  • Test server-side webhook triggers
  • Verify Conversions API integration
  • Monitor Flow execution

Next Steps

Choose your integration to get started:

Additional Resources

Directus Documentation:

Nach oben