Developer documentation

// Track a simple event
AnalyticsWP.event('page_view');

// Track an event with properties
AnalyticsWP.event('button_click', {
    unique_event_identifier: 'btn_click_123',
    button_id: 'submit-form',
    button_text: 'Submit'
});

interface EventProperties {
    // Pass a unique identifier if you want to reference this Event later:
    unique_event_identifier?: string;
    // Pass conversion properties in if it's a conversion event:
    conversion_type?: string;
    conversion_id?: string;
    // All of these below properties are *automatically* added by AnalyticsWP,
    // you can still pass them in to override the values if you want:
    unique_session_id?: string;
    user_id?: number|string;
    user_email?: string;
    device_type?: string;
    ip_address?: string;
    utm_source?: string;
    utm_medium?: string;
    utm_campaign?: string;
    utm_term?: string;
    utm_content?: string;
    timestamp?: string;
    // And then literally any custom properties you want to add:
    [key: string]: any;
}

function event(event_type: string, event_properties?: EventProperties): void

/**
 * Track an event from the server side
 * 
 * @param string $event_type
 * @param array $args
 * 
 * @return array{error: non-empty-string}|int - An error message or the Event ID.
 */
public static function track_server_event(
    string $event_type, 
    array $args = array(), 
)

/**
 * Track WooCommerce orders as conversions
 * 
 * @param int $order_id
 * @return array{error: string}|int|null
 */
function track_order($order_id) {
    $order = \wc_get_order($order_id);

    $user_id = $order->get_user_id();
    $email = $order->get_billing_email();

    return Event::track_server_event('conversion', [
        'conversion_id' => $order_id,
        'conversion_type' => 'woocommerce_order',
        'user_id' => $user_id,
        'user_email' => $email,
    ]);
}

add_action('woocommerce_new_order', 'track_order, 10);

namespace Breakdance\Partners\AnalyticsWP;

// Initialize the integration when WordPress plugins are loaded
add_action('plugins_loaded', '\Breakdance\Partners\AnalyticsWP\init_integration');

/**
 * Main initialization function for the AnalyticsWP integration with Breakdance forms
 * Sets up all the necessary WordPress hooks if AnalyticsWP is installed
 */
function init_integration() {
    if (is_analyticswp_installed()) {
        // Track form submissions when they're saved to the database
        add_action('wp_insert_post', '\Breakdance\Partners\AnalyticsWP\breakdance_form_submission_handler', 10, 3);
        
        // Add a custom column to the form submissions admin screen
        add_filter(
            'manage_breakdance_form_res_posts_columns',
            '\Breakdance\Partners\AnalyticsWP\breakdance_form_analyticswp_custom_column'
        );
        
        // Populate the custom column with a link to view the user's journey
        add_action('manage_breakdance_form_res_posts_custom_column', 
            '\Breakdance\Partners\AnalyticsWP\breakdance_form_analyticswp_custom_column_content', 
            10, 
            2
        );
    }
}

/**
 * Handles form submissions by tracking them in AnalyticsWP
 * This is called automatically by WordPress when a form submission is saved
 * 
 * Key AnalyticsWP Integration Point:
 * Uses track_server_event() to track form submissions with a unique identifier
 */
function breakdance_form_submission_handler($post_id, $post, $update) {
    if ($post->post_type == 'breakdance_form_res') {
        // Track the form submission in AnalyticsWP
        \AnalyticsWP\Lib\Event::track_server_event(
            'breakdance_form_submission',  // Event type
            [
                // Use a unique identifier to prevent duplicate tracking
                'unique_event_identifier' => get_unique_event_identifier_for_form_submission($post_id),
            ]
        );
    }
}

/**
 * Adds an "AnalyticsWP Journey" column to the form submissions list
 */
function breakdance_form_analyticswp_custom_column($columns) {
    $columns['analyticswp_journey'] = 'AnalyticsWP Journey';
    return $columns;
}

/**
 * Displays a link to view the user's journey for each form submission
 * 
 * Key AnalyticsWP Integration Point:
 * Uses admin_journey_path_for_event_where_condition() to generate a URL
 * that will show the user's journey leading up to this form submission
 */
function breakdance_form_analyticswp_custom_column_content($column, $post_id) {
    if ($column !== 'analyticswp_journey') return;

    // Get the journey URL from AnalyticsWP using the unique identifier
    $journey_path = \AnalyticsWP\Lib\URLs::admin_journey_path_for_event_where_condition(
        ['unique_event_identifier' => get_unique_event_identifier_for_form_submission($post_id)]
    );

    if ($journey_path) {
        echo "View Journey";
    } else {
        echo "No Journey";
    }
}

/**
 * Creates a unique identifier for a form submission
 * This helps prevent duplicate tracking and allows linking back to the journey
 */
function get_unique_event_identifier_for_form_submission($post_id) {
    return 'breakdance_form_submission' . '_' . $post_id;
}

/**
 * Checks if AnalyticsWP is installed and available
 */
function is_analyticswp_installed() {
    return class_exists('\AnalyticsWP\Lib\Core');
}