UTM Parameter Guidelines for Article Links
1min read
Overview
This article outlines the standardized UTM parameter implementation for tracking article link clicks across all Brainfish channels and integrations, based on the official requirements from the Linear ticket.
UTM Parameter Structure
Source Parameter
All article links must include:
utm_source=brainfish
This parameter remains consistent across all channels to identify Brainfish as the traffic source.
Medium Parameter
The utm_medium parameter varies based on the channel where the link is clicked:
Official Requirements (Widget + HC):
| Channel | UTM Medium Value | Description |
|---|---|---|
| Popup Widget | utm_medium=popup_widget | Links clicked from the in-app popup widget |
| Search Bar Widget | utm_medium=search_widget | Links clicked from embedded search bar widgets |
| Help Center | utm_medium=help_center | Links clicked from Brainfish Help Center pages |
Additional Channels:
| Channel | UTM Medium Value | Description |
|---|---|---|
| Slack Integration | utm_medium=slack | Links clicked from Slack bot responses |
Implementation Examples
Popup Widget Links
https://example.com/article?utm_source=brainfish&utm_medium=popup_widget
Search Bar Widget Links
https://example.com/article?utm_source=brainfish&utm_medium=search_widget
Help Center Links
https://example.com/article?utm_source=brainfish&utm_medium=help_center
Slack Integration Links
https://example.com/article?utm_source=brainfish&utm_medium=slack
Channel Definitions
Primary Channels
In-App Popup Widget
- The modal/popup widget that appears within customer applications
- Includes both legacy and new widget versions
- Users interact with this widget directly in the app interface
- UTM Medium:
popup_widget
Search Bar Widget
- Embedded search functionality placed within customer Help Centers
- Example: Buffer's implementation where the search bar is integrated into their Help Scout help center
- Provides search results without leaving the customer's help center environment
- UTM Medium:
search_widget
Help Center (HC)
- Brainfish's own help center pages
- Direct navigation and search within the Brainfish platform
- UTM Medium:
help_center
Additional Channels
Slack Integration
- Article links shared through Slack bot responses
- Links clicked from Slack conversations and channels
- UTM Medium:
slackImportant Considerations
Implementation Checklist
- Verify
utm_source=brainfishis applied to all article links - Confirm correct
utm_mediumvalue based on channel type - Test UTM parameters across all integration points
- Document any custom implementations or exceptions
- Review analytics setup to properly capture UTM data
Questions or Issues?
If you encounter any issues with UTM parameter implementation or need clarification on channel definitions, please reach out to the development team for assistance.