react-native-google-analytics-bridge

GoogleAnalyticsBridge

Google Analytics Bridge is built to provide an easy interface to the native Google Analytics libraries on both iOS and Android.

Why a native bridge? Why not use just JavaScript?

The key difference with the native bridge is that you get a lot of the metadata handled automatically by the Google Analytics native library. This will include the device UUID, device model, viewport size, OS version etc.

You will only have to send in a few parameteres when tracking, e.g:

import { GoogleAnalyticsTracker } from 'react-native-google-analytics-bridge';
let tracker = new GoogleAnalyticsTracker('UA-12345-1');

tracker.trackScreenView('Home');
tracker.trackEvent('testcategory', 'testaction');

Content

• Installation
• Manual installation
• Usage
• JavaScript API
• Troubleshooting
• A/B testing
• Roadmap

Installation and linking libraries

• For React Native >= 0.40 use version 5.0.0 (and up) of this module.
• For React Native < 0.40 use version 4.0.3.

Install with npm: npm install --save react-native-google-analytics-bridge

Or, install with yarn: yarn add react-native-google-analytics-bridge

Either way, then link with: react-native link react-native-google-analytics-bridge

If it doesn't work immediately after this, consult the manual installation guide. Both Android and iOS has a couple of prerequisite SDKs linked and installed.

Important: Does this library work with Expo? We have to sort of invert the question a bit, because it should be: does Expo work with other libraries? And the answer is no:

The most limiting thing about Expo is that you can’t add in your own native modules without detaching and using ExpoKit.

This includes using create-react-native-app which also makes use of Expo.

Usage

// You have access to three classes in this module:
import {
  GoogleAnalyticsTracker,
  GoogleTagManager,
  GoogleAnalyticsSettings
} from 'react-native-google-analytics-bridge';

// The tracker must be constructed, and you can have multiple:
let tracker1 = new GoogleAnalyticsTracker('UA-12345-1');
let tracker2 = new GoogleAnalyticsTracker('UA-12345-2');

tracker1.trackScreenView('Home');
tracker1.trackEvent('Customer', 'New');

// The GoogleAnalyticsSettings is static, and settings are applied across all trackers:
GoogleAnalyticsSettings.setDispatchInterval(30);
// Setting `dryRun` to `true` lets you test tracking without sending data to GA 
GoogleAnalyticsSettings.setDryRun(true);

// GoogleTagManager is also static, and works only with one container. All functions here are Promises:
GoogleTagManager.openContainerWithId("GT-NZT48")
  .then(() => {
    return GoogleTagManager.stringForKey("pack");
  })
  .then((pack) => {
    console.log("Pack: ", pack);
  })
  .catch((err) => {
    console.log(err);
  });

JavaScript API

There are three classes which can be imported from the react-native-google-analytics-bridge module.

Classes

CustomDimensionsFieldIndexMap

CustomDimensionsByIndex

CustomDimensionsByField

CustomMetrics

GoogleAnalyticsSettings

GoogleAnalyticsTracker

GoogleTagManager

HitPayload

Hit

ScreenHit ⇐ Hit

EventHit ⇐ Hit

TimingHit ⇐ Hit

ExceptionHit ⇐ Hit

SocialHit ⇐ Hit

NewGoogleAnalyticsTracker

CustomDimensionsFieldIndexMap

Kind: global class
Export:

CustomDimensionsByIndex

Kind: global class
Export:

CustomDimensionsByField

Kind: global class
Export:

CustomMetrics

Kind: global class
Export:

GoogleAnalyticsSettings

Kind: global class

• GoogleAnalyticsSettings
  • .setOptOut(enabled)
  • .setDispatchInterval(intervalInSeconds)
  • .setDryRun(enabled)

GoogleAnalyticsSettings.setOptOut(enabled)

Sets if OptOut is active and disables Google Analytics This has to be set each time the App starts

Kind: static method of GoogleAnalyticsSettings

Param	Type
enabled	boolean

GoogleAnalyticsSettings.setDispatchInterval(intervalInSeconds)

Sets the trackers dispatch interval This will influence how often batches of events, screen views, etc are sent to your tracker.

Kind: static method of GoogleAnalyticsSettings

Param	Type
intervalInSeconds	number

GoogleAnalyticsSettings.setDryRun(enabled)

Sets if the tracker should have dry run enabled. If dry run is enabled, no analytics data will be sent to your tracker.

Kind: static method of GoogleAnalyticsSettings

Param	Type
enabled	boolean

GoogleAnalyticsTracker

Kind: global class

• GoogleAnalyticsTracker
  • new GoogleAnalyticsTracker(trackerId, customDimensionsFieldsIndexMap)
  • .trackScreenView(screenName, payload)
  • .trackEvent(category, action, payload, label, value)
  • .trackTiming(category, interval, payload, name, label)
  • .trackException(error, fatal, payload)
  • .trackSocialInteraction(network, action, targetUrl, payload)
  • .setUser(userId)
  • .setClient(clientId)
  • .allowIDFA(enabled)
  • .setAppName(appName)
  • .setAppVersion(appVersion)
  • .setAnonymizeIp(enabled)
  • .setSamplingRate(sampleRatio)
  • .setCurrency(currencyCode)
  • .setTrackUncaughtExceptions(enabled)

new GoogleAnalyticsTracker(trackerId, customDimensionsFieldsIndexMap)

Save all tracker related data that is needed to call native methods with proper data.

Param	Type	Description
trackerId	string	Your tracker id, something like: UA-12345-1
customDimensionsFieldsIndexMap	Object	Custom dimensions field/index pairs

Example

import { GoogleAnalyticsTracker } from 'react-native-google-analytics-bridge';
let tracker = new GoogleAnalyticsTracker('UA-12345-1');

tracker.trackScreenView(screenName, payload)

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Default	Description
screenName	string		(Required) The name of the current screen
payload	Object		(Optional) An object containing the hit payload

Example

tracker.trackScreenView('Home')

Track the current screen/view. Calling this will also set the "current view" for other calls. So events tracked will be tagged as having occured on the current view, Home in this example. This means it is important to track navigation, especially if events can fire on different views.

tracker.trackEvent(category, action, payload, label, value)

Track an event that has occured

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Default	Description
category	string		(Required) The event category
action	string		(Required) The event action
payload	Object		(Optional) An object containing the hit payload
label	string	null	(Optional) An optional event label
value	number		(Optional) An optional event value

tracker.trackTiming(category, interval, payload, name, label)

Track an event that has occured

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Default	Description
category	string		(Required) The event category
interval	number		(Required) The timing measurement in milliseconds
payload	Object		(Optional) An object containing the hit payload
name	string	null	(Required) The timing name
label	string	null	(Optional) An optional timing label

tracker.trackException(error, fatal, payload)

Track an exception

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Default	Description
error	string		(Required) The description of the error
fatal	boolean	false	(Optional) A value indiciating if the error was fatal, defaults to false
payload	Object		(Optional) An object containing the hit payload

tracker.trackSocialInteraction(network, action, targetUrl, payload)

Track a social interaction, Facebook, Twitter, etc.

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
network	string
action	string
targetUrl	string
payload	Object	(Optional) An object containing the hit payload

tracker.setUser(userId)

Sets the current userId for tracking.

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
userId	string	The current userId

tracker.setClient(clientId)

Sets the current clientId for tracking.

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
clientId	string	The current userId

tracker.allowIDFA(enabled)

Sets if IDFA (identifier for advertisers) collection should be enabled

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Default	Description
enabled	boolean	true	(Optional) Defaults to true

tracker.setAppName(appName)

Sets the trackers appName The Bundle name is used by default

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
appName	string	(Required)

tracker.setAppVersion(appVersion)

Sets the trackers appVersion

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
appVersion	string	(Required)

tracker.setAnonymizeIp(enabled)

Sets if AnonymizeIp is enabled If enabled the last octet of the IP address will be removed

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
enabled	boolean	(Required)

tracker.setSamplingRate(sampleRatio)

Sets tracker sampling rate.

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
sampleRatio	number	(Required) Percentage 0 - 100

tracker.setCurrency(currencyCode)

Sets the currency for tracking.

Kind: instance method of GoogleAnalyticsTracker

Param	Type	Description
currencyCode	string	(Required) The currency ISO 4217 code

tracker.setTrackUncaughtExceptions(enabled)

Sets if uncaught exceptions should be tracked Important to note: On iOS this option is set on all trackers. On Android it is set per tracker. If you are using multiple trackers on iOS, this will enable & disable on all trackers.

Kind: instance method of GoogleAnalyticsTracker

Param	Type
enabled	boolean

GoogleTagManager

Kind: global class

• GoogleTagManager
  • .openContainerWithId(containerId) ⇒ Promise.<boolean>
  • .boolForKey(key) ⇒ Promise.<boolean>
  • .stringForKey(key) ⇒ Promise.<string>
  • .doubleForKey(key) ⇒ Promise.<number>
  • .pushDataLayerEvent(event) ⇒ Promise.<boolean>

GoogleTagManager.openContainerWithId(containerId) ⇒ Promise.<boolean>

Call once to open the container for all subsequent static calls.

Kind: static method of GoogleTagManager

Param	Type
containerId	string

GoogleTagManager.boolForKey(key) ⇒ Promise.<boolean>

Retrieves a boolean value with the given key from the opened container.

Kind: static method of GoogleTagManager

Param	Type
key	string

GoogleTagManager.stringForKey(key) ⇒ Promise.<string>

Retrieves a string with the given key from the opened container.

Kind: static method of GoogleTagManager

Param	Type
key	string

GoogleTagManager.doubleForKey(key) ⇒ Promise.<number>

Retrieves a number with the given key from the opened container.

Kind: static method of GoogleTagManager

Param	Type
key	string

GoogleTagManager.pushDataLayerEvent(event) ⇒ Promise.<boolean>

Push a datalayer event for Google Analytics through Google Tag Manager. The event must have at least one key "event" with event name. You can add optional values on top of that, example: {event: "eventName", pageId: "/home"}

Kind: static method of GoogleTagManager

Param	Type	Description
event	Object	An Map<String, Object> containing key and value pairs. It must have at least one key "event" with event name

HitPayload

Kind: global class
Properties

Name	Type	Description
products	Array.<Product>	(Optional) Products which an action has occured on.
productAction	ProductAction	(Optional) The action which occured on the products. Required if products is not empty.
impressionProducts	Array.<Product>	(Optional) Products which has had an impression.
impressionList	string	(Optional) The list which product impressions occured on. Required if impressionProducts is not empty.
impressionSource	string	(Optional) The source which impression occured from (Android only).
customDimensions	CustomDimensionsByIndex | CustomDimensionsByField	(Optional) Custom dimensions.
customMetrics	CustomMetrics	(Optional) Custom metrics.
utmCampaignUrl	string	(Optional) UTM campaign URL.
startSession	number	(Optional) Start new session.

• HitPayload
  • new HitPayload()
  • .addProduct(product) ⇒ HitPayload
  • .addProductImpression(product) ⇒ HitPayload

new HitPayload()

All properties on the payload is optional. Preferably leave them empty unless you actually need to send something extra.

payload.addProduct(product) ⇒ HitPayload

Adds a product in the payload. productAction must also be set on the payload if you add products.

Kind: instance method of HitPayload

Param	Type
product	Product

payload.addProductImpression(product) ⇒ HitPayload

Adds a product impression. impressionList must also be set on the payload if you add impression products.

Kind: instance method of HitPayload

Param	Type
product	Product

Hit

Kind: global class
Properties

Name	Type	Default	Description
payload	HitPayload		(Optional) Payload to send with the hit.

new Hit()

Base class for all Hits.

ScreenHit ⇐ Hit

Kind: global class
Extends: Hit
Export:
Properties

Name	Type	Description
screenName	string	The current screen name.

• ScreenHit ⇐ Hit
  • .ScreenHit
    • new ScreenHit(screenName)

ScreenHit.ScreenHit

Kind: static class of ScreenHit

new ScreenHit(screenName)

Creates an instance of ScreenHit.

Param	Type
screenName	string

EventHit ⇐ Hit

Kind: global class
Extends: Hit
Export:
Properties

Name	Type	Default	Description
category	string		The event category
action	string		The event action
label	string	null	The event label
value	number		The event value

• EventHit ⇐ Hit
  • .EventHit
    • new EventHit(category, action, [label], [value])

EventHit.EventHit

Kind: static class of EventHit

new EventHit(category, action, [label], [value])

Creates an instance of EventHit.

Param	Type	Default
category	string
action	string
[label]	string	null
[value]	number

TimingHit ⇐ Hit

Kind: global class
Extends: Hit
Export:
Properties

Name	Type	Default	Description
category	string		The timing category
interval	number		The timing interval
name	string		The timing name
label	string	null	The timing label

• TimingHit ⇐ Hit
  • .TimingHit
    • new TimingHit(category, interval, name, [label])

TimingHit.TimingHit

Kind: static class of TimingHit

new TimingHit(category, interval, name, [label])

Creates an instance of TimingHit.

Param	Type	Default
category	string
interval	number
name	string
[label]	string	null

ExceptionHit ⇐ Hit

Kind: global class
Extends: Hit
Export:
Properties

Name	Type	Default	Description
error	string		The error
fatal	boolean	false	If the error was fatal. Defaults to false.

• ExceptionHit ⇐ Hit
  • .ExceptionHit
    • new ExceptionHit(error, [fatal])

ExceptionHit.ExceptionHit

Kind: static class of ExceptionHit

new ExceptionHit(error, [fatal])

Creates an instance of ExceptionHit.

Param	Type	Default
error	string
[fatal]	boolean	false

SocialHit ⇐ Hit

Kind: global class
Extends: Hit
Export:
Properties

Name	Type	Description
network	string	The social network
action	string	The social action. +1, like, etc
targetUrl	string	The target url.

• SocialHit ⇐ Hit
  • .SocialHit
    • new SocialHit(network, action, targetUrl)

SocialHit.SocialHit

Kind: static class of SocialHit

new SocialHit(network, action, targetUrl)

Creates an instance of SocialHit.

Param	Type
network	string
action	string
targetUrl	string

NewGoogleAnalyticsTracker

Kind: global class

• NewGoogleAnalyticsTracker
  • new NewGoogleAnalyticsTracker(trackerId, customDimensionsFieldsIndexMap)
  • .trackScreen(screenName)
  • .trackScreenHit(hit)
  • .trackEvent(category, action, [label], [value])
  • .trackEvenHit(hit)
  • .trackTiming(category, interval, name, [label])
  • .trackTimingHit(hit)
  • .trackException(error, [fatal])
  • .trackExceptionHit(hit)
  • .trackSocial(network, action, targetUrl)
  • .trackSocialHit(hit)
  • .setUser(userId)
  • .setClient(clientId)
  • .allowIDFA(enabled)
  • .setAppName(appName)
  • .setAppVersion(appVersion)
  • .setAnonymizeIp(enabled)
  • .setSamplingRate(sampleRatio)
  • .setCurrency(currencyCode)
  • .setTrackUncaughtExceptions(enabled)

new NewGoogleAnalyticsTracker(trackerId, customDimensionsFieldsIndexMap)

Save all tracker related data that is needed to call native methods with proper data.

Param	Type	Description
trackerId	string	Your tracker id, something like: UA-12345-1
customDimensionsFieldsIndexMap	Object	Custom dimensions field/index pairs

Example

import { GoogleAnalyticsTracker } from 'react-native-google-analytics-bridge';
let tracker = new GoogleAnalyticsTracker('UA-12345-1');

tracker.trackScreen(screenName)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
screenName	string

tracker.trackScreenHit(hit)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
hit	ScreenHit

tracker.trackEvent(category, action, [label], [value])

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Default
category	string
action	string
[label]	string	null
[value]	number

tracker.trackEvenHit(hit)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
hit	EventHit

tracker.trackTiming(category, interval, name, [label])

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Default
category	string
interval	number
name	string
[label]	string	null

tracker.trackTimingHit(hit)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
hit	TimingHit

tracker.trackException(error, [fatal])

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Default
error	string
[fatal]	boolean	false

tracker.trackExceptionHit(hit)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
hit	ExceptionHit

tracker.trackSocial(network, action, targetUrl)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
network	string
action	string
targetUrl	string

tracker.trackSocialHit(hit)

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type
hit	SocialHit

tracker.setUser(userId)

Sets the current userId for tracking.

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
userId	string	The current userId

tracker.setClient(clientId)

Sets the current clientId for tracking.

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
clientId	string	The current userId

tracker.allowIDFA(enabled)

Sets if IDFA (identifier for advertisers) collection should be enabled

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Default	Description
enabled	boolean	true	(Optional) Defaults to true

tracker.setAppName(appName)

Sets the trackers appName The Bundle name is used by default

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
appName	string	(Required) The app name

tracker.setAppVersion(appVersion)

Sets the trackers appVersion

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
appVersion	string	(Required) The app version

tracker.setAnonymizeIp(enabled)

Sets if AnonymizeIp is enabled If enabled the last octet of the IP address will be removed

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
enabled	boolean	(Required) Enable anonymize IP

tracker.setSamplingRate(sampleRatio)

Sets tracker sampling rate.

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
sampleRatio	number	(Required) Percentage 0 - 100

tracker.setCurrency(currencyCode)

Sets the currency for tracking.

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
currencyCode	string	(Required) The currency ISO 4217 code

tracker.setTrackUncaughtExceptions(enabled)

Sets if uncaught exceptions should be tracked Important to note: On iOS this option is set on all trackers. On Android it is set per tracker. If you are using multiple trackers on iOS, this will enable & disable on all trackers.

Kind: instance method of NewGoogleAnalyticsTracker

Param	Type	Description
enabled	boolean	Should enable uncaught exception tracking