|
| 1 | +This package is intended to be used on Dash (Flutter, Dart, etc.) related tooling only. |
| 2 | +It provides APIs to send events to Google Analytics using the Measurement Protocol. |
| 3 | + |
| 4 | +## Usage |
| 5 | + |
| 6 | +To get started using this package, import at the entrypoint dart file and |
| 7 | +initialize with the required parameters |
| 8 | + |
| 9 | +```dart |
| 10 | +import 'dash_analytics'; |
| 11 | +
|
| 12 | +// Constants that should be resolved by the client using package |
| 13 | +final DashTool tool = DashTool.flutterTools; // Restricted to enum provided by package |
| 14 | +final String measurementId = 'xxxxxxxxxxxx'; // To be provided to client |
| 15 | +final String apiSecret = 'xxxxxxxxxxxx'; // To be provided to client |
| 16 | +
|
| 17 | +// Values that need to be provided by the client that may |
| 18 | +// need to be calculated |
| 19 | +final String branch = ...; |
| 20 | +final String flutterVersion = ...; |
| 21 | +final String dartVersion = ...; |
| 22 | +
|
| 23 | +// Initialize the [Analytics] class with the required parameters; |
| 24 | +// preferably outside of the [main] method |
| 25 | +final Analytics analytics = Analytics( |
| 26 | + tool: tool, |
| 27 | + measurementId: measurementId, |
| 28 | + apiSecret: apiSecret, |
| 29 | + branch: branch, |
| 30 | + flutterVersion: flutterVersion, |
| 31 | + dartVersion: dartVersion, |
| 32 | +); |
| 33 | +
|
| 34 | +// Timing a process and sending the event |
| 35 | +void main() { |
| 36 | + DateTime start = DateTime.now(); |
| 37 | + int count = 0; |
| 38 | +
|
| 39 | + // Example of long running process |
| 40 | + for (int i = 0; i < 2000; i++) { |
| 41 | + count += i; |
| 42 | + } |
| 43 | + |
| 44 | + // Calculate the metric to send |
| 45 | + final int runTime = DateTime.now().difference(start).inMilliseconds; |
| 46 | +
|
| 47 | + // Generate the body for the event data |
| 48 | + final Map<String, int> eventData = { |
| 49 | + 'time_ns': runTime, |
| 50 | + }; |
| 51 | +
|
| 52 | + // Choose one of the enum values for [DashEvent] which should |
| 53 | + // have all possible events; if not there, open an issue for the |
| 54 | + // team to add |
| 55 | + final DashEvent eventName = ...; // Select appropriate DashEvent enum value |
| 56 | +
|
| 57 | + // Make a call to the [Analytics] api to send the data |
| 58 | + analytics.sendEvent( |
| 59 | + eventName: eventName, |
| 60 | + eventData: eventData, |
| 61 | + ); |
| 62 | +
|
| 63 | + // Close the client connection on exit |
| 64 | + analytics.close(); |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +## Opting In and Out of Analytics Collection |
| 69 | + |
| 70 | +It will be important for each Dash tool to expose a trivial method to |
| 71 | +disabling or enabling analytics collection. Based on how the user interacts |
| 72 | +with the tool, this can be done through the CLI, IDE, etc. The Dash tool will |
| 73 | +then pass a boolean to an API exposed by the package as shown below |
| 74 | + |
| 75 | +```dart |
| 76 | +// Begin by initializing the class |
| 77 | +final Analytics analytics = Analytics(...); |
| 78 | +
|
| 79 | +// The boolean below simulates the user deciding to opt-out |
| 80 | +// of Analytics collection |
| 81 | +final bool status = false; |
| 82 | +
|
| 83 | +// Call the method to pass the boolean |
| 84 | +analytics.setTelemetry(status); |
| 85 | +``` |
| 86 | + |
| 87 | +## Informing Users About Analytics Opt-In Status |
| 88 | + |
| 89 | +When a user first uses any Dash tool with this package enabled, they |
| 90 | +will be enrolled into Analytics collection. It will be the responsiblity |
| 91 | +of the Dash tool using this package to display the proper Analytics messaging |
| 92 | +and inform them on how to Opt-Out of Analytics collection if they wish. The |
| 93 | +package will expose APIs that will make it easy to configure Opt-In status. |
| 94 | + |
| 95 | +```dart |
| 96 | +// Begin by initializing the class |
| 97 | +final Analytics analytics = Analytics(...); |
| 98 | +
|
| 99 | +// This should be performed every time the Dash tool starts up |
| 100 | +if (analytics.shouldShowMessage) { |
| 101 | +
|
| 102 | + // How each Dash tool displays the message will be unique, |
| 103 | + // print statement used for trivial usage example |
| 104 | + print(analytics.toolsMessage); |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +## Checking User Opt-In Status |
| 109 | + |
| 110 | +Some Dash tools may need to know if the user has opted in for Analytics |
| 111 | +collection in order to enable additional functionality. The example below |
| 112 | +shows how to check the status |
| 113 | + |
| 114 | +```dart |
| 115 | +// Begin by initializing the class |
| 116 | +final Analytics analytics = Analytics(...); |
| 117 | +
|
| 118 | +// This getter will return a boolean showing the status; |
| 119 | +// print statement used for trivial usage example |
| 120 | +print('This user's status: ${analytics.telemetryEnabled}'); // true if opted-in |
| 121 | +``` |
| 122 | + |
| 123 | +## Advanced Usage: Querying Locally Persisted Logs |
| 124 | + |
| 125 | +This package enables dash tools to persist the events that have been |
| 126 | +sent to Google Analytics for logging by default. This can be very helpful if |
| 127 | +dash tools would like to understand the user's activity level across all |
| 128 | +dash related tooling. For example, if querying the locally persisted logs |
| 129 | +shows that the user has not been active for N number of days, a dash tool that |
| 130 | +works within an IDE can prompt the user with a survey to understand why their |
| 131 | +level of activity has dropped. |
| 132 | + |
| 133 | +The snippet below shows how to invoke the query and a sample response |
| 134 | + |
| 135 | +```dart |
| 136 | +// Begin by initializing the class |
| 137 | +final Analytics analytics = Analytics(...); |
| 138 | +
|
| 139 | +// Printing the query results returns json formatted |
| 140 | +// string to view; data can also be accessed through |
| 141 | +// [LogFileStats] getters |
| 142 | +print(analytics.logFileStats()); |
| 143 | +
|
| 144 | +// Prints out the below |
| 145 | +// { |
| 146 | +// "startDateTime": "2023-02-08 15:07:10.293728", |
| 147 | +// "endDateTime": "2023-02-08 15:07:10.299678", |
| 148 | +// "sessionCount": 1, |
| 149 | +// "flutterChannelCount": 1, |
| 150 | +// "toolCount": 1 |
| 151 | +// } |
| 152 | +``` |
| 153 | + |
| 154 | +Explanation of the each key above |
| 155 | + |
| 156 | +- startDateTime: the earliest event that was sent |
| 157 | +- endDateTime: the latest, most recent event that was sent |
| 158 | +- sessionCount: count of sessions; sessions have a minimum time of 30 minutes |
| 159 | +- flutterChannelCount: count of flutter channels (can be 0 if developer is a Dart dev only) |
| 160 | +- toolCount: count of the dash tools sending analytics |
0 commit comments