n8n-nodes-fullstory

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node for FullStory, the digital experience intelligence platform. This node enables workflow automation with 10 resources and 60+ operations for user management, event tracking, session replay, error analysis, page analytics, and more.

Features

• User Management: Create, update, get, list, search, merge, and delete users with custom properties
• Event Tracking: Track custom events with full context support; manage event definitions
• Session Replay: Access session details, generate replay URLs, search sessions, manage notes
• Segment Management: Full CRUD for segments with user/session membership and exports
• Webhook Management: Complete webhook lifecycle including deliveries and retries
• Data Export: Create exports, monitor status, download results, manage operations
• Notes: Create, search, and manage notes on sessions and users
• Error Analytics: View, search, and group captured JavaScript/network errors
• Page Analytics: Access page metrics, heatmaps, and session data
• Integrations: Manage third-party integration configurations
• Trigger Support: Receive real-time webhook events from FullStory

Installation

Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Select Install
4. Enter n8n-nodes-fullstory in the package name field
5. Accept the risks and click Install

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-fullstory

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-fullstory.git
cd n8n-nodes-fullstory

# Install dependencies
npm install

# Build the project
npm run build

# Link to n8n
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-fullstory

# Restart n8n

Credentials Setup

FullStory API

| Field | Description | |-------|-------------| | API Key | Your FullStory API key. Create one in Settings > Integrations > API Keys | | Data Center | Select your data center region (US or EU) |

Permission Levels

• Standard: Basic read/write operations
• Admin: Extended permissions including user deletion
• Architect: Full access including webhook management

Resources & Operations

User (V2 API)

| Operation | Description | |-----------|-------------| | Create | Create or update a user with custom properties | | Get | Retrieve user details by FullStory ID | | Get by UID | Retrieve user by your system's user ID | | Update | Update user display name, email, or properties | | Batch Create | Create or update multiple users in a single request | | Delete | Delete a user and all associated data | | List | List all users with pagination | | Search | Search users by properties | | Get Sessions | Get all sessions for a user | | Merge | Merge two user profiles |

Event (V2 API)

| Operation | Description | |-----------|-------------| | Track | Track a custom event with optional context | | Batch Track | Track multiple events in a single request | | List Definitions | List all custom event definitions | | Get Definition | Get event definition details | | Create Definition | Create custom event schema | | Update Definition | Update event schema | | Delete Definition | Delete event definition |

Session

| Operation | Description | |-----------|-------------| | Get | Get details for a specific session | | List | List sessions with filters | | Search | Search sessions by criteria | | Get Replay URL | Generate a session replay URL | | Get Events | Get events within a session | | Get Notes | Get notes on a session | | Add Note | Add a note to a session | | Delete Note | Remove a note from a session |

Segment

| Operation | Description | |-----------|-------------| | List | List all segments in your account | | Get | Get details for a specific segment | | Create | Create a new segment | | Update | Update segment definition | | Delete | Delete a segment | | Get Users | Get users in segment | | Get Sessions | Get sessions matching segment | | Create Export | Create an export job for segment data |

Webhook

| Operation | Description | |-----------|-------------| | Create | Create a new webhook endpoint | | List | List all webhook endpoints | | Get | Get details for a specific endpoint | | Update | Update an existing endpoint | | Delete | Delete a webhook endpoint | | Enable | Enable a disabled endpoint | | Disable | Disable an endpoint | | Test | Send test webhook payload | | List Deliveries | Get webhook delivery history | | Retry Delivery | Retry a failed delivery |

Data Export

| Operation | Description | |-----------|-------------| | Create | Create a new data export job | | Create Segment Export | Create segment-specific export | | Get Status | Check the status of an export job | | List Operations | List all export operations | | Download | Wait for completion and get download URLs | | Cancel | Cancel a pending export | | Get Schema | Get export data schema |

Note

| Operation | Description | |-----------|-------------| | List | List all notes | | Get | Get note details | | Create | Create a note on session/user | | Update | Update note content | | Delete | Delete a note | | Search | Search notes by content |

Error

| Operation | Description | |-----------|-------------| | List | List captured errors | | Get | Get error details | | Get Sessions | Get sessions with specific error | | Group | Get error groupings | | Search | Search errors by message/stack |

Page

| Operation | Description | |-----------|-------------| | List | List tracked pages | | Get | Get page analytics | | Get Sessions | Get sessions for page | | Get Heatmap | Get page heatmap data | | Search | Search pages by URL pattern |

Integration

| Operation | Description | |-----------|-------------| | List | List configured integrations | | Get | Get integration details | | Create | Set up new integration | | Update | Update integration config | | Delete | Remove integration | | Test | Test integration connection |

Trigger Node

The FullStory Trigger node automatically manages webhook endpoints and receives events in real-time.

Supported Events

• note.created - Triggered when a note is created
• note.updated - Note was modified
• note.deleted - Note was removed
• recording.event.custom - Custom event occurred
• recording.completed - Session recording completed
• segment.entered - User entered a segment
• segment.exited - User exited a segment
• user.created - New user identified
• user.updated - User properties changed
• error.captured - JavaScript error captured

Usage Examples

Track a Custom Event

{
  "resource": "event",
  "operation": "track",
  "userId": "user_123",
  "eventName": "Purchase Completed",
  "properties": {
    "amount": 99.99,
    "currency": "USD",
    "product_id": "prod_456"
  }
}

Create a User with Properties

{
  "resource": "user",
  "operation": "create",
  "uid": "user_123",
  "displayName": "John Doe",
  "email": "[email protected]",
  "properties": {
    "plan": "enterprise",
    "company": "Acme Inc"
  }
}

Generate Session Replay URL

{
  "resource": "session",
  "operation": "getUrl",
  "sessionId": "5678901234:1234567890",
  "timestamp": 5000
}

Create Data Export

{
  "resource": "dataExport",
  "operation": "create",
  "exportType": "TYPE_EVENT",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-31T23:59:59Z",
  "format": "FORMAT_CSV"
}

Data Centers

| Region | Data Center | API Endpoint | |--------|-------------|--------------| | United States | NA1 | api.fullstory.com | | Europe | EU1 | api.fullstory.com |

Note: The data center is encoded in your API key prefix.

Error Handling

The node handles common FullStory API errors:

| Code | Description | |------|-------------| | 400 | Invalid input - check your parameters | | 401 | Unauthorized - verify your API key | | 403 | Forbidden - insufficient permissions | | 404 | Resource not found | | 429 | Rate limited - implement backoff | | 500 | Server error - retry later |

Rate Limits

• Default: 100 requests/minute
• Segment Export: 2 requests/minute
• The node implements exponential backoff for 429 responses

Security Best Practices

1. Use HTTPS for all webhook URLs
2. Rotate API keys periodically
3. Use minimum required permissions for API keys
4. Validate webhook payloads in your workflows
5. Encrypt sensitive user properties before storing

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Fix linting issues
npm run lint:fix

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• Documentation: FullStory Developer Docs
• Issues: GitHub Issues
• Email: [email protected]

Acknowledgments

• FullStory for their digital experience platform
• n8n for the workflow automation platform
• The n8n community for their contributions and feedback