Custom Events

Custom events allow you to track any user interaction or business metric that's specific to your application with complete flexibility in naming and payload structure. Unlike automatic events that fire automatically and pre-defined events that integrate with Markopolo's platform features, custom events are purely for analytics and reporting.

When to Use Custom Events

Use custom events when:

• You need to track interactions unique to your business
• Pre-defined events don't match your specific use case
• You want to track micro-conversions or custom engagement metrics
• You need complete control over the event schema
• You're tracking metrics for analytics dashboards only

Important Characteristics

• Analytics Only: Custom events appear in your analytics dashboard but are NOT used by Markopolo for platform-specific features
• Complete Flexibility: Use any event name and any payload structure
• No Platform Integration: Won't trigger marketing automations or sync with platform features
• Custom Reporting: Perfect for business-specific KPIs and metrics

Basic Implementation

Custom events follow the same pattern as suggested events:

mtag('event', {
    type: 'your_custom_event_name',
    // Your custom parameters
    parameter1: 'value1',
    parameter2: 'value2',
    // ... any other data
});

Event Naming

Custom events have complete flexibility - there are no naming conventions or requirements. You can name your events however you want:

// All of these are valid - use whatever works for your team
mtag('event', { type: 'VideoPlayed' });
mtag('event', { type: 'video_played' });
mtag('event', { type: 'videoPlayed' });
mtag('event', { type: 'VIDEOPLAY' });
mtag('event', { type: 'evt_123_video' });
mtag('event', { type: 'My Video Event' });  // Spaces work but not recommended

Custom Event Examples

Media & Content

// Video engagement
mtag('event', {
    type: 'video_played',
    email: 'user@example.com',
    video_id: 'VID-12345',
    video_title: 'Product Demo',
    video_duration: 120,  // seconds
    category: 'tutorials'
});

// Article reading
mtag('event', {
    type: 'article_read',
    email: 'user@example.com',
    article_id: 'ART-789',
    article_title: 'Getting Started Guide',
    read_time: 45,  // seconds
    scroll_depth: 85  // percentage
});

// Download tracking
mtag('event', {
    type: 'resource_downloaded',
    email: 'user@example.com',
    resource_type: 'pdf',
    resource_name: 'Annual Report 2024',
    file_size: '2.3MB'
});

User Engagement

// Feature usage
mtag('event', {
    type: 'feature_used',
    email: 'user@example.com',
    feature_name: 'advanced_search',
    search_query: 'blue widgets',
    results_count: 23
});

// Social interactions
mtag('event', {
    type: 'user_followed',
    email: 'follower@example.com',
    followed_user_id: 'USER-456',
    followed_from: 'profile_page'
});

// Gamification
mtag('event', {
    type: 'achievement_unlocked',
    email: 'user@example.com',
    achievement_id: 'first_purchase',
    achievement_name: 'First Timer',
    points_earned: 100
});

SaaS & Apps

// Project management
mtag('event', {
    type: 'project_created',
    email: 'user@example.com',
    project_id: 'PROJ-123',
    project_type: 'marketing',
    team_size: 5
});

// Workspace activity
mtag('event', {
    type: 'document_exported',
    email: 'user@example.com',
    document_id: 'DOC-456',
    export_format: 'PDF',
    document_pages: 12
});

// Collaboration
mtag('event', {
    type: 'team_member_invited',
    email: 'admin@example.com',
    invited_email: 'newuser@example.com',
    role: 'editor',
    workspace_id: 'WS-789'
});

E-Learning

// Course progress
mtag('event', {
    type: 'lesson_completed',
    email: 'student@example.com',
    course_id: 'COURSE-101',
    lesson_id: 'LESSON-5',
    lesson_title: 'Advanced Concepts',
    completion_time: 1250,  // seconds
    quiz_score: 85
});

// Certification
mtag('event', {
    type: 'certificate_earned',
    email: 'student@example.com',
    course_id: 'COURSE-101',
    certificate_id: 'CERT-12345',
    passing_score: 80,
    actual_score: 92
});

Gaming & Entertainment

// Game progression
mtag('event', {
    type: 'level_completed',
    email: 'player@example.com',
    level_number: 15,
    score: 12500,
    time_taken: 300,  // seconds
    power_ups_used: 3
});

// In-app activity
mtag('event', {
    type: 'virtual_item_purchased',
    email: 'player@example.com',
    item_id: 'ITEM-789',
    item_name: 'Golden Sword',
    item_category: 'weapons',
    virtual_currency_spent: 500,
    real_value: 4.99
});

Including User Identifiers

Always include user identifiers when available for better tracking:

mtag('event', {
    type: 'custom_action',

    // Include at least one identifier
    email: 'user@example.com',      // Preferred
    phone: '+13425784032',          // Alternative
    user_id: 'USER-12345',          // Your internal ID

    // Your custom parameters
    custom_param: 'value'
});

Structuring Complex Data

For complex events, organize your data hierarchically:

mtag('event', {
    type: 'checkout_customized',
    email: 'user@example.com',

    // Group related data
    cart: {
        total_items: 3,
        total_value: 150.00,
        currency: 'USD'
    },

    shipping: {
        method: 'express',
        cost: 15.00,
        estimated_days: 2
    },

    payment: {
        method: 'credit_card',
        installments: 3
    },

    // Arrays for multiple items
    applied_coupons: ['SAVE10', 'FREESHIP'],

    // Metadata
    session_duration: 450,  // seconds
    device_type: 'mobile'
});

Best Practices

1. Plan Your Events

Before implementing, create an event tracking plan:

• List all important user actions
• Define the data you need for each event
• Document your naming conventions

2. Be Consistent with Data Types

// Good - consistent types
mtag('event', {
    type: 'product_rated',
    rating: 4.5,        // Always use numbers for ratings
    product_id: 'PROD-123',  // Always use strings for IDs
    is_verified: true   // Always use booleans for yes/no
});

// Bad - inconsistent types
mtag('event', {
    type: 'product_rated',
    rating: '4.5',      // String instead of number
    product_id: 123,    // Number instead of string
    is_verified: 'yes'  // String instead of boolean
});

3. User Identification

You can include user identifiers like email and phone numbers in your custom events, similar to pre-defined events:

// Include user identifiers as event parameters
mtag('event', {
    type: 'UserLoggedIn',
    email: 'john.smith@example.com',
    phone: '+1234567890'
});

Testing Custom Events

1. Browser Console Testing

// Test your events in the browser console first
mtag('event', {
    type: 'test_event',
    test_parameter: 'test_value'
});

2. Verify in Network Tab

• Open Developer Tools
• Go to Network tab
• Filter for MarkTag requests
• Verify your custom event data is being sent

3. Check Event Data

• Option 1: Use the Partners API Events endpoint to verify your events
• Option 2: Log into Markopolo Dashboard
  • Navigate to Data Room > Events
  • Look for your custom events in the event stream
  • Verify all parameters are captured correctly

Common Pitfalls to Avoid

1. Don't Over-Track: Focus on meaningful interactions, not every click
2. Don't Duplicate: Avoid tracking the same action with multiple events
3. Don't Forget Context: Include relevant context like page, section, or feature
4. Don't Use Reserved Words: Avoid using MarkTag's reserved event types for custom events
5. Don't Send Sensitive Data: Never send passwords, credit card numbers, or SSNs

Performance Considerations

• Batch Events When Possible: For multiple related actions, consider combining data
• Limit Event Frequency: For high-frequency events (like mouse movements), implement throttling
• Keep Payload Size Reasonable: Avoid sending large amounts of data in a single event

Custom Events vs Pre-defined Events

Aspect	Custom Events	Pre-defined Events
Schema	Any structure you want	Suggested schema for platform compatibility
Platform Features	No integration	Powers marketing features (product sync, optimization)
Use Case	Unique business metrics	Standard e-commerce/SaaS actions
Analytics	✅ Full analytics	✅ Full analytics + platform features
Example	recipe_saved, workout_completed	Purchase, ViewItem, Lead

Migration from Other Platforms

If you're migrating from another analytics platform, you can map your existing events as custom events:

// Google Analytics event
// gtag('event', 'video_play', { video_title: 'Demo' });

// Equivalent MarkTag custom event
mtag('event', {
    type: 'video_play',
    video_title: 'Demo'
});

// Facebook Pixel event
// fbq('trackCustom', 'ShareDiscount', { value: 10 });

// Equivalent MarkTag custom event
mtag('event', {
    type: 'share_discount',
    value: 10
});

Choosing Between Event Types

1. Use Automatic Events when the behavior is already tracked (page views, clicks, scrolling)
2. Use Pre-defined Events when you want platform features (product sync, campaign optimization)
3. Use Custom Events when you need analytics for unique business metrics

Partners API Note

TIP

If you're using Markopolo through the Partners API for analytics only (not the full marketing platform), custom events and pre-defined events are functionally equivalent since you won't be using platform-specific features. Choose based on your reporting needs.

Next Steps

• Review Automatic Events to avoid duplicating built-in tracking
• Explore Pre-defined Events to see if platform-optimized events meet your needs
• Return to Overview to understand all event types
• Test your implementation in the Markopolo dashboard