Skip to content

Commit a3c0635

Browse files
OmbuwebOmbuweb
authored
docs(firebase-analytics): update (#186)
* docs(firebase-analytics): update * chore: update * chore: update * chore: update * chore: update
1 parent f207f72 commit a3c0635

File tree

1 file changed

+194
-33
lines changed

1 file changed

+194
-33
lines changed

‎packages/firebase-analytics/README.md

Lines changed: 194 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,47 @@
11
# @nativescript/firebase-analytics
22

3-
```cli
4-
npm install @nativescript/firebase-analytics
5-
```
3+
This plugin allows you to add [Google Analytics for Firebase](https://firebase.google.com/docs/analytics)
4+
to your app.
65

7-
## What does it do?
6+
> **Note:** Use this plugin with the [@nativescript/firebase-core](../firebase-core/) plugin to initialize Firebase in your app.
87
98
Analytics collects usage and behavior data for your app. Its two primary concerns are:
109

11-
- **Events**: What is happening in your app, such as user actions, system events, or errors.
12-
- **User properties**: Attributes you define to describe segments of your user base, such as language preference or geographic location.
10+
- [Events](https://support.google.com/analytics/answer/9234069): These are events that occur in your app, such as user actions, system events, or errors. Google Analytics collects information for 3 types of events: [Automatically collected](https://support.google.com/analytics/answer/9234069?hl=en&ref_topic=13367566), [Recommended](https://support.google.com/analytics/answer/9267735?hl=en&ref_topic=13367566) and [Custom](https://support.google.com/analytics/answer/12229021?hl=en&ref_topic=13367566) events.
11+
12+
- [user properties](https://support.google.com/analytics/answer/9268042): Attributes you define to describe segments of your user base, such as language preference or geographic location.
1313

1414
[![image](https://img.youtube.com/vi/8iZpH7O6zXo/hqdefault.jpg)](https://www.youtube.com/watch?v=8iZpH7O6zXo)
1515

16-
Analytics automatically logs some [events](https://support.google.com/analytics/answer/9234069) and [user properties](https://support.google.com/analytics/answer/9268042); you don't need to add any code to enable them. However, Analytics also allows you to log custom or predefined events within your app. How you can do this will be explained below.
16+
* [Installation](#installation)
17+
* [Use @nativescript/firebase-analytics](#use-nativescriptfirebase-analytics)
18+
* [Log custom events](#log-custom-events)
19+
* [Log Predefined Events](#log-predefined-events)
20+
* [Reserved Events](#reserved-events)
21+
* [Get the app instance id](#get-the-appinstance-id)
22+
* [Disable Ad Id usage on iOS](#disable-ad-id-usage-on-ios)
23+
* [Analytics class API](#analytics-class-api)
24+
* [Properties](#properties)
25+
* [Methods](#Methods)
26+
* [License](#License)
27+
28+
## Installation
29+
Install the plugin by running the following command in the root directory of your project.
30+
31+
```cli
32+
npm install @nativescript/firebase-analytics
33+
```
34+
35+
## Use @nativescript/firebase-analytics
1736

18-
## Usage
37+
The examples below show you how to use `@nativescript/firebase-analytics` to log custom and predefined events.
1938

20-
Analytics offers a wealth of Predefined Events to track user behavior. Analytics also offers folks the ability to log Custom Events . If you're already familiar with Google Analytics, this method is equivalent to using the event command in [gtag.js](https://developers.google.com/gtagjs/).
39+
### Log custom events
2140

22-
### Custom Events
41+
Analytics also allows developers to log custom events. If you're already familiar with Google Analytics, this method is equivalent to using the event command in [gtag.js](https://developers.google.com/gtagjs/).
42+
To log a custom event to Analytics, call the `logEvent` method on an instance of the `Analytics` class passing it the name of the custom event as the first argument and the event data object as the second argument.
2343

24-
Below is an example showing how a custom event can be logged. Please be aware that primitive data types or arrays of primitive data types are logged in your Firebase Analytics console.
44+
Please be aware that primitive data types or arrays of primitive data types are logged in your Firebase Analytics console.
2545

2646
```ts
2747
import { firebase } from '@nativescript/firebase-core';
@@ -36,14 +56,15 @@ firebase()
3656
size: 'L',
3757
});
3858
```
59+
After calling `logEvent`, look for your event name in the Analytics Realtime data to see if it's logged.
3960

40-
### Predefined Events
61+
### Log Predefined Events
4162

42-
To help you get started, Analytics provides a number of events that are common among different types of apps, including retail and e-commerce, travel, and gaming apps. To learn more about these events and when to use them, browse the [Events and properties articles](https://support.google.com/analytics/answer/9322688?hl=en&ref_topic=9267641) in the Firebase Help Center.
63+
To help you get started, Google Analytics automatically logs events that are common among different types of apps, including retail and e-commerce, travel, and gaming apps.
4364

44-
Below is a sample of how to use one of the predefined events the Analytics module provides for you.
65+
To log a predefined event, call the `logEvent` method on the `Analytics` class instance passing it the event name and the [event data](https://support.google.com/analytics/answer/13316687#zippy=%2Cmobile-android-and-ios) object.
4566

46-
Using the [select_content](https://developers.google.com/analytics/devguides/collection/ga4/reference/events#select_content) event
67+
The following example demonstrates logging the [select_content](https://developers.google.com/analytics/devguides/collection/ga4/reference/events#select_content) event.
4768

4869
```ts
4970
import { firebase } from '@nativescript/firebase-core';
@@ -55,25 +76,28 @@ firebase().analytics().logEvent('select_content', {
5576
item_id: 'abcd',
5677
});
5778
```
79+
After calling `logEvent`, look for your event name in the Analytics Realtime data to see if it's logged.
5880

5981
### Reserved Events
6082

61-
The Analytics package works out of the box, however a number of events are automatically reported to Firebase. These event names are called as 'Reserved Events'. Attempting to send any custom event using the logEvent method with any of the following event names will throw an error.
83+
In Analytics, the names of the automatically logged events are referred to as [Reserved Events](https://support.google.com/analytics/answer/13316687#zippy=%2Cmobile-android-and-ios). Creating custom events with those names results in an error. Below are some of the Reserved Events names:
84+
85+
| Reserved Events Names
86+
|:-------------------
87+
| `app_clear_data`
88+
| `error`
89+
| `first_open_time`
90+
| `notification_dismiss`
91+
| `notification_receive`
92+
| `screen_view`
93+
| `ad_click`
94+
| `adunit_exposure`
6295

63-
| Reserved Events Names | | |
64-
| :-------------------: | :---------------------: | :---------------: |
65-
| app_clear_data | app_uninstall | app_update |
66-
| error | first_open | first_visit |
67-
| first_open_time | first_visit_time | in_app_purchase |
68-
| notification_dismiss | notification_foreground | notification_open |
69-
| notification_receive | os_update | session_start |
70-
| screen_view | user_engagement | ad_impression |
71-
| ad_click | ad_query | ad_exposure |
72-
| adunit_exposure | ad_activeiew |
96+
For more Reserved event names, visit [Event naming rules](https://support.google.com/analytics/answer/13316687#zippy=%2Cmobile-android-and-ios).
7397

74-
### App instance id
98+
### Get the app instance id
7599

76-
Below is an example showing how to retrieve the app instance id of the application. This will return null on android if ConsentType.Analytics_Storage has been set to ConsentStatus.Denied.
100+
To get the app instance id of the application, call the `getAppInstanceId` method. This returns `null` on Android if `ConsentType.Analytics_Storage = ConsentStatus.Denied`.
77101

78102
```ts
79103
import { firebase } from '@nativescript/firebase-core';
@@ -83,19 +107,156 @@ const appInstanceId = firebase().analytics().getAppInstanceId();
83107

84108
### Disable Ad Id usage on iOS
85109

86-
Apple has a strict ban on the usage of Ad Ids ("IDFA") in Kids Category apps. They will not accept any app in the Kids category if the app accesses the IDFA iOS symbols.
110+
Apple strictly bans an app from being in the Kids category if the app accesses IDFA iOS symbols.
87111

88-
Additionally, apps must implement Apples "App Tracking Transparency" (or "ATT") requirements if they access IDFA symbols. However, if an app does not use IDFA and otherwise handles data in an ATT-compatible way, it eliminates this ATT requirement.
112+
Additionally, if an app accesses IDFA iOS symbols, it must implement Apple's [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency)(or `ATT`). However, if an app does not use IDFA and otherwise handles data in an ATT-compatible way, it eliminates this ATT requirement.
89113

90-
If you need to avoid IDFA usage while still using analytics, then you need to define the following variable in your Podfile:
114+
If you need to avoid IDFA usage while still using analytics, define the following variable in your Podfile:
91115

92116
```ruby
93117
$NSFirebaseAnalyticsWithoutAdIdSupport = true
94118
```
95119

96-
During pod install, using that variable installs a new "Analytics With No Ad Ids" pod the firebase-ios-sdk team has created, and allows both the use of Firebase Analytics in Kids Category apps, and use of Firebase Analytics without needing the App Tracking Transparency handling (assuming no other parts of your app handle data in a way that requires ATT)
120+
During pod install, using that variable installs a new `Analytics With No Ad Ids` pod that the firebase-ios-sdk team created, and allows both the use of Firebase Analytics in Kids Category apps and Firebase Analytics without needing the App Tracking Transparency handling (assuming no other parts of your app handles data in a way that requires ATT)
121+
122+
Note that for obvious reasons, configuring Firebase Analytics for use without IDFA is incompatible with AdMob.
123+
124+
## Analytics class API
125+
126+
The plugin offers you the Analytics class through which you can manage Firebase Analytics.
127+
The Analytics class has the following properties and methods.
128+
129+
### Properties
130+
|Property | Type
131+
|---------|-----
132+
| `appInstanceId` | `string`
133+
134+
### logEvent()
135+
```ts
136+
firebase().analytics()
137+
.logEvent(name, parameters)
138+
```
139+
Sends the specified event data to Google Analytics.
140+
| Parameter | Type | Description
141+
|-----------|------|-----------
142+
| `name` | `string`| The name of the event to log.
143+
| `parameters` | [EventParameter](#eventparameter)| An object specifying the event data. For the list of supported properties for `parameters` for a Reserved event, visit [FirebaseAnalytics.Param Constants Summary](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Param#constant-summary).
144+
145+
---
146+
### setUserId()
147+
148+
```ts
149+
firebase().analytics().setUserId(userId)
150+
```
151+
Allows you to store a user ID for the individual using your app. Read more about setting user ID [here](https://firebase.google.com/docs/analytics/userid).
152+
153+
---
154+
### resetAnalyticsData()
155+
```ts
156+
firebase().analytics().resetAnalyticsData()
157+
```
158+
See the description [here](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics#public-void-resetanalyticsdata).
159+
160+
---
161+
### setAnalyticsCollectionEnabled()
162+
```ts
163+
firebase().analytics().setAnalyticsCollectionEnabled(analyticsCollectionEnabled: boolean)
164+
```
165+
A method used to manually disable or enable the collection of analytics data.
166+
167+
- `analyticsCollectionEnabled`: A `boolean` value. If set to `true` analytics data is collected. If set to `false` analytics collection is disabled.
168+
---
169+
### setUserProperty()
170+
171+
```ts
172+
firebase().analytics().setUserProperty(name: string, value: string)
173+
```
174+
Sets a user property. For more details, see [Set user properties](https://firebase.google.com/docs/analytics/user-properties?platform=ios).
175+
176+
| Parameter | Type | Description
177+
|-----------|------|-----------
178+
| `name` | `string` | The name of the user property to set.
179+
| `value` | `string` | The value of the user property.
180+
181+
---
182+
### setSessionTimeoutInterval()
183+
```ts
184+
firebase().analytics().setSessionTimeoutInterval(sessionTimeoutInterval: number)
185+
```
186+
For the description, see [setSessionTimeoutDuration](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics#public-void-setsessiontimeoutduration-long-milliseconds).
187+
188+
| Parameter | Type | Description
189+
|-----------|------|------------
190+
| `sessionTimeoutInterval` | `number` | The duration of inactivity, in milliseconds. Defaults to `1800000` (`30` minutes).
191+
192+
---
193+
### setDefaultEventParameters()
194+
```ts
195+
firebase().analytics().setDefaultEventParameters(parameters)
196+
```
197+
Read the description [here](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics#public-void-setdefaulteventparameters-bundle-parameters).
198+
199+
| Parameter | Type | Description
200+
|----------|-------|------------
201+
| `parameters` | [EventParameter](#eventparameter) | Parameters object. For the list of supported properties for `parameters` for a Reserved event, visit [FirebaseAnalytics.Param Constants Summary](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Param#constant-summary).
202+
203+
#### EventParameter
204+
```ts
205+
interface EventParameter {
206+
[key: string]: any;
207+
}
208+
```
209+
---
210+
### setConsent()
211+
```ts
212+
firebase().analytics().setConsent(consentSettings)
213+
```
214+
See the description [here](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics#public-void-setconsent-mapfirebaseanalytics.consenttype,-firebaseanalytics.consentstatus-consentsettings).
215+
216+
| Parameter | Type | Description
217+
|----------|-------|------------
218+
| `consentSettings`| Map\<[ConsentType](#consenttype),[ConsentStatus](#consentstatus)\> |
219+
220+
#### ConsentType
221+
```ts
222+
enum ConsentType {
223+
Ad_Storage,
224+
Analytics_Storage,
225+
}
226+
```
227+
#### ConsentStatus
228+
```ts
229+
enum ConsentStatus {
230+
Denied,
231+
Granted,
232+
}
233+
```
234+
235+
---
236+
### handleOpenURL()
237+
```ts
238+
firebase().analytics().handleOpenURL(url)
239+
```
240+
241+
(`iOS-specific`)Handles the event when the app is launched by a URL.
242+
243+
| Parameter | Type | Description
244+
|----------|-------|------------
245+
| `url` | `string` | The URL from which to open the app.
246+
247+
---
248+
### handleUserActivity()
249+
```ts
250+
firebase().analytics().handleUserActivity(userActivity)
251+
```
252+
253+
(`iOS-specific`)Handles the event when the app receives data associated with user activity that includes a Universal Link (on iOS 9.0 and above).
254+
255+
| Parameter | Type | Description
256+
|----------|-------|------------
257+
| `userActivity` | `any` | The URL from which to open the app.
97258

98-
Note that for obvious reasons, configuring Firebase Analytics for use without IDFA is incompatible with AdMob
259+
---
99260

100261
## License
101262

0 commit comments

Comments
 (0)