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-react-sdk

# or with yarn:

yarn add matomo-react-sdk

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-react-sdk';
import {
  SafeAreaView,
    Button,
} from 'react-native';
const AppTracker = () => {
    const { trackEvent,setUserId,setCustomDimension,trackPageView,setActionName} = useMatomo();
    useEffect(() => {
        setCustomDimension(1, 13);//活动ID 常量
        setCustomDimension(2,1);//事件ID,常量
        setCustomDimension(3,"浏览页面");//事件名称,常量
        setCustomDimension(22,'1');//事件类型 常量
        setActionName("home_page");//页面路由
        trackPageView();//浏览页面监听
    }, []);
    return (
        <>
            <SafeAreaView>
                <Button
                    title={'点击'}
                    accessibilityLabel="accessibility title"
                    color={'red'}
                    disabled={false}
                    testID={'buttonTag'}
                    onPress={() => {
                        setCustomDimension(1, 13);//活动ID 常量
                        setCustomDimension(2,1);//事件ID,常量
                        setCustomDimension(3,"浏览页面");//事件名称,常量
                        setCustomDimension(22,'1');//事件类型 常量
                        setUserId("11");//用户ID
                        setCustomDimension(4,"11");//归属省份
                        setCustomDimension(5,"");//归属城市
                        setCustomDimension(10,"1");//页面名称
                        trackEvent({ category:"1", action:"1", name:"fadfa", value:"myvalue" })//事件监听，

                    }}
                />
            </SafeAreaView>
        </>
    );
};
const MainAppContainer : () => React$Node = () => {
    const instance = new MatomoTracker({
        urlBase: 'matomo服务器地址', // required
        siteId: 1, // required, number matching your Matomo project
        disabled: false, // optional, default value: false. Disables all tracking operations if set to true.
        log: true  // optional, default value: false. Enables some logs if set to true.
    });
    return (
        <MatomoProvider instance={instance}>
            <AppTracker />
        </MatomoProvider>
    );
};
export default MainAppContainer;

Usage

If other subcomponents send Matomo, refer to the example

app.js

import Son from './son' // Introduced in app.js

<Son></Son>  //The child components are embedded in the page

son.js

//son.js 子类 import React, { useEffect } from 'react'; import MatomoTracker, { MatomoProvider, useMatomo } from 'matomo-react-sdk'; import { SafeAreaView, Button, } from 'react-native'; function Son(props) { const { trackEvent,setUserId,setCustomDimension,trackPageView,setActionName} = useMatomo(); return ( //Consumer容器,可以拿到上文传递下来的name属性,并可以展示对应的值 <Button title={'我是子节点点击'} accessibilityLabel="accessibility title" color={'red'} disabled={false} testID={'buttonTag'} onPress={() => { setCustomDimension(1, 13);//活动ID 常量 setCustomDimension(2,1);//事件ID,常量 setCustomDimension(3,"点击事件");//事件名称,常量 setCustomDimension(22,'1');//事件类型 常量 setUserId("11");//用户ID setCustomDimension(4,"11");//归属省份 setCustomDimension(5,"");//归属城市 setCustomDimension(10,"1");//页面名称 trackEvent({ category:"1", action:"1", name:"1111111111", value:"111111111" })//事件监听，

              }}  />
);

} export default Son;

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.

setUserId(uid)

Sets the user id for the tracker. Passing null as the user id will clear any previously set user id

Param | Description ------ | ----------- uid | 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.

setUrl(url)

The routing address of the current page

Param | Description ------ | ----------- url | 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.

setActionName(action_name)

When you do page listening, pass in your page routing name

Param | Description ------ | ----------- action_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.

setCustomDimension(id: number, value: string | null)

Sets a custom dimension value for the tracker which will be sent as part of all subsequent tracking calls. Passing null as the value will clear any previously set value for the given dimension id.

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

Param | Description ------ | ----------- id | number value | string | null

trackEvent({ category, action, name, value })

When event listening is set, Matomo is immediately sent to the server

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.

trackPageView()

Browse the page monitor When all the conditions are set, Send the service to the Matomo server

logInfo

Version: 1.0.2