search

mccsoft / react-native-matomo

Matomo wrapper for React-Native. Supports Android and iOS. Fixed issues for native platforms build that are present in the official package.
MIT License
7 stars 2 forks source link

readme

@mccsoft/react-native-matomo

Matomo wrapper for React-Native. Supports Android and iOS. Fixed issues for native platforms build that are present in the official package.

Installation

After that you can install it as usual.

Via NPM

npm install @mccsoft/react-native-matomo

Via Yarn

yarn add @mccsoft/react-native-matomo

Directly in package.json pointed to GitHub

"@mccsoft/react-native-matomo": "https://github.com/mccsoft/react-native-matomo",

:iphone:iOS (Extra steps)

cd ios/
# Install pod dependencies
pod install

Since the official matomo-sdk-ios library is written is Swift, you need to have Swift enabled in your iOS project. If you already have any .swift files, you are good to go. Otherwise create a new empty Swift source file in Xcode, and allow it to create the neccessary bridging header when prompted.

Quick usage

import Matomo from "@mccsoft/react-native-matomo";

Matomo.initialize("https://example.com/piwik.php", 1)
  .catch(error => console.warn("Failed to initialize matomo", error))
  .then(() => Matomo.setUserId("UniqueUserId"))
  .then(() => Matomo.setCustomDimension(1, "1.0.0"))
  .then(async () => {
      await Matomo.trackEvent("Application", "Startup");

      await Matomo.trackView("/start", 'Start screen title');
    }
  )

Methods

Initialize

Before using any function below, the tracker must be initialized.

Matomo.initialize('https://your-matomo-domain.tld/piwik.php', 1);

On Android events queue is by default cached on disk, so events are not lost when user close the app. On iOS by default evetns queue is saved in memory, however you con opt in to use cached queue on iOS as well by initilaizing tracker with third option:

Matomo.initialize('https://your-matomo-domain.tld/piwik.php', 1, true);

Set User ID

Providing the tracker with a user ID lets you connect data collected from multiple devices and multiple browsers for the same user. A user ID is typically a non empty string such as username, email address or UUID that uniquely identifies the user. The User ID must be the same for a given user across all her devices and browsers. . If user ID is used, it must be persisted locally by the app and set directly on the tracker each time the app is started.

If no user ID is used, the SDK will generate, manage and persist a random id for you.

Matomo.setUserId('123e4567-e89b-12d3-a456-426655440000');

Custom Dimensions

The Matomo SDK currently supports Custom Dimensions for the Visit Scope. Using Custom Dimensions you can add properties to the whole visit, such as "Did the user finish the tutorial?", "Is the user a paying user?" or "Which version of the Application is being used?" and such. Before sending custom dimensions please make sure Custom Dimensions are properly installed and documented. You will need the ID of your configured Dimension.

After that you can set a new Dimension,

Matomo.setCustomDimension(1, 'abc');

or remove an already set dimension.

Matomo.setCustomDimension(1, null);

Dimensions in the Visit Scope will be sent along every Page View or Event. Custom Dimensions are not persisted by the SDK and have to be re-configured upon application startup.

Track screen views

To send a screen view set the screen path and titles on the tracker.

Matomo.trackView('/your_activity', 'Title');

Track events

To collect data about user's interaction with interactive components of your app, like button presses or the use of a particular item in a game use trackEvent.

Matomo.trackEvent('category', 'action', 'label', 1000);

Track goals

If you want to trigger a conversion manually or track some user interaction simply call the method trackGoal. Read more about what is a Goal in Matomo.

Matomo.trackGoal(1, revenue);

Track App Downloads

If you want to track the app downloads, there is also a function to do that (only supported on Android).

Matomo.trackAppDownload();

Setting App Opt Out

The MatomoTracker SDK supports opting out of tracking. Note that this flag must be set each time the app starts up and will default to false. To set the app-level opt out, use:

Matomo.setAppOptOut(true);

Is initialized

You can easily find out is Matomo tracker initialized or not. Call this method and get Boolean value, use:

await Matomo.isInitialized();

Dispatch events manually

Sometimes there is a need to dispach events manully:

Matomo.dispatch();

Set dispatch interval in seconds

There is an option to change dispatch interval using seconds:

Matomo.setDispatchInterval(30)

Get dispatch internatl

You can easily find out current dispatch interanl in seconds. Call this method and get number value, use:

await Matomo.getDispatchInterval();

Mocking

Add this to mock specific function as you wish

jest.mock('@mccsoft/react-native-matomo', () => ({
  initialize: () => Promise.resolve(),
  trackEvent: () => Promise.resolve(),
  trackView: () => Promise.resolve(),
  ...
}));

Or add this line in your jest setupFiles configuration to define default mocks.

  "setupFiles": [
    ...
    "./node_modules/@mccsoft/react-native-matomo/jestSetup.js"
  ],

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library