{"id":752,"url":"https://github.com/matomo-org/matomo-sdk-ios","last_synced_at":"2025-07-30T19:32:07.445Z","repository":{"id":3472434,"uuid":"4527336","full_name":"matomo-org/matomo-sdk-ios","owner":"matomo-org","description":"Matomo iOS, tvOS and macOS SDK: a Matomo tracker written in Swift","archived":false,"fork":false,"pushed_at":"2024-04-01T18:31:51.000Z","size":4721,"stargazers_count":381,"open_issues_count":20,"forks_count":161,"subscribers_count":35,"default_branch":"develop","last_synced_at":"2024-04-14T00:59:43.795Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matomo-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2012-06-02T06:30:44.000Z","updated_at":"2024-04-16T07:27:26.099Z","dependencies_parsed_at":"2023-02-16T13:15:50.166Z","dependency_job_id":"6ce14f8f-e632-454b-b677-9fe535bcd2e1","html_url":"https://github.com/matomo-org/matomo-sdk-ios","commit_stats":{"total_commits":364,"total_committers":45,"mean_commits":8.088888888888889,"dds":0.5412087912087913,"last_synced_commit":"cc5d5b3256a21f99b55029116021d98c753c8f26"},"previous_names":["piwik/piwik-sdk-ios"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-sdk-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-sdk-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-sdk-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matomo-org%2Fmatomo-sdk-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matomo-org","download_url":"https://codeload.github.com/matomo-org/matomo-sdk-ios/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227991722,"owners_count":17852522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-01-05T20:15:30.546Z","updated_at":"2024-12-04T19:31:54.371Z","avatar_url":"https://github.com/matomo-org.png","language":"Swift","funding_links":[],"categories":["Analytics"],"sub_categories":["Getting Started"],"readme":"# MatomoTracker (former PiwikTracker) iOS SDK\n\nThe MatomoTracker is an iOS, tvOS and macOS SDK for sending app analytics to a Matomo server. MatomoTracker can be used from Swift and [Objective-C](https://github.com/matomo-org/matomo-sdk-ios/wiki/FAQ#how-to-use-the-matomotracker-from-objective-c).\n\n**Fancy help improve this SDK? Check [this list](https://github.com/matomo-org/matomo-sdk-ios/issues?utf8=✓\u0026q=is%3Aopen+is%3Aissue) to see what is left and can be improved.**\n\n## Installation\n\nThe MatomoTracker can be installed via CocoaPods, Carthage and the Swift Package Manager. In every file you want to use the MatomoTracker, don't forget to import the framework with `import MatomoTracker`.\n\n\u003cdetails\u003e\u003csummary\u003eCocoaPods\u003c/summary\u003e\n\nUse the following in your Podfile.\n```\npod 'MatomoTracker', '~\u003e 7.7'\n```\nThen run `pod install`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eCarthage\u003c/summary\u003e\n\n[Carthage](https://github.com/Carthage/Carthage) is a non intrusive way to install MatomoTracker to your project. It makes no changes to your Xcode project and workspace. Add the following to your Cartfile:\n\n```\ngithub \"matomo-org/matomo-sdk-ios\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eSwift Package Manager\u003c/summary\u003e\n\nYou can use the Swift Package Manager as integration method. If you want to use the Swift Package Manager as integration method, either use Xcode to add the package dependency or add the following dependency to your Package.swift:\n\n`.package(url: \"https://github.com/matomo-org/matomo-sdk-ios.git\", from: \"v7.7.0\"),`\n\nand in your dependencies:\n\n`.product(name: \"MatomoTracker\", package: \"matomo-sdk-ios\")`\n\n\u003c/details\u003e\n\n## Usage\n### Matomo Instance\n\nThe Matomo iOS SDK doesn't provide a instance of the PiwikTracker. In order to be able to track data you have to create an instance first.\n\n```Swift\nlet matomoTracker = MatomoTracker(siteId: \"23\", baseURL: URL(string: \"https://demo2.matomo.org/piwik.php\")!)\n```\n\n\nThe `siteId` is the ID that you can get if you [add a website](https://matomo.org/faq/how-to/create-and-manage-websites/) within the Matomo web interface. The `baseURL` it the URL to your Matomo web instance and has to include the \"piwik.php\" or \"matomo.php\" string.\n\nYou can either pass around this instance, or add an extension to the `MatomoTracker` class and add a shared instance property.\n\n```Swift\nextension MatomoTracker {\n    static let shared: MatomoTracker = MatomoTracker(siteId: \"1\", baseURL: URL(string: \"https://example.com/piwik.php\")!)\n}\n```\n\nThe `siteId` is the ID that you can get if you [add a website](https://matomo.org/faq/how-to/create-and-manage-websites/) within the Matomo web interface. The `baseURL` is the URL to your Matomo web instance and has to include the \"piwik.php\" or \"matomo.php\" string.\n\nYou can use multiple instances within one application.\n\n#### Opting Out\n\nThe MatomoTracker SDK supports opting out of tracking. Please use the `isOptedOut` property of the MatomoTracker to define if the user opted out of tracking.\n\n```Swift\nmatomoTracker.isOptedOut = true\n```\n\n### Tracking Page Views\n\nThe MatomoTracker can track hierarchical screen names, e.g. screen/settings/register. Use this to create a hierarchical and logical grouping of screen views in the Matomo web interface.\n\n```Swift\nmatomoTracker.track(view: [\"path\",\"to\",\"your\",\"page\"])\n```\n\nYou can also set the url of the page.\n```Swift\nlet url = URL(string: \"https://matomo.org/get-involved/\")\nmatomoTracker.track(view: [\"community\",\"get-involved\"], url: url)\n```\n\n### Tracking Events\n\nEvents can be used to track user interactions such as taps on a button. An event consists of four parts:\n\n- Category\n- Action\n- Name (optional, recommended)\n- Value (optional)\n\n```Swift\nmatomoTracker.track(eventWithCategory: \"player\", action: \"slide\", name: \"volume\", value: 35.1)\n```\n\nThis will log that the user slid the volume slider on the player to 35.1%.\n\n### Tracking search\n\nThe `MatomoTracker` can track how users use your app internal search. You can track what keywords were searched for, what categories they use, the number of results for a certain search and what searches resulted in no results.\n\n```Swift\nmatomoTracker.trackSearch(query: \"Best mobile tracking\", category: \"Technology\", resultCount: 15)\n```\n\n### Custom Dimension\n\nThe 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 configured](https://matomo.org/docs/custom-dimensions/). You will need the `ID` of your configured Dimension.\n\nAfter that you can set a new Dimension,\n\n```Swift\nmatomoTracker.set(value: \"1.0.0-beta2\", forIndex: 1)\n```\n\nor remove an already set dimension.\n\n```Swift\nmatomoTracker.remove(dimensionAtIndex: 1)\n```\n\nDimensions 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.\n\n### Custom User ID\n\nTo add a [custom User ID](https://matomo.org/docs/user-id/), simply set the value you'd like to use on the `userId` field of the tracker:\n\n```Swift\nmatomoTracker.userId = \"coolUsername123\"\n```\n\nAll future events being tracked by the SDK will be associated with this userID, as opposed to the default UUID created for each Visitor.\n\n### Custom Visitor ID persisted on app starts\n\nMatomoTracker will generate an `_id` upon first usage and will use this value to recognize the current visitor. This `_id` is persisted over app starts.\n\nIf you want to set your own visitor id, you can set your own visitor id with the `forcedVisitorId` field. Make sure you use a 16 character long hexadecimal string. The `forcedVisitorId` is persisted over app starts.\n\n```Swift\nmatomoTracker.forcedVisitorId = \"0123456789abcdef\"\n```\n\nBecause the SDK persists this visitor id on app start, then we recommend to ask users for consent before tracking your app users.\n\n### Campaign Tracking\n\nThe Matomo iOS SDK supports [campaign tracking](https://matomo.org/docs/tracking-campaigns/).\n\n```Swift\nmatomoTracker.trackCampaign(name: \"campaign_name\", keyword: \"campaign_keyword\")\n```\n\n### Content Tracking\n\nThe Matomo iOS SDK supports [content tracking](https://matomo.org/docs/content-tracking/).\n\n```Swift\nmatomoTracker.trackContentImpression(name: \"preview-liveaboard\", piece: \"Malaysia\", target: \"https://dummy.matomo.org/liveaboard/malaysia\")\nmatomoTracker.trackContentInteraction(name: \"preview-liveaboard\", interaction: \"tap\", piece: \"Malaysia\", target: \"https://dummy.matomo.org/liveaboard/malaysia\")\n```\n\n### Goal Tracking\n\nThe Matomo iOS SDK supports [goal tracking](https://matomo.org/docs/tracking-goals-web-analytics/).\n\n```Swift\nmatomoTracker.trackGoal(id: 1, revenue: 99.99)\n```\n\n### Order Tracking\n\nThe Matomo iOS SDK supports [order tracking](https://matomo.org/faq/reports/advanced-manually-tracking-ecommerce-actions-in-matomo/#tracking-orders-to-matomo-required).\n\n```Swift\nlet items = [\n  OrderItem(sku: \"product_sku_1\", name: \"iPhone Xs\", category: \"phone\", price: 999.99, quantity: 1),\n  OrderItem(sku: \"product_sku_2\", name: \"iPhone Xs Max\", category: \"phone\", price: 1199.99, quantity: 1)\n]\n\nmatomoTracker.trackOrder(id: \"order_id_1234\", items: items, revenue: 2199.98, subTotal: 2000, tax: 190.98, shippingCost: 9)\n```\n\n## Advanced Usage\n### Manual dispatching\n\nThe MatomoTracker will dispatch events every 30 seconds automatically. If you want to dispatch events manually, you can use the `dispatch()` function.\n\n### Session Management\n\nThe MatomoTracker starts a new session whenever the application starts. If you want to start a new session manually, you can use the `startNewSession()` function. You can, for example, start a new session whenever the user enters the application.\n\n```Swift\nfunc applicationWillEnterForeground(_ application: UIApplication) {\n  matomoTracker.startNewSession()\n}\n```\n\n### Logging\n\nThe MatomoTracker per default logs `warning` and `error` messages to the console. You can change the `LogLevel`.\n\n```Swift\nmatomoTracker.logger = DefaultLogger(minLevel: .verbose)\nmatomoTracker.logger = DefaultLogger(minLevel: .debug)\nmatomoTracker.logger = DefaultLogger(minLevel: .info)\nmatomoTracker.logger = DefaultLogger(minLevel: .warning)\nmatomoTracker.logger = DefaultLogger(minLevel: .error)\n```\n\nYou can also write your own `Logger` and send the logs wherever you want. Just write a new class/struct and let it conform to the `Logger` protocol.\n\n### Custom User Agent\nThe `MatomoTracker` will create a default user agent derived from the WKWebView user agent.\nYou can instantiate the `MatomoTracker` using your own user agent.\n\n```Swift\nlet matomoTracker = MatomoTracker(siteId: \"5\", baseURL: URL(string: \"http://your.server.org/path-to-matomo/piwik.php\")!, userAgent: \"Your custom user agent\")\n```\n\n### Sending custom events\n\nInstead of using the convenience functions for events and screen views for example you can create your event manually and even send custom tracking parameters. This feature isn't available from Objective-C.\n\n```Swift\nfunc sendCustomEvent() {\n  guard let matomoTracker = MatomoTracker.shared else { return }\n  let downloadURL = URL(string: \"https://builds.matomo.org/piwik.zip\")!\n  let event = Event(tracker: matomoTracker, action: [\"menu\", \"custom tracking parameters\"], url: downloadURL, customTrackingParameters: [\"download\": downloadURL.absoluteString])\n  matomoTracker.track(event)\n}\n```\n\nAll custom events will be URL-encoded and dispatched along with the default Event parameters. Please read the [Tracking API Documentation](https://developer.matomo.org/api-reference/tracking-api) for more information on which parameters can be used.\n\nAlso: You cannot override Custom Parameter keys that are already defined by the Event itself. If you set those keys in the `customTrackingParameters` they will be discarded.\n\n### Automatic url generation\n\nYou can define the url property on every `Event`. If none is defined, the SDK will try to generate a url based on the `contentBase` of the `MatomoTracker`. If the `contentBase` is nil, no url will be generated. If the `contentBase` is set, it will append the actions of the event to it and use it as the url. Per default the `contentBase` is generated using the application bundle identifier. For example `http://org.matomo.skd`. This will not result in resolvable urls, but enables the backend to analyse and structure them.\n\n### Event dispatching\n\nWhenever you track an event or a page view it is stored in memory first. In every dispatch run a batch of those events are sent to the server. If the device is offline or the server doesn't respond these events will be kept and resent at a later time. Events currently aren't stored on disk and will be lost if the application is terminated. [#137](https://github.com/matomo-org/matomo-sdk-ios/issues/137). You can use an experimental implementation of a Queue that stores all Events in the UserDefaults.\n\n```swift\nlet queue = UserDefaultsQueue(userDefaults: UserDefaults.standard)\nlet dispatcher = URLSessionDispatcher(baseURL: URL(string: \"https://example.com/matomo.php\")!)\nlet matomoTracker = MatomoTracker(siteId: \"1\", queue: queue, dispatcher: dispatcher)\n```\n\n## Contributing\nPlease read [CONTRIBUTING.md](https://github.com/matomo-org/matomo-sdk-ios/blob/develop/CONTRIBUTING.md) for details.\n\n## License\n\nMatomoTracker is available under the [MIT license](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatomo-org%2Fmatomo-sdk-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatomo-org%2Fmatomo-sdk-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatomo-org%2Fmatomo-sdk-ios/lists"}