Skip to content

Latest commit

 

History

History
274 lines (206 loc) · 10.8 KB

README.md

File metadata and controls

274 lines (206 loc) · 10.8 KB
Raw

@nativescript/firebase-analytics

Intro

This plugin allows you to add Google Analytics for Firebase to your app.

Note: Use this plugin with the @nativescript/firebase-core plugin to initialize Firebase in your app.

Analytics collects usage and behavior data for your app. Its two primary concerns are:

  • Events: 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, Recommended and Custom events.

  • user properties: Attributes you define to describe segments of your user base, such as language preference or geographic location.

image

Installation

Install the plugin by running the following command in the root directory of your project.

npm install @nativescript/firebase-analytics

Use @nativescript/firebase-analytics

The examples below show you how to use @nativescript/firebase-analytics to log custom and predefined events.

Log custom events

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.

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.

Please be aware that primitive data types or arrays of primitive data types are logged in your Firebase Analytics console.

import { firebase } from '@nativescript/firebase-core';
import '@nativescript/firebase-analytics';

firebase()
	.analytics()
	.logEvent('basket', {
		id: 3745092,
		item: 'mens grey t-shirt',
		description: ['round neck', 'long sleeved'],
		size: 'L',
	});

After calling logEvent, look for your event name in the Analytics Realtime data to see if it's logged.

Log Predefined Events

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.

To log a predefined event, call the logEvent method on the Analytics class instance passing it the event name and the event data object.

The following example demonstrates logging the select_content event.

import { firebase } from '@nativescript/firebase-core';

// Logs in the firebase analytics console as "select_content" event
// only accepts the two object properties which accept strings.
firebase().analytics().logEvent('select_content', {
	content_type: 'clothing',
	item_id: 'abcd',
});

After calling logEvent, look for your event name in the Analytics Realtime data to see if it's logged.

Reserved Events

In Analytics, the names of the automatically logged events are referred to as Reserved Events. Creating custom events with those names results in an error. Below are some of the Reserved Events names:

Reserved Events Names
app_clear_data
error
first_open_time
notification_dismiss
notification_receive
screen_view
ad_click
adunit_exposure

For more Reserved event names, visit Event naming rules.

Get the app instance id

To get the app instance id of the application, call the getAppInstanceId method. This returns null on Android if ConsentType.Analytics_Storage = ConsentStatus.Denied.

import { firebase } from '@nativescript/firebase-core';

const appInstanceId = firebase().analytics().getAppInstanceId();

Disable Identifier for Advertisers usage with analytics on iOS

Apple strictly bans an app from being in the Kids category if the app accesses Identifier for Advertisers(IDFA) iOS symbols.

Additionally, if an app accesses IDFA iOS symbols, it must implement Apple's App Tracking Transparency(or ATT). However, if an app does not use IDFA and otherwise handles data in an ATT-compatible way, it eliminates this ATT requirement.

If you need to avoid IDFA usage while still using analytics, define the following variable in your Podfile:

$NSFirebaseAnalyticsWithoutAdIdSupport = true

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)

Note that configuring Firebase Analytics for use without IDFA is incompatible with AdMob.

Demo app

You can find the demo app here.

Analytics class

The plugin offers you the Analytics class through which you can manage Firebase Analytics. The Analytics class has the following properties and methods.

Properties

Property Type
appInstanceId string

logEvent()

firebase().analytics()
		.logEvent(name, parameters)

Sends the specified event data to Google Analytics.

Parameter Type Description
name string The name of the event to log.
parameters EventParameter An object specifying the event data. For the list of supported properties for parameters for a Reserved event, visit FirebaseAnalytics.Param Constants Summary.

setUserId()

firebase().analytics().setUserId(userId)

Allows you to store a user ID for the individual using your app. Read more about setting user ID here.

resetAnalyticsData()

firebase().analytics().resetAnalyticsData()

See the description here.

setAnalyticsCollectionEnabled()

firebase().analytics().setAnalyticsCollectionEnabled(analyticsCollectionEnabled: boolean)

A method used to manually disable or enable the collection of analytics data.

  • analyticsCollectionEnabled: A boolean value. If set to true analytics data is collected. If set to false analytics collection is disabled.

setUserProperty()

firebase().analytics().setUserProperty(name: string, value: string)

Sets a user property. For more details, see Set user properties.

Parameter Type Description
name string The name of the user property to set.
value string The value of the user property.

setSessionTimeoutInterval()

firebase().analytics().setSessionTimeoutInterval(sessionTimeoutInterval: number)

For the description, see setSessionTimeoutDuration.

Parameter Type Description
sessionTimeoutInterval number The duration of inactivity, in milliseconds. Defaults to 1800000 (30 minutes).

setDefaultEventParameters()

firebase().analytics().setDefaultEventParameters(parameters)

Read the description here.

Parameter Type Description
parameters EventParameter Parameters object. For the list of supported properties for parameters for a Reserved event, visit FirebaseAnalytics.Param Constants Summary.

EventParameter

interface EventParameter {
	[key: string]: any;
}

setConsent()

firebase().analytics().setConsent(consentSettings)

See the description here.

Parameter Type Description
consentSettings Map<ConsentType,ConsentStatus>

ConsentType

enum ConsentType {
	Ad_Storage,
	Analytics_Storage,
	Ad_User_Data,
	Ad_Personalization,
}

ConsentStatus

enum ConsentStatus {
	Denied,
	Granted,
}

handleOpenURL()

firebase().analytics().handleOpenURL(url)

(iOS-specific)Handles the event when the app is launched by a URL.

Parameter Type Description
url string The URL from which to open the app.

handleUserActivity()

firebase().analytics().handleUserActivity(userActivity)

(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).

Parameter Type Description
userActivity any The URL from which to open the app.

License

Apache License Version 2.0