Skip to content

Commit cc315e0

Browse files
kevinthecheungkevinthecheung
authored
docs(firebase_analytics): Add material from official docs (#8093)
1 parent 6ac77d9 commit cc315e0

File tree

9 files changed

+717
-283
lines changed

9 files changed

+717
-283
lines changed

‎docs/analytics/events.mdx

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Log events
3+
---
4+
5+
This guide shows you how to log events in your app.
6+
7+
Analytics automatically logs some
8+
[events](https://support.google.com/firebase/answer/6317485) for you; you don't
9+
need to add any code to receive them. If your app needs to collect additional
10+
data, you can log up to 500 different Analytics Event *types* in your app.
11+
There is no limit on the total volume of events your app logs. Note that event
12+
names are case-sensitive and that logging two events whose names differ only in
13+
case will result in two distinct events.
14+
15+
## Before you begin
16+
17+
Make sure that you've set up your project and can access Analytics as
18+
described in [Get Started with Analytics](get-started).
19+
20+
## Log events
21+
22+
After you have created a `FirebaseAnalytics` instance, you can use it to log
23+
events with the library's `log`- methods.
24+
25+
### Predefined events
26+
27+
To help you get started, the Analytics SDK defines a number of
28+
suggested events that are common among different types of apps, including
29+
retail and ecommerce, travel, and gaming apps. To learn more
30+
[about these events](https://support.google.com/analytics/answer/9322688)
31+
and when to use them, browse the
32+
[Events and properties](https://support.google.com/firebase/topic/6317484)
33+
articles in the Firebase Help Center.
34+
35+
:::note
36+
To get the maximum detail in reports, log the suggested events that make
37+
sense for your app and their prescribed parameters. This also ensures that you
38+
benefit from the latest Google Analytics features as
39+
they become available.
40+
:::
41+
42+
You can find the log methods for the suggested event types in the
43+
[API reference](https://pub.dev/documentation/firebase_analytics/latest/firebase_analytics/FirebaseAnalytics-class.html).
44+
45+
The following example demonstrates how to log a `select_content` event:
46+
47+
```dart
48+
await FirebaseAnalytics.instance.logSelectContent(
49+
contentType: "image",
50+
itemId: itemId,
51+
);
52+
```
53+
54+
Alternatively, you can log the same event using `logEvent()`:
55+
56+
```dart
57+
await FirebaseAnalytics.instance.logEvent(
58+
name: "select_content",
59+
parameters: {
60+
"content_type": "image",
61+
"item_id": itemId,
62+
},
63+
);
64+
```
65+
66+
This can be useful if you want to specify additional parameters other than the
67+
prescribed (required) parameters. You can add the following parameters
68+
to any event:
69+
70+
* Custom parameters: Custom parameters can be used as
71+
[dimensions or metrics](https://support.google.com/analytics/answer/10075209)
72+
in [Analytics reports](https://support.google.com/analytics/answer/9212670).
73+
You can use custom dimensions for non-numerical event parameter data and
74+
custom metrics for any parameter data better represented numerically. Once
75+
you've logged a custom parameter using the SDK, register the dimension or
76+
metric to ensure those custom parameters appear in Analytics
77+
reports. Do this via: *Analytics > Events > Manage Custom Definitions >
78+
Create Custom Dimensions*
79+
80+
Custom parameters can be used in
81+
[audience](https://support.google.com/firebase/answer/6317509)
82+
definitions that may be applied to every report.
83+
Custom parameters are also included in data
84+
[exported to BigQuery](https://support.google.com/firebase/answer/7030014)
85+
if your app is linked to a BigQuery project. Find sample queries and much more
86+
at [Google Analytics 4 BigQuery Export](https://developers.google.com/analytics/bigquery).
87+
88+
* `value` parameter: a general purpose parameter
89+
that is useful for accumulating a key metric that pertains to an
90+
event. Examples include revenue, distance, time, and points.
91+
92+
### Custom events
93+
94+
If your application has specific needs not covered by a suggested
95+
event type, you can log your own custom events as shown in this example:
96+
97+
```dart
98+
await FirebaseAnalytics.instance.logEvent(
99+
name: "share_image",
100+
parameters: {
101+
"image_name": name,
102+
"full_text": text,
103+
},
104+
);
105+
```
106+
107+
## Set default event parameters
108+
109+
You can log parameters across events using `setDefaultEventParameters()`.
110+
Default parameters are associated with all future events that are logged.
111+
112+
As with custom parameters, register the default event parameters to ensure they
113+
appear in Analytics reports.
114+
115+
```dart
116+
// Not supported on web
117+
await FirebaseAnalytics.instance
118+
.setDefaultEventParameters({
119+
version: '1.2.3'
120+
});
121+
```
122+
123+
If a parameter is specificed in the `logEvent()` or `log`-
124+
method, that value is used instead of the default.
125+
126+
To clear a default parameter, call the `setDefaultEventParameters()`
127+
method with the parameter set to `null`.

‎docs/analytics/get-started.mdx

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: Get started with Google Analytics
3+
sidebar_label: Get started
4+
---
5+
6+
Google Analytics collects usage and behavior data for your app. The SDK
7+
logs two primary types of information:
8+
9+
* **Events:** What is happening in your app, such as user actions, system
10+
events, or errors.
11+
* **User properties:** Attributes you define to describe segments of your
12+
user base, such as language preference or geographic location.
13+
14+
Analytics automatically logs some
15+
[events](https://support.google.com/firebase/answer/6317485) and
16+
[user properties](https://support.google.com/firebase/answer/6317486);
17+
you don't need to add any code to enable them.
18+
19+
## Before you begin
20+
21+
1. [Install `firebase_core`](../overview.mdx) and add the initialization code
22+
to your app if you haven't already.
23+
1. Add your app to your Firebase project in the <a href="https://console.firebase.google.com/">Firebase console</a>.
24+
25+
## Add the Analytics SDK to your app {#add-sdk}
26+
27+
1. From the root of your Flutter project, run the following command to install the plugin:
28+
29+
```bash {5}
30+
flutter pub add firebase_analytics
31+
```
32+
33+
1. Once complete, rebuild your Flutter application:
34+
35+
```bash
36+
flutter run
37+
```
38+
39+
1. Once installed, you can access the [`firebase_analytics`](!firebase_analytics)
40+
plugin by importing it in your Dart code:
41+
42+
```dart
43+
import 'package:firebase_analytics/firebase_analytics.dart';
44+
```
45+
46+
1. Create a new Firebase Analytics instance by calling the
47+
[`instance`](!firebase_analytics.FirebaseAnalytics.instance) getter on
48+
[`FirebaseAnalytics`](!firebase_auth.FirebaseAnalytics):
49+
50+
```dart
51+
FirebaseAnalytics analytics = FirebaseAnalytics.instance;
52+
```
53+
54+
### (Optional) Disable IDFA tracking
55+
56+
To use Firebase Analytics without IDFA collection capability, open
57+
`/ios/Podfile` or `/macos/Podfile` and add the following global variable to the
58+
top of the file:
59+
60+
```ruby
61+
$FirebaseAnalyticsWithoutAdIdSupport = true
62+
```
63+
64+
Learn more about IDFA in Apple's documentation:
65+
66+
* [User Privacy and Data Use](https://developer.apple.com/app-store/user-privacy-and-data-use/)
67+
* [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency)
68+
69+
### (Optional) Disable Apple ad network attribution registration
70+
71+
For your convenience, the SDK automatically
72+
[registers](//developer.apple.com/documentation/storekit/skadnetwork/2943654-registerappforadnetworkattributi)
73+
your app with Apple for ad network attribution with
74+
[SKAdNetwork](//developer.apple.com/documentation/storekit/skadnetwork).
75+
If you wish to disable this feature, set the value of
76+
`GOOGLE_ANALYTICS_REGISTRATION_WITH_AD_NETWORK_ENABLED` to `NO` (Boolean) in
77+
your app's Info.plist file.
78+
79+
80+
## Start logging events
81+
82+
After you have created a `FirebaseAnalytics` instance, you can begin to log
83+
events with the library's `log`- methods.
84+
85+
Certain events are
86+
[recommended for all apps](https://support.google.com/firebase/answer/6317498?ref_topic=6317484);
87+
others are recommended for specific business types or verticals. You should send
88+
suggested events along with their prescribed parameters, to ensure maximum
89+
available detail in your reports and to benefit from future features and
90+
integrations as they become available. This section demonstrates logging a
91+
pre-defined event, for more information on logging events, see
92+
[Log events](events).
93+
94+
The following code logs a checkout event:
95+
96+
```dart
97+
await FirebaseAnalytics.instance
98+
.logBeginCheckout(
99+
value: 10.0,
100+
currency: 'USD',
101+
items: [
102+
AnalyticsEventItem(
103+
itemName: 'Socks',
104+
itemId: 'xjw73ndnw',
105+
price: '10.0'
106+
),
107+
],
108+
coupon: '10PERCENTOFF'
109+
);
110+
```
111+
112+
## Next steps
113+
114+
* Use the [DebugView](https://firebase.google.com/docs/analytics/debugview) to verify your events.
115+
* Explore your data in the [Firebase console](https://console.firebase.google.com/project/_/analytics/).
116+
* Explore the guides on [events](events) and
117+
[user properties](user-properties).
118+
* Learn how to export your data to [BigQuery](https://support.google.com/firebase/answer/7030014?hl=en&ref_topic=7029512).

0 commit comments

Comments
 (0)