Backstage PlatformX Plugin

A Backstage plugin that tracks user page visits and events using PlatformX by DX .

This plugin uses the new Backstage frontend system.

Installation

1. Install the plugin in your Backstage app:

yarn workspace app add @justinabrahms/backstage-plugin-platformx

1. Configure the PlatformX API key in your app-config.yaml:

platformx:
  apiKey: ${PLATFORMX_API_KEY}
  emailDomain: example.com  # Optional: appends @example.com to usernames

1. Add the plugin to your packages/app/src/index.tsx:

import platformxPlugin from '@justinabrahms/backstage-plugin-platformx';

export default createApp({
  features: [
    // ... other plugins
    platformxPlugin,
  ],
});

The plugin automatically includes a tracker component that will be rendered at the app root level. No additional configuration is needed!

Usage

The plugin automatically tracks page visits when users navigate through your Backstage instance. Each page visit sends:

• Event name: page.visit
• User email (from Backstage identity)
• Timestamp
• Metadata:
  • page: Full URL
  • referrer: Previous page
  • pathname: Current path

Custom Event Tracking

You can also track custom events using the API:

import { useApi } from '@backstage/frontend-plugin-api';
import { platformXApiRef } from '@justinabrahms/backstage-plugin-platformx';

function MyComponent() {
  const platformXApi = useApi(platformXApiRef);

  const handleAction = async () => {
    await platformXApi.trackEvent({
      name: 'button.clicked',
      metadata: {
        button: 'create-component',
        page: window.location.pathname,
      },
    });
  };

  return <button onClick={handleAction}>Create Component</button>;
}

Configuration

Required Configuration

• platformx.apiKey : Your PlatformX API key (obtain from your PlatformX project settings)

Optional Configuration

• platformx.emailDomain : Domain to append to usernames to create full email addresses (e.g., thrivemarket.com will convert justin.abrahms to [email protected] )

Environment Variables

Set the API key as an environment variable:

export PLATFORMX_API_KEY=your_api_key_here

Features

• Automatic page visit tracking
• User identification via Backstage identity
• Custom event tracking API
• Silent failure (won't disrupt user experience if tracking fails)
• TypeScript support

License

Apache-2.0