Tracking Events

Learn how to send events from your app to Cueflow for behavior-based targeting and analytics.

Tracking via Embed Script

Use Cueflow.track() to record events:

// Simple event
Cueflow.track('project_created');

// Event with properties
Cueflow.track('file_exported', {
  format: 'csv',
  rowCount: 1500
});

When to Track

Call Cueflow.track() when important actions occur:

// After user creates a project
async function createProject(data) {
  const project = await api.createProject(data);

  // Track the event
  Cueflow.track('project_created', {
    projectId: project.id,
    projectType: project.type
  });

  return project;
}

// After user invites a team member
function inviteTeamMember(email) {
  api.sendInvite(email).then(() => {
    Cueflow.track('team_member_invited');
  });
}

// After completing onboarding
function completeOnboarding() {
  Cueflow.track('onboarding_completed');
}

Event Properties

Add context with properties (optional):

Cueflow.track('purchase_completed', {
  orderId: 'order-123',
  amount: 99.99,
  currency: 'USD',
  items: 3
});

Properties must be JSON-serializable values:

• Strings

• Numbers

• Booleans

• Arrays

• Objects

Queued Events

If you track events before Cueflow.init() completes, they're automatically queued and sent once initialization finishes.

// This works - events are queued
Cueflow.init({ id: 'user-123' });
Cueflow.track('page_loaded'); // Queued until init completes

Tracking via Server API

For server-side events, use the API:

curl -X POST https://app.cueflow.so/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-123",
    "eventKey": "subscription_renewed",
    "properties": {
      "plan": "pro",
      "amount": 99
    }
  }'

Use Cases for Server Events

• Webhook-triggered events (payment completed, email opened)

• Backend processes (job completed, report generated)

• Events from systems without JavaScript

Managing Events in Dashboard

Creating Events

Pre-define events for visibility:

1. Go to Events in the sidebar

2. Click New Event

3. Enter:

   • Name - Display name (e.g., "Project Created")

   • Key - API key (e.g., project_created)

   • Description - Optional context

4. Click Create

Events are also auto-created when first tracked.

Viewing Events

The Events page shows:

• All defined events

• Event occurrence counts

• Last triggered timestamp

Event Details

Click an event to see:

• Recent occurrences

• Which contacts triggered it

• Event properties

Viewing Contact Events

See all events for a specific user:

1. Go to Contacts

2. Click a contact

3. View the Events tab

Shows:

• All events triggered

• Timestamps

• Event properties

Automatic Checklist Completion

Events can auto-complete checklist items:

1. Create a checklist with items

2. For each item, set completion to "Automatic"

3. Add a rule: Event → event_key → Has Done

When the user triggers the event, the checklist item completes automatically.

Example:

Checklist item: "Create your first project"

• Completion type: Automatic

• Rule: Event → project_created → Has Done

When user creates a project and Cueflow.track('project_created') fires, the item auto-completes.

Framework Examples

React

import { useCallback } from 'react';

function CreateProjectButton() {
  const handleCreate = useCallback(async () => {
    const project = await createProject();

    // Track after success
    window.Cueflow.track('project_created', {
      projectId: project.id
    });
  }, []);

  return <button onClick={handleCreate}>Create Project</button>;
}

Vue

<script setup>
function handleExport(format) {
  exportData(format).then(() => {
    window.Cueflow.track('data_exported', { format });
  });
}
</script>

<template>
  <button @click="handleExport('csv')">Export CSV</button>
</template>

Event Wrapper Utility

Create a utility for consistent tracking:

// lib/analytics.ts
export function trackEvent(
  key: string,
  properties?: Record<string, unknown>
) {
  if (typeof window !== 'undefined' && window.Cueflow) {
    window.Cueflow.track(key, properties);
  }
}

// Usage
import { trackEvent } from '@/lib/analytics';

trackEvent('feature_used', { feature: 'dark_mode' });

Best Practices

Track Meaningful Actions

Focus on events that matter:

Good:

• project_created

• team_member_invited

• export_completed

Avoid:

• button_clicked

• page_viewed (too generic)

• mouse_moved

Be Consistent

• Use the same event key everywhere

• Document your event schema

• Review with your team

Include Useful Properties

Add context that helps with analysis:

// Good - useful context
Cueflow.track('file_exported', {
  format: 'csv',
  rowCount: 1500,
  includesHeaders: true
});

// Not as useful - missing context
Cueflow.track('file_exported');

Don't Over-Track

• Track actions, not every interaction

• Consider what you'll actually use

• Review and clean up unused events

Handle Errors

Track events after successful actions:

// Good - track after success
api.createProject(data)
  .then(project => {
    Cueflow.track('project_created');
  })
  .catch(error => {
    // Don't track on failure
  });

Troubleshooting

Events not appearing

1. Check that Cueflow is initialized

2. Verify the event key matches exactly

3. Check browser console for errors

4. Ensure the user has a valid contact ID

Events not triggering messages

1. Verify targeting rules match

2. Check that the message is Published

3. Confirm the event key in rules matches tracked key

4. Check user hasn't already dismissed the message