Skip to content

Analytics and attribution library for Apple platforms built on top of Ahoy for Ruby on Rails.

License

Notifications You must be signed in to change notification settings

namolnad/ahoy-ios

Repository files navigation

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

Actions Status

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.

About

Analytics and attribution library for Apple platforms built on top of Ahoy for Ruby on Rails.

Resources

License

Stars

Watchers

Forks

Languages