|
| 1 | +--- |
| 2 | +# Sidenav top-level section |
| 3 | +# should be the same for all markdown files |
| 4 | +section: PatternFly-AI |
| 5 | +subsection: ChatBot |
| 6 | +# Sidenav secondary level section |
| 7 | +# should be the same for all markdown files |
| 8 | +id: Analytics |
| 9 | +source: Analytics |
| 10 | +# Tab (react | react-demos | html | html-demos | design-guidelines | accessibility) |
| 11 | +# If you use typescript, the name of the interface to display props for |
| 12 | +# These are found through the sourceProps function provided in patternfly-docs.source.js |
| 13 | +sortValue: 4 |
| 14 | +--- |
| 15 | +import "../../images.css" |
| 16 | + |
| 17 | +To gain more insight into the ways that your users interact with your ChatBot, you can add support for **analytics**. To add analytics tracking, you can refer to this guide and configure tracking for the interactions you care about most. |
| 18 | + |
| 19 | +## Elements |
| 20 | + |
| 21 | +This following diagram shows the main components of ChatBot analytics tracking code, as well as the flow of information between components: |
| 22 | + |
| 23 | +<div class="ws-docs-content-img"> |
| 24 | + |
| 25 | +</div> |
| 26 | + |
| 27 | +The user code (1) first calls the static `getTrackingProviders()` method (3) which initializes the tracking providers (4). This returns an instance of the `trackingAPI` (2), which can then subsequently be used to emit analytics events. |
| 28 | + |
| 29 | +Note that user code only interacts with: |
| 30 | +- `trackingAPI` (including `identify`, `trackPageview`, `trackSingleItem`) |
| 31 | +- `TrackingRegistry` (including `getTrackingProviders`) |
| 32 | + |
| 33 | +## Usage |
| 34 | + |
| 35 | +### Setup |
| 36 | + |
| 37 | +1. Before you can use the `trackingAPI`, you must first supply the API keys of the respective providers. |
| 38 | + |
| 39 | + ```nolive |
| 40 | + const initProps: InitProps = { |
| 41 | + segmentKey: 'TODO-key', // TODO add your key here |
| 42 | + // segmentCdn: 'https://my.org/cdn', // Set up segment cdn (optional) |
| 43 | + // segmentIntegrations: { // Provide Segment integrations (optional) |
| 44 | + // 'Segment.io': { |
| 45 | + // apiHost: 'my.api.host/api/v1', |
| 46 | + // protocol: 'https' |
| 47 | + // } |
| 48 | + }, |
| 49 | +
|
| 50 | + posthogKey: 'TODO-key', |
| 51 | + umamiKey: 'TODO-key', |
| 52 | + umamiHostUrl: 'http://localhost:3000', // TODO where is your JS provider? |
| 53 | + something: 'test', |
| 54 | + console: 'true' // Console provider |
| 55 | + }; |
| 56 | + ``` |
| 57 | + |
| 58 | +1. Once this is done, you can create an instance of the `trackingAPI` and start sending events. |
| 59 | + |
| 60 | + ```nolive |
| 61 | + const trackingAPI = getTrackingProviders(initProps); |
| 62 | + ``` |
| 63 | +
|
| 64 | +1. One of your first events should identify the user in some way, such as a UUID that stays consistent for the same user. |
| 65 | +
|
| 66 | + ```nolive |
| 67 | + const trackingAPI = getTrackingProviders(initProps); |
| 68 | + trackingAPI.identify('user-123'); // TODO get real user id |
| 69 | + // Track the page that is currently visited. Best put into a react effect (see below) |
| 70 | + trackingAPI.trackPageView(); |
| 71 | + // Track a single Event |
| 72 | + trackingAPI.trackSingleItem("MyEvent", { response: 'Good response' }) |
| 73 | + ``` |
| 74 | + |
| 75 | +#### Tracking providers |
| 76 | + |
| 77 | +Only providers with a matching key in the `InitProps` will be started and used. |
| 78 | + |
| 79 | +```nolive |
| 80 | +const initProps: InitProps = { |
| 81 | + segmentKey: 'TODO-key', // TODO add your key here |
| 82 | + posthogKey: 'TODO-key', |
| 83 | + umamiKey: 'TODO-key', |
| 84 | + umamiHostUrl: 'http://localhost:3000', // TODO where is your JS provider? |
| 85 | + console: true |
| 86 | +``` |
| 87 | + |
| 88 | +##### Modifying providers |
| 89 | + |
| 90 | +If you know upfront that you only want to use 1 of the supported providers, you can modify `getTrackingProviders()` and remove all other providers in the providers array. |
| 91 | + |
| 92 | +When using the providers you need to add additional dependencies to your package.json file: |
| 93 | + |
| 94 | +```nolive |
| 95 | +"dependencies": { |
| 96 | + "@segment/analytics-next": "^1.76.0", |
| 97 | + "posthog-js": "^1.194.4" |
| 98 | +``` |
| 99 | + |
| 100 | +##### Adding providers |
| 101 | + |
| 102 | +To add another analytics provider, you need to implement 2 interfaces, `TrackingSpi` and `trackingApi`. |
| 103 | +1. It is easiest to start by copying the `ConsoleTrackingProvider` |
| 104 | +1. The first thing you should do is to provide a correct value in `getKey()` |
| 105 | +1. Once you are happy enough with the implementation, add it to the array of providers in `getTrackingProviders()` |
| 106 | + |
| 107 | +### Page flow tracking |
| 108 | + |
| 109 | +To understand how users move through their ChatBot journey, you can track their page flow. |
| 110 | + |
| 111 | +To add tracking to each page view, use the `trackPageView()` method. |
| 112 | + |
| 113 | +```nolive |
| 114 | +import React from 'react'; |
| 115 | +import { useLocation } from 'react-router-dom'; |
| 116 | +
|
| 117 | +export const useTrackPageFlow = (): void => { |
| 118 | + const { pathname } = useLocation(); |
| 119 | +
|
| 120 | + // notify url change events |
| 121 | + React.useEffect(() => { |
| 122 | + trackingAPI.trackPageView(); |
| 123 | + }, [pathname]); |
| 124 | +}; |
| 125 | +``` |
| 126 | + |
| 127 | +### Event tracking |
| 128 | + |
| 129 | +To get more specific insight into how users are interacting with the UI, you can track single events, including button clicks, form submissions, and so on. |
| 130 | + |
| 131 | +To add tracking to an interaction of your choice, use the `trackSingleItem` method. |
| 132 | + |
| 133 | +```nolive |
| 134 | +trackingAPI.trackSingleItem(eventName, propertyDict) |
| 135 | +``` |
| 136 | + |
| 137 | +This method takes 2 parameters: |
| 138 | +- `eventName`: The unique name of the event. To differentiate different events that use the same name, you'll need to add an additional property. |
| 139 | +- `propertyDict`: A dict with key-value pairs that represent important properties of the event. If there are none, this value can be empty. |
| 140 | + |
| 141 | +#### Form submissions |
| 142 | + |
| 143 | +Only add tracking to the form itself, not the button that opens the form. You should track both successful and failed form submissions, as well as cancelled forms |
| 144 | + |
| 145 | +```nolive |
| 146 | +trackingAPI.trackSingleItem(Event_Name, { |
| 147 | + outcome: << submit , cancel >>, |
| 148 | + success? : boolean, |
| 149 | + error? : string, |
| 150 | + <properties>, string/number/boolean } ) |
| 151 | +``` |
| 152 | + |
| 153 | +Parameters to pass with the `trackSingleItem` method can include: |
| 154 | +- `outcome`: Communicates if the form was submitted or cancelled. |
| 155 | +- `success`: Used for a "submit" outcome to communicate if the submission was successful for not in the backend. |
| 156 | +- `error`: Used for a "submit" outcome to communicate the error message associated with a failed submission. Try to remove extraneous parts of the message, like part of a container-name. |
| 157 | +- `properties`: Any additional properties from the form, to be tracked for analytics. |
| 158 | + - Use your judgement to determine what will be useful for your analytics. |
| 159 | + - Highly specific data, like names provided by the user or description text input, should not be tracked. |
| 160 | + - Less personal data, like deployment replica count or memory server size, is more likely to help you understand your users. |
| 161 | + |
| 162 | +## Examples |
| 163 | + |
| 164 | +To better understand the analytics tracking process, here are 3 examples of what you could see in an analytics tool. |
| 165 | + |
| 166 | +For all 3 tools, consider the following example, where the users has started a ChatBot and taken actions 1-5 in order: |
| 167 | + |
| 168 | +<div class="ws-docs-content-img" style="width:60%"> |
| 169 | + |
| 170 | +</div> |
| 171 | + |
| 172 | +1. Selected a model |
| 173 | +2. Sent a question |
| 174 | +3. Received a response from the model |
| 175 | +4. Clicked the "thumbs up" button |
| 176 | +5. Closed the ChatBot window |
| 177 | + |
| 178 | +This pattern of actions will be applied to the following 3 analytics tools. |
| 179 | + |
| 180 | +1. Segment |
| 181 | + |
| 182 | + - [Segment](https://segment.com/) shows all user events in its source debugger: |
| 183 | + |
| 184 | + <div class="ws-docs-content-img" style="width:70%"> |
| 185 | +  |
| 186 | + </div> |
| 187 | + |
| 188 | + - 1-5: User actions with the newest event at the top. |
| 189 | + - 6-7: You can also see the results of `identify` (6) and `trackPageView` (7). |
| 190 | + - If you clicked on an event, you would also see the properties. |
| 191 | + |
| 192 | + - **Note**: When using the Segment provider, you may also want to set the `segmentCdn` and `segmentIntegrations` initialization properties. |
| 193 | + |
| 194 | +1. Umami |
| 195 | + |
| 196 | + - In [Umami](https://umami.is/), events are visible within **Website** / **Events**. |
| 197 | + - The list is similar to Segment, with different formatting: |
| 198 | + |
| 199 | + <div class="ws-docs-content-img"> |
| 200 | +  |
| 201 | + </div> |
| 202 | + |
| 203 | + - 1-5: User actions with the newest event at the top. |
| 204 | + |
| 205 | +3. PostHog |
| 206 | + |
| 207 | + - In [PostHog](https://posthog.com/), events are located in the **Activity** section. |
| 208 | + - PostHog integrates deeper in the provided code, so there are more default events tracked: |
| 209 | + |
| 210 | + <div class="ws-docs-content-img"> |
| 211 | +  |
| 212 | + </div> |
| 213 | + |
| 214 | + - 1-5: User actions with the newest event at the top. |
0 commit comments