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 send begin to send events to your server.

ahoy.track(events: [myFirstEvent, mySecondEvent])
    .sink(receiveCompletion: { _ in }, receiveOutput: { _ in })
    .store(in: &cancellables)

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.