Track goals with the Matomo SDK for iOS

Goals record important user actions in your app, such as completing a sign-up, starting a trial, submitting a form, or reaching a key screen. Tracking goals helps measure conversions, so you can analyse whether users complete important actions.

This guide explains how to track goals in your iOS app using the Matomo SDK for iOS.

Before you start

1. Ensure tracking is already set up and working in your app. Follow the guide: setup tracking with the Matomo SDK for iOS.
2. Each goal must first be created in your Matomo instance under Goals > Manage Goals.
3. Take note of the numeric Goal ID required for configuring tracking in your mobile app. Learn how to create goals in Matomo.

Choose how the goal is tracked

Matomo can record goal conversions automatically when a tracked action matches the goal configuration in Matomo, or manually when your app sends a goal conversion using the SDK.

Do not use both methods for the same user action. For example, if Matomo is already configured to record a file download as a goal, do not also call trackGoal() from the same download button. This would record two goal conversions for a single download.

Track a goal manually

Use manual goal tracking when the conversion cannot be detected automatically from another tracked action.

1. Open the Swift file that contains the action you want to track a conversion for.
2. Ensure the file imports the Matomo SDK: import MatomoTracker.
3. Add the goal tracking call where the conversion happens. In the example code below, Matomo records a conversion for goal ID 1 when the user taps the button to start a free trial.
4. You can associate a monetary value with the conversion using the revenue parameter, for example:

    Button("Start free trial") { 
      MatomoTracker.shared.trackGoal(id: 1, revenue: 99.99) 

      // Perform the button action 
    }

Test the goal tracking setup

1. Build and run the app.
2. On a device or simulator, open your app and perform the action to trigger the goal conversion.

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

4. This example shows a goal conversion triggered automatically from a tracked download.

5. You can also view aggregated conversion data in the Goals report 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 goal conversions do 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.
• The goal must be defined in Matomo: Confirm that the goal has been created and that the goal ID in your code matches the ID in Matomo.
• Check for duplicate goal tracking: If the same action is already tracked automatically by a goal definition in Matomo, do not also send a manual trackGoal() request for that action.
• Confirm the tracking code executes: Add a breakpoint or debug message inside the button action to verify that the goal tracking call runs.
• Verify tracking is not disabled: If you use the isOptedOut property elsewhere in your application, confirm that tracking has not been disabled before the goal conversion 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 goals are recorded correctly, you can extend tracking to screen views, events, User IDs, and custom dimensions with the Matomo SDK for iOS.

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