Ahoy iOS

Simple visit-attribution and analytics library for Apple Platforms for integration with your Rails Ahoy backend.

🌖 User visit tracking

📥 Visit attribution through UTM & referrer parameters

📆 Simple, straightforward, in-house event tracking

Installation

The Ahoy library can be easily installed using Swift Package Manager. See the Apple docs for instructions on adding a package to your project.

Usage

To get started you need to initialize an instance of an Ahoy client. The initializer takes a configuration object, which requires you to provide a baseUrl as well as an ApplicationEnvironment object.

import Ahoy

let ahoy: Ahoy = .init(
    configuration: .init(
    environment: .init(
        platform: UIDevice.current.systemName,
        appVersion: "1.0.2",
        osVersion: UIDevice.current.systemVersion
    ),
    baseUrl: URL(string: "https://your-server.com")!
  )
)

Configuration

The configuation object has intelligent defaults (listed below in parens), but allows you to a to provide overrides for a series of values:

• visitDuration (30 minutes)
• urlRequestHandler (URLSession.shared.dataTaskPublisher)
• Routing
  • ahoyPath ("ahoy")
  • visitsPath ("visits")
  • eventsPath ("events")

Beyond configuration, you can also provide your own AhoyTokenManager and RequestInterceptors at initialization (requestInterceptors can be modified later) for custom token management and pre-flight Ahoy request modifications, respectively.

Tracking a visit

After your client is initialized — ensure you maintain a reference — you'll need to track a visit, typically done at application launch. If desired, you can pass custom data such as utm parameters, referrer, etc.

ahoy.trackVisit()
    .sink(receiveCompletion: { _ in }, receiveOutput: { visit in print(visit) })
    .store(in: &cancellables)

Tracking events

After your client has successfully registered a visit, you can begin to send events to your server.

/// For bulk-tracking, use the `track(events:)` function
var pendingEvents: [Event] = []
pendingEvents.append(Event(name: "ride_details.update_driver_rating", properties: ["driver_id": 4]))
pendingEvents.append(Event(name: "ride_details.increase_tip", properties: ["driver_id": 4]))

ahoy.track(events: pendingEvents)
    .sink(
        receiveCompletion: { _ in }, // handle error as needed
        receiveValue: { pendingEvents.removeAll() }
    )
    .store(in: &cancellables)

/// If you prefer to fire events individually, you can use the fire-and-forget convenience method
ahoy.track("ride_details.update_driver_rating", properties: ["driver_id": 4])

/// If your event does not require properties, they can be omitted
ahoy.track("ride_details.update_driver_rating")

Other goodies

To access the current visit directly, simply use your Ahoy client's currentVisit property. (There is also a currentVisitPublisher you can listen to.) Additionally, you can use the headers property to add Ahoy-Visitor and Ahoy-Visit tokens to your own requests as needed.