Track events with the Matomo SDK for iOS

Events record specific user interactions within your app, such as button clicks, menu selections, form submissions, and downloads. Tracking events helps you measure feature adoption and understand how users interact with key functionality.

This guide explains how to track a button click (tap) event in your iOS app using the Matomo SDK for iOS.

Before you start

Ensure tracking is already set up and working in your app. Follow the guide: setup tracking with the Matomo SDK for iOS.

Track a button click event

Events consist of a category, action, and optional name. These values help you identify and group user interactions in Matomo reports. Learn about the anatomy of an event and best practices.

1. Open the Swift file that contains the button you want to track, for example, ContentView.swift.
2. Ensure the file imports the Matomo SDK: import MatomoTracker.
3. To track a button click, add an event tracking call inside the button action.
4. When the button is tapped, the SDK sends an event to Matomo.
5. The number and url parameters are optional and can be used to send additional information with the event.

Button("Download Guide") {

    MatomoTracker.shared.track(
        eventWithCategory: "Document",
        action: "Download",
        name: "User Guide",
        number: nil,
        url: nil
    )

    downloadGuide()
}

The example event includes:

• Category: Button
• Action: Click
• Name: Download

These values identify the interaction in Matomo reports. If the button performs navigation or another action, send the tracking event before executing the action. This ensures the event is queued before the view changes.

Test the event tracking setup

1. Build and run the app.
2. On a device or simulator, open your app and tap the button you are tracking. This will trigger the event.

3. In Matomo, open the Visitors > Real-time report or Visits Log.
   

4. Verify that the tracked event is recorded in the visit. Check that the event category, action, and name contain the expected values. These values determine how the event appears in Matomo reports.

5. You can also view aggregated event data in Behaviour > Events after the data has been processed.
   Note: The SDK queues tracking requests and sends them in batches, so tracking data may not appear immediately in Matomo.

Troubleshooting

If the event does not appear in Matomo, check the following:

• Allow time for queued requests: The SDK queues tracking requests and sends them in batches, so data may not appear immediately in Matomo.
• Verify the button action is not exiting early: If your button contains conditional logic, ensure the tracking call is reached before the function returns or navigation occurs.
• Confirm the tracking code executes: Add a breakpoint or debug message inside the button action to verify that the tracking call runs when the button is tapped.
• Verify tracking is not disabled: If you use the isOptedOut property elsewhere in your application, confirm that tracking has not been disabled before the event is sent.
• Inspect the Xcode console: Build and run the application in Xcode and check the console for SDK warnings, configuration errors, or network-related messages.

Next steps

After confirming that events are recorded correctly, you can extend tracking to screen views, goals, User IDs, and custom dimensions with the Matomo SDK for iOS.

For advanced SDK options, see the Matomo SDK for iOS page on GitHub.