https://github.com/brightdigit/aviaryinsights
Easy to use Swift Package for recording pageviews and custom events for Plausible.
https://github.com/brightdigit/aviaryinsights
analytics plausible plausible-analytics swift swift-package-manager
Last synced: 4 months ago
JSON representation
Easy to use Swift Package for recording pageviews and custom events for Plausible.
- Host: GitHub
- URL: https://github.com/brightdigit/aviaryinsights
- Owner: brightdigit
- License: mit
- Created: 2024-05-05T16:28:15.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-07T20:45:35.000Z (6 months ago)
- Last Synced: 2025-05-23T03:48:54.285Z (5 months ago)
- Topics: analytics, plausible, plausible-analytics, swift, swift-package-manager
- Language: Swift
- Homepage:
- Size: 35.2 KB
- Stars: 15
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AviaryInsights
Easy to use Swift Package for recording pageviews and custom events for Plausible.
[](https://swift.org)
[](http://twitter.com/brightdigit)
[](https://swiftpackageindex.com/brightdigit/AviaryInsights)
[](https://swiftpackageindex.com/brightdigit/AviaryInsights)
[](https://codecov.io/gh/brightdigit/AviaryInsights)
[](https://www.codefactor.io/repository/github/brightdigit/AviaryInsights)
[](https://codebeat.co/projects/github-com-brightdigit-mistkit-main)
[](https://codeclimate.com/github/brightdigit/AviaryInsights)
[](https://codeclimate.com/github/brightdigit/AviaryInsights)
[](https://codeclimate.com/github/brightdigit/AviaryInsights)
[](https://houndci.com)
Table of Contents
=================
* [Features](#features)
* [Requirements](#requirements)
* [Installation](#installation)
* [Usage](#usage)
* [Sending an Event](#sending-an-event)
* [Asynchronous Throwing Method](#asynchronous-throwing-method)
* [Synchronous Method](#synchronous-method)
* [Contributing](#contributing)
* [License](#license)
## Features
Plausible provides simple and meaningful insights into your website's traffic without invading the privacy of your visitors. However, integrating Plausible into a Swift application can be complex and time-consuming. AviaryInsights simplifies this process, allowing you to focus on building your application while still gaining the valuable insights that Plausible provides.
- **Event tracking** Define and track custom events in your application.
- **Revenue tracking** Track revenue data associated with events.
- **Plausible API integration** Send your events to the Plausible API for further analysis.
## Requirements
**Apple Platforms**
- Xcode 15 or later
- Swift 5.9 or later
- iOS 13 / watchOS 6 / tvOS 13 / visionOS 1 / macCatalyst 13 / macOS 10.15 or later deployment targets
**Linux**
- Ubuntu 20.04 or later
- Swift 5.9 or later
## Installation
To add the AviaryInsights package to your Xcode project, select File > Swift Packages > Add Package Dependency and enter the repository URL.
Using Swift Package Manager add the repository url:
```
https://github.com/brightdigit/AviaryInsights.git
```
## Usage
```swift
import AviaryInsights
// Initialize the client with your bundle identifier as the domain
let plausible = Plausible(domain: "com.example.yourApp")
// Define an event
let event = Event(url: "app://localhost/login")
// Send the event
plausible.send(event: event)
```
### `Plausible` Client
`Plausible` is a client for interacting with the Plausible API. It is initialized with a domain, which is typically your app's bundle identifier. The `Plausible` client is used to send events to the Plausible API for tracking and analysis.
To construct a `Plausible` instance, you need to provide a domain. The domain is a string that identifies your application, typically the bundle identifier of your app.
```swift
let plausible = Plausible(domain: "com.example.yourApp")
```
By default `Plausible` uses a `URLSessionTransport`, however you can use alternatives such as AsyncClient.
### Sending an `Event`
`Event` represents an event in your system. An event has a name, and optionally, a domain, URL, referrer, custom properties (`props`), and revenue information. You can create an `Event` instance and send it using the `Plausible` client.
To construct an `Event`, you need to provide at least a name. The name is a string that identifies the event you want to track. Optionally, you can also provide:
- **`name`** string that represents the name of the event. _Default_ is **pageview**.
- **`url`** string that represents the URL where the event occurred. For an app you may wish to use a app url such as `app://localhost/login`.
- `domain` _optional_ string that identifies the domain in which the event occurred. Overrides whatever was set in the `Plausible` instance.
- `referrer` _optional_ string that represents the URL of the referrer
- `props` _optional_ dictionary of custom properties associated with the event.
- `revenue` _optional_ `Revenue` instance that represents the revenue data associated with the event
```swift
let event = Event
name: "eventName",
domain: "domain",
url: "url",
referrer: "referrer",
props: ["key": "value"],
revenue: Revenue(
currencyCode: "USD",
amount: 100
)
)
```
AviaryInsights provides two ways to send events to the Plausible API:
#### Asynchronous Throwing Method
This method sends an event to the Plausible API and throws an error if the operation fails. This is useful when you want to handle errors in your own way. Here's an example:
```swift
do {
try await plausible.postEvent(event)
} catch {
print("Failed to post event: \(error)")
}
```
#### Synchronous Method
This method sends an event to the Plausible API in the background and ignores any errors that occur. This is useful when you don't need to handle errors and want to fire-and-forget the event. Here's an example:
```swift
plausible.postEvent(event)
```
In both cases, `event` is an instance of `Event` that you want to send to the Plausible API.
## License
AviaryInsights is available under the MIT license. See the [LICENSE](LICENSE) file for more info.