Matomo Tracker (React Native/Expo)

Stand alone library for using Matomo tracking in React Native and Expo projects.

There is one React Native Matomo package mentioned on the official integration docs of Matomo, which sadly cannot be used with Expo because of native modules that are included.

If you know React Native already but have not heard about Expo yet, you can read about it here in their docs.

This package aims for making tracking available in every React Native app with sending custom actions to the Matomo Tracking HTTP API.

There are two existing implementations for Node.js and React, that built the basis for this React Native package. Thanks to:

• https://github.com/matomo-org/matomo-nodejs-tracker
• https://github.com/Amsterdam/matomo-tracker

Installation

# with npm:

npm install matomo-tracker-react-native

# or with yarn:

yarn add matomo-tracker-react-native

Usage

You need to create a Matomo instance within your project with your specific Matomo details and wrap your app with the MatomoProvider of this package.

The useMatomo hook is exposing all methods you can use for several trackings.

import React, { useEffect } from 'react';
import MatomoTracker, { MatomoProvider, useMatomo } from 'matomo-tracker-react-native';

const MainAppContainer = () => {
  const { trackAppStart } = useMatomo();

  useEffect(() => {
    trackAppStart();
  }, []);

  return (
    <View>Main App</View>
  );
};

export const App = () => {
  const instance = new MatomoTracker({
    urlBase: 'https://LINK.TO.DOMAIN', // required
    // trackerUrl: 'https://LINK.TO.DOMAIN/tracking.php', // optional, default value: `${urlBase}matomo.php`
    siteId: 1, // required, number matching your Matomo project
    // userId: 'UID76903202' // optional, default value: `undefined`.
    // disabled: false, // optional, default value: false. Disables all tracking operations if set to true.
    // log: false  // optional, default value: false. Enables some logs if set to true.
  });

  return (
    <MatomoProvider instance={instance}>
      <MainAppContainer />
    </MatomoProvider>
  );
};

Instance

You need to provide at least an urlBase and a siteId to create an instance.

Method	Default	Description
urlBase		(required) Link to your Matomo server domain.
trackerUrl	${urlBase}matomo.php	If your Matomo runs a different endpoint than the default matomo.php.
siteId		(required) Number matching your Matomo project.
userId	undefined	Defines the User ID for a tracking request. The User ID is any non-empty unique string identifying an user. (https://developer.matomo.org/api-reference/tracking-api#optional-user-info)
disabled	false	Disables all tracking operations if set to true.
log	false	Enables some logs if set to true.

Methods

The following methods are available with the useMatomo hook.

trackAppStart({ userInfo = {} } = {})

Tracks app start as action with prefixed 'App' category: App / start.

Param	Description
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

trackScreenView({ name, userInfo = {} })

Tracks screen view as action with prefixed 'Screen' category: Screen / ${name}

Param	Description
name	The title of the action being tracked. It is possible to use slashes / to set one or several categories for this action. For example, Help / Feedback will create the Action Feedback in the category Help.
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

trackAction({ name, userInfo = {} })

Tracks actions

Doc: https://developer.matomo.org/api-reference/tracking-api#recommended-parameters

Param	Description
name	The title of the action being tracked. It is possible to use slashes / to set one or several categories for this action. For example, Help / Feedback will create the Action Feedback in the category Help.
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

trackEvent({ category, action, name, value, campaign, userInfo = {} })

Tracks custom events

Doc: https://developer.matomo.org/api-reference/tracking-api#optional-event-trackinghttpsmatomoorgdocsevent-tracking-info

Param	Description
category	The event category. Must not be empty. (eg. Videos, Music, Games...)
action	The event action. Must not be empty. (eg. Play, Pause, Duration, Add Playlist, Downloaded, Clicked...)
name	The event name. (eg. a Movie name, or Song name, or File name...)
value	The event value. Must be a float or integer value (numeric), not a string.
campaign	The event related campaign.
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

trackSiteSearch({ keyword, category, count, userInfo = {} })

Tracks site search

Doc: https://developer.matomo.org/api-reference/tracking-api#optional-action-info-measure-page-view-outlink-download-site-search

Param	Description
keyword	The Site Search keyword. When specified, the request will not be tracked as a normal pageview but will instead be tracked as a Site Search request.
category	When keyword is specified, you can optionally specify a search category with this parameter.
count	When keyword is specified, it is also recommended setting the search_count to the number of search results displayed on the results page. When keywords are tracked with &search_count=0 they will appear in the "No Result Search Keyword" report.
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

trackLink({ link, userInfo = {} })

Tracks outgoing links to other sites

Doc: https://developer.matomo.org/api-reference/tracking-api#optional-action-info-measure-page-view-outlink-download-site-search

Param	Description
link	An external URL the user has opened. Used for tracking outlink clicks.
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

trackDownload({ download, userInfo = {} })

Tracks downloads

Doc: https://developer.matomo.org/api-reference/tracking-api#optional-action-info-measure-page-view-outlink-download-site-search

Param	Description
download	URL of a file the user has downloaded. Used for tracking downloads.
userInfo	Optional data used for tracking different user info, see https://developer.matomo.org/api-reference/tracking-api#optional-user-info.

Changelog

Have a look at the changelog to be up to date with the development process.

Star History

---

Version: 0.3.2