Deprecation notice

On November 13th 2018 Google issued the following statement:

> We want to let you know that in October 2019 we will begin to sunset our Google Analytics for mobile apps reporting and the Google Analytics Services SDK.
>
> Data collection and processing for such properties will stop on October 31, 2019.

The message is quite clear, and therefore I am officially deprecating this library. If you want to continue using Google's solutions for analytics, I recommend you move to Google Analytics for Firebase instead.

For React Native, there is a great library called react-native-firebase which implements Analytics (and other Firebase solutions).

I will continue to support this library for minor fixes, but no major changes will occur. The repository itself will be archived sometime in 2019.

Thanks to everyone who have used or contributed to this library!

\- Christian (@cbrevik)

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:

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

tracker.trackScreenView("Home");
tracker.trackEvent("testcategory", "testaction");
`

Version 6 breaking changes!

If you are upgrading to version 6 from an older version, read this wiki post for important details.

The newest version of this library has a new API surface. The API changes are in most cases backwards-compatible.

Important: If you are using ecommerce or custom dimensions, you probably have to migrate to new API if you upgrade!

Content

- Installation
- Manual installation
- Usage
- JavaScript API
- Problems with the library?
- See wiki for more helpful topics

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

`javascript
// 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);
});

// You can also register Function Call tag handlers when the container is open.
GoogleTagManager.registerFunctionCallTagHandler(
"some_function", // Must be equal to Function Name field when the tag was configured.
(functionName, tagArguments) => {
// functionName is passed for convenience. In this example it will be equal to "some_function".
// tagArguments is an object and is populated based on Tag configuration in TagManager interface.
console.log("Handling Function Call tag:", functionName);
}
)
`

JavaScript API

#### Table of Contents

- GoogleAnalyticsSettings
- setOptOut
- Parameters
- Examples
- setDispatchInterval
- Parameters
- Examples
- setDryRun
- Parameters
- Examples
- GoogleAnalyticsTracker
- Examples
- trackScreenView
- Parameters
- Examples
- trackEvent
- Parameters
- Examples
- trackTiming
- Parameters
- Examples
- trackException
- Parameters
- Examples
- trackSocialInteraction
- Parameters
- Examples
- setUser
- Parameters
- Examples
- setClient
- Parameters
- Examples
- getClientId
- Examples
- allowIDFA
- Parameters
- Examples
- setAppName
- Parameters
- Examples
- setAppVersion
- Parameters
- Examples
- setAnonymizeIp
- Parameters
- Examples
- setSamplingRate
- Parameters
- Examples
- setCurrency
- Parameters
- Examples
- setTrackUncaughtExceptions
- Parameters
- dispatch
- Examples
- dispatchWithTimeout
- Parameters
- Examples
- GoogleTagManager
- Examples
- openContainerWithId
- Parameters
- Examples
- refreshContainer
- Examples
- boolForKey
- Parameters
- Examples
- stringForKey
- Parameters
- Examples
- doubleForKey
- Parameters
- Examples
- pushDataLayerEvent
- Parameters
- Examples
- registerFunctionCallTagHandler
- Parameters
- setVerboseLoggingEnabled
- Parameters
- TimingMetadata
- Parameters
- Examples
- EventMetadata
- Parameters
- Examples
- HitPayload
- Parameters
- Examples
- CustomDimensionsByField
- Examples
- CustomDimensionsByIndex
- Examples
- CustomDimensionsFieldIndexMap
- Examples
- CustomMetrics
- Examples
- DataLayerEvent
- Parameters
- Examples
- ProductActionEnum
- Product
- Parameters
- Examples
- ProductAction
- Parameters
- Examples
- Transaction
- Parameters
- Examples

$3

Settings which are applied across all trackers.

#### setOptOut

Sets if OptOut is active and disables Google Analytics. This is disabled by default. Note: This has to be set each time the App starts.

##### Parameters

- enabled boolean

##### Examples

`javascript
GoogleAnalyticsSettings.setOptOut(true);
`

#### setDispatchInterval

Sets the trackers dispatch interval.
Events, screen views, etc, are sent in batches to your tracker. This function allows you to configure how often (in seconds) the batches are sent to your tracker. Recommended to keep this around 20-120 seconds to preserve battery and network traffic. This is set to 20 seconds by default.

##### Parameters

- intervalInSeconds number

##### Examples

`javascript
GoogleAnalyticsSettings.setDispatchInterval(30);
`

#### setDryRun

When enabled the native library prevents any data from being sent to Google Analytics. This allows you to test or debug the implementation, without your test data appearing in your Google Analytics reports.

##### Parameters

- enabled boolean

##### Examples

`javascript
GoogleAnalyticsSettings.setDryRun(true);
`

$3

#### Examples

`javascript
// Constructing a tracker is simple:
import { GoogleAnalyticsTracker } from "react-native-google-analytics-bridge";
const tracker = new GoogleAnalyticsTracker("UA-12345-1");
tracker.trackScreenView("Home");

// You can have multiple trackers if you have several tracking ids
const tracker2 = new GoogleAnalyticsTracker("UA-12345-2");
`

`javascript
// One optional feature as well is constructing a tracker with a CustomDimensionsFieldIndexMap, to map custom dimension field names to index keys:
const fieldIndexMap = { customerType: 1 };
const tracker3 = new GoogleAnalyticsTracker("UA-12345-3", fieldIndexMap);

// This is because the Google Analytics API expects custom dimensions to be tracked by index keys, and not field names.
// Here the underlying logic will transform the custom dimension, so what ends up being sent to GA is { 1: 'Premium' }:
tracker3.trackScreenView("Home", { customDimensions: { customerType: "Premium" } });

// If you do not use a CustomDimensionsFieldIndexMap, you will have to use index as keys instead for custom dimensions:
tracker.trackScreenView("Home", { customDimensions: { 1: "Premium" } });
`

#### trackScreenView

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.

##### Parameters

- screenName string (Required) The name of the current screen
- payload HitPayload (Optional) An object containing the hit payload (optional, default null)

##### Examples

`javascript
tracker.trackScreenView('Home');
`

`javascript
// With payload:
const payload = { impressionList: "Sale", impressionProducts: [ { id: "PW928", name: "Premium bundle" } ] };
tracker.trackScreenView("SplashModal", payload);
`

#### trackEvent

Track an event that has occured

##### Parameters

- category string (Required) The event category
- action string (Required) The event action
- eventMetadata EventMetadata (Optional) An object containing event metadata
- payload HitPayload (Optional) An object containing the hit payload (optional, default null)

##### Examples

`javascript
tracker.trackEvent("DetailsButton", "Click");
`

`javascript
// Track event with label and value
tracker.trackEvent("AppVersionButton", "Click", { label: "v1.0.3", value: 22 });
`

`javascript
// Track with a payload (ecommerce in this case):
const product = {
id: "P12345",
name: "Android Warhol T-Shirt",
category: "Apparel/T-Shirts",
brand: "Google",
variant: "Black",
price: 29.2,
quantity: 1,
couponCode: "APPARELSALE"
};
const transaction = {
id: "T12345",
affiliation: "Google Store - Online",
revenue: 37.39,
tax: 2.85,
shipping: 5.34,
couponCode: "SUMMER2013"
};
const productAction = {
transaction,
action: 7 // Purchase action, see ProductActionEnum
}
const payload = { products: [ product ], productAction: productAction }
tracker.trackEvent("FinalizeOrderButton", "Click", null, payload);
`

#### trackTiming

Track a timing measurement

##### Parameters

- category string (Required) The event category
- interval number (Required) The timing measurement in milliseconds
- timingMetadata TimingMetadata (Required) An object containing timing metadata
- payload HitPayload (Optional) An object containing the hit payload (optional, default null)

##### Examples

`javascript
tracker.trackTiming("testcategory", 2000, { name: "LoadList" }); // name metadata is required
`

`javascript
// With optional label:
tracker.trackTiming("testcategory", 2000, { name: "LoadList", label: "v1.0.3" });
`

#### trackException

Track an exception

##### Parameters

- error string (Required) The description of the error
- fatal boolean (Optional) A value indiciating if the error was fatal, defaults to false (optional, default false)
- payload HitPayload (Optional) An object containing the hit payload (optional, default null)

##### Examples

`javascript
try {
...
} catch(error) {
tracker.trackException(error.message, false);
}
`

#### trackSocialInteraction

Track a social interaction, Facebook, Twitter, etc.

##### Parameters

- network string
- action string
- targetUrl string
- payload HitPayload (Optional) An object containing the hit payload

##### Examples

`javascript
tracker.trackSocialInteraction("Twitter", "Post");
`

#### setUser

Sets the current userId for tracking.

##### Parameters

- userId string An anonymous identifier that complies with Google Analytic's user ID policy

##### Examples

`javascript
tracker.setUser("12345678");
`

#### setClient

Sets the current clientId for tracking.

##### Parameters

- clientId string A anonymous identifier that complies with Google Analytic's client ID policy

##### Examples

`javascript
tracker.setClient("35009a79-1a05-49d7-b876-2b884d0f825b");
`

#### getClientId

Get the client id to be used for purpose of logging etc.

##### Examples

`javascript
tracker.getClientId().then(clientId => console.log("Client id is: ", clientId));
`

Returns Promise<string>

#### allowIDFA

Also called advertising identifier collection, and is used for advertising features.

Important: For iOS you can only use this method if you have done the optional step 6 from the installation guide. Only enable this (and link the appropriate libraries) if you plan to use advertising features in your app, or else your app may get rejected from the AppStore.

##### Parameters

- enabled boolean (Optional) Defaults to true (optional, default true)

##### Examples

`javascript
tracker.allowIDFA(true);
`

#### setAppName

Overrides the app name logged in Google Analytics. The Bundle name is used by default. Note: This has to be set each time the App starts.

##### Parameters

- appName string (Required)

##### Examples

`javascript
tracker.setAppName("YourAwesomeApp");
`

#### setAppVersion

Sets the trackers appVersion

##### Parameters

- appVersion string (Required)

##### Examples

`javascript
tracker.setAppVersion("1.3.2");
`

#### setAnonymizeIp

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

##### Parameters

- enabled boolean (Required)

##### Examples

`javascript
tracker.setAnonymizeIp(true);
`

#### setSamplingRate

Sets tracker sampling rate.

##### Parameters

- sampleRatio number (Required) Percentage 0 - 100

##### Examples

`javascript
tracker.setSamplingRate(50);
`

#### setCurrency

Sets the currency for tracking.

##### Parameters

- currencyCode string (Required) The currency ISO 4217 code

##### Examples

`javascript
tracker.setCurrency("EUR");
`

#### setTrackUncaughtExceptions

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.

##### Parameters

- enabled boolean

#### dispatch

This function lets you manually dispatch all hits which are queued.
Use this function sparingly, as it will normally happen automatically
as a batch. This function will also dispatch for all trackers.

##### Examples

`javascript
tracker.dispatch().then(done => console.log("Dispatch is done: ", done));
`

Returns Promise<boolean> Returns when done

#### dispatchWithTimeout

The same as dispatch, but also gives you the ability to time out
the Promise in case dispatch takes too long.

##### Parameters

- timeout number The timeout. Default value is 15 sec. (optional, default -1)

##### Examples

`javascript
tracker
.dispatchWithTimeout(10000)
.then(done => console.log("Dispatch is done: ", done));
`

Returns Promise<boolean> Returns when done or timed out

$3

Can only be used with one container. All functions returns a Promise.

#### Examples

`javascript
import { GoogleTagManager } from "react-native-google-analytics-bridge";
GoogleTagManager.openContainerWithId("GT-NZT48")
.then(() => GoogleTagManager.stringForKey("pack"))
.then(str => console.log("Pack: ", str));
`

#### openContainerWithId

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

##### Parameters

- containerId string

##### Examples

`javascript
GoogleTagManager.openContainerWithId('GT-NZT48').then((..) => ..)
`

Returns Promise<boolean>

#### refreshContainer

Refreshes the GTM container.
According to Tag Manager documentations for Android can be called once every 15 minutes.
No such limitations has been mentioned for iOS containers, though.

##### Examples

`javascript
GoogleTagManager.refreshContainer().then((..) => ..)
`

Returns Promise<boolean>

#### boolForKey

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

##### Parameters

- key string

##### Examples

`javascript
GoogleTagManager.boolForKey("key").then(val => console.log(val));
`

Returns Promise<boolean>

#### stringForKey

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

##### Parameters

- key string

##### Examples

`javascript
GoogleTagManager.stringForKey("key").then(val => console.log(val));
`

Returns Promise<string>

#### doubleForKey

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

##### Parameters

- key string

##### Examples

`javascript
GoogleTagManager.doubleForKey("key").then(val => console.log(val));
`

Returns Promise<number>

#### pushDataLayerEvent

Push a datalayer event for Google Analytics through Google Tag Manager. The event must have at least one key "event" with event name.

##### Parameters

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

##### Examples

`javascript
GoogleTagManager.pushDataLayerEvent({
event: "eventName",
pageId: "/home"
}).then(success => console.log(success));
`

Returns Promise<boolean>

#### registerFunctionCallTagHandler

Register Function Call tag handler

##### Parameters

- functionName String
- handler Function

#### setVerboseLoggingEnabled

Sets logger to verbose, default is warning

##### Parameters

- enabled boolean

$3

Used when tracking time measurements

#### Parameters

- name string (Required)
- label string (Optional)

#### Examples

`javascript
const timingMetadata = { name: "LoadList" } // name is a required value when tracking timing
tracker.trackTiming("testcategory", 13000, timingMetadata);
`

$3

Used when tracking event

#### Parameters

- label string (Optional)
- value number (Optional)

#### Examples

`javascript
const eventMetadata = { label: "v1.0.3", value: 22 }
tracker.trackEvent("FinalizeOrderButton", "Click", eventMetadata);
`

$3

The HitPayload object and possible values

Used by the different tracking methods for adding metadata to the hit.

#### Parameters

- products Array<Product> (Optional) Used for ecommerce
- impressionProducts Array<Product> (Optional) Used for ecommerce
- impressionList string (Optional) Used for ecommerce
- impressionSource string (Optional) Used for ecommerce
- productAction ProductAction (Optional) Used for ecommerce
- customDimensions (CustomDimensionsByIndex \| CustomDimensionsByField) (Optional)
- customMetrics CustomMetrics (Optional)
- utmCampaignUrl string (Optional) Used for campaigns
- session string (Optional) Only two possible values, "start" or "end". This will either start or end a session.

#### Examples

`javascript
// If you want to do send a purchase payload with an event:
const product = {
id: "P12345",
name: "Android Warhol T-Shirt",
category: "Apparel/T-Shirts",
brand: "Google",
variant: "Black",
price: 29.2,
quantity: 1,
couponCode: "APPARELSALE"
};
const transaction = {
id: "T12345",
affiliation: "Google Store - Online",
revenue: 37.39,
tax: 2.85,
shipping: 5.34,
couponCode: "SUMMER2013"
};
const productAction = {
transaction,
action: 7 // Purchase action, see ProductActionEnum
}
const payload = { products: [ product ], productAction: productAction }
tracker.trackEvent("FinalizeOrderButton", "Click", null, payload);
`

`javascript
// If you want to send custom dimensions with a screen view:
const customDimensions = {
1: "Beta",
3: "Premium"
};
const payload = { customDimensions };
tracker.trackScreenView("SaleScreen", payload);
`

$3

- See: CustomDimensionsFieldIndexMap
- See: CustomDimensionsByIndex

A dictionary with custom dimensions values and their (mapped) field name keys.
In order to use this and send in custom dimensions by field name, you must have
provided a CustomDimensionsFieldIndexMap when constructing the tracker.

#### Examples

`javascript
const customDimensions = { customerType: "Premium", appType: "Beta", credit: 1200 }
tracker.trackScreenView("Home", { customDimensions });
`

$3

- See: CustomDimensionsFieldIndexMap
- See: CustomDimensionsByField

A dictionary with custom dimensions values and their index keys.

#### Examples

`javascript
const customDimensions = { 1: "Premium", 3: "Beta", 5: 1200 }
tracker.trackScreenView("Home", { customDimensions });
`

$3

- See: CustomDimensionsFieldIndexMap
- See: CustomDimensionsByField

A dictionary describing mapping of field names to indices for custom dimensions.
This is an optional object used by the tracker.

#### Examples

`javascript
// Create something like:
const fieldIndexMap = { customerType: 1 };
// Construct tracker with it:
const tracker = new GoogleAnalyticsTracker("UA-12345-3", fieldIndexMap);
// This allows you to send in customDimensions in theHitPayload by field name instead of index:
tracker.trackScreenView("Home", { customDimensions: { customerType: "Premium" } });
// If you do not provide a map, you instead have to send in by index:
tracker.trackScreenView("Home", { customDimensions: { 1: "Premium" } });
``

$3

A dictionary with custom metric values and their index keys.

#### Examples

`javascript
const customMetrics = { 1: 2389, 4: 15000 }
tracker.trackScreenView("Home", { customMetrics });
`

$3

The Google Tag Manager DataLayerEvent dictionary.

Populate this event-object with values to push to the DataLayer. The only required property is event.

#### Parameters

- event string

#### Examples

`javascript
const dataLayerEvent = {
event: "eventName",
pageId: "/home"
};
GoogleTagManager.pushDataLayerEvent(dataLayerEvent);
`

$3

Enhanced Ecommerce ProductActionEnum

Used by ProductAction when describing the type of product action. The possible values (numbers) are:

- Detail = 1,
- Click = 2,
- Add = 3,
- Remove = 4,
- Checkout = 5,
- CheckoutOption = 6,
- Purchase = 7,
- Refund = 8

$3

Enhanced Ecommerce Product

Used by HitPayload when populating product actions or impressions

#### Parameters

- id string
- name string
- category string (Optional)
- brand string (Optional)
- variant string (Optional)
- price number (Optional)
- couponCode string (Optional)
- quantity number (Optional)

#### Examples

`javascript
const product = {
id: "P12345",
name: "Android Warhol T-Shirt",
category: "Apparel/T-Shirts",
brand: "Google",
variant: "Black",
price: 29.2,
quantity: 1,
couponCode: "APPARELSALE"
};
`

$3

Enhanced Ecommerce Product Action

Used by HitPayload when describing a product action

#### Parameters

- action ProductActionEnum
- transaction Transaction (Optional)
- checkoutStep number (Optional)
- checkoutOption string (Optional)
- productActionList string (Optional)
- productListSource string (Optional)

#### Examples

`javascript
const productAction = {
transaction,
action: 7 // Purchase action, see ProductActionEnum
}
`

`javascript
const productAction = {
action: 3 // Add action, see ProductActionEnum
}
`

$3

Enhanced Ecommerce Transaction

Used by ProductAction when populating describing a purchase/transaction

#### Parameters

- id string
- affiliation string (Optional)
- revenue number (Optional - but not really)
- tax number (Optional)
- shipping number (Optional)
- couponCode string (Optional)

#### Examples

`javascript
const transaction = {
id: "T12345",
affiliation: "Google Store - Online",
revenue: 37.39,
tax: 2.85,
shipping: 5.34,
couponCode: "SUMMER2013"
};
``