promotedai/ios-metrics-sdk

MetricsLoggerService

Create and configure the service when your app starts, then retrieve the MetricsLogger instance from the service after it has been configured. Alternatively, create ImpressionTracker instances using the service.

Example usage (dependency injection)

var config = ClientConfig()
config.metricsLoggingURL = "https://yourdomain.ext.promoted.ai"
config.metricsLoggingAPIKey = "..."
let service = try MetricsLoggerService(initialConfig: config)
try service.startLoggingServices()
// Create and use objects from the service
let logger = service.metricsLogger
let impressionTracker = service.impressionTracker(sourceType: .delivery)
let scrollTracker = service.scrollTracker(collectionView: ...)

Example usage (singleton)

var config = ClientConfig()
config.metricsLoggingURL = "https://yourdomain.ext.promoted.ai"
config.metricsLoggingAPIKey = "..."
// Call `startServices` first before accessing the instance.
try MetricsLoggerService.startServices(initialConfig: config)
let service = MetricsLoggerService.shared
// Create and use objects from the service
let logger = service.metricsLogger
let impressionTracker = service.impressionTracker(sourceType: .delivery)
let scrollTracker = service.scrollTracker(collectionView: ...)

Promoted vs proxy servers

When using ClientConfig, if you connect directly to a Promoted server in metricsLoggingURL, you need to provide an API key for metricsLoggingAPIKey. However, if you use a proxy server, you do not need to specify a value for metricsLoggingAPIKey, since your proxy would presumably forward the real API key to the Promoted Metrics service. Furthermore, you can use metricsLoggingRequestHeaders to customize your request headers.

// Using a proxy server
var config = ClientConfig()
config.metricsLoggingURL = "https://proxy.yourdomain.com"
config.metricsLoggingRequestHeaders = [
  "x-custom-header-1": "value1",
  "x-custom-header-2": "value2"
]
let service = try MetricsLoggerService(initialConfig: config)

MetricsLogger

Promoted event logging interface. Use instances of MetricsLogger to log events to Promoted’s servers. Events are accumulated and sent in batches on a timer.

To start a logging session, first call startSession(userID:) or startSessionSignedOut() to set up the user ID and log user ID for the session. You can call either startSession method more than once to begin a new session with the given user ID.

Use log(message:) to enqueue an event for logging. When the batching timer fires, all events are delivered to the server via the NetworkConnection.

Example

let logger = MetricsLogger(...)
// Sets userID and logUserID for subsequent log() calls.
logger.startSession(userID: myUserID)
// Log clicks, purchases, or other relevant events
logger.logAction(type: .navigate, content: clickedContent)
logger.logAction(type: .purchase, content: purchasedContent)
// Resets userID and logUserID.
logger.startSession(userID: secondUserID)

ImpressionTracker

Provides basic impression tracking across scrolling collection views, such as UICollectionView or UITableView. Works best with views that can provide fine-grained updates of visible cells, but can also be adapted to work with views that don't (see ScrollTracker).

Example usage with UICollectionView

Clients should create an instance of ImpressionTracker and reference it in their view controller, then provide updates to the impression logger as the collection view scrolls or updates.

class MyViewController: UIViewController {
  var collectionView: UICollectionView
  var impressionTracker: ImpressionTracker

  init(...) {
    impressionTracker = metricsLoggerService.impressionTracker()
  }

  private func content(atIndexPath path: IndexPath) -> Content? {
    let item = path.item
    if item >= self.items.count { return nil }
    let myItemProperties = self.items[item]
    return Item(properties: myItemProperties)
  }

  func viewWillDisappear(_ animated: Bool) {
    impressionTracker.collectionViewDidHideAllContent()
  }

  func collectionView(
    _ collectionView: UICollectionView,
    willDisplay cell: UICollectionViewCell,
    forItemAt indexPath: IndexPath
  ) {
    if let content = content(atIndexPath: indexPath) {
      impressionTracker.collectionViewWillDisplay(content: content)
    }
  }
   
  func collectionView(
    _ collectionView: UICollectionView,
    didEndDisplaying cell: UICollectionViewCell,
    forItemAt indexPath: IndexPath
  ) {
    if let content = content(atIndexPath: indexPath) {
      impressionTracker.collectionViewDidHide(content: content)
    }
  }

  func reloadCollectionView() {
    self.collectionView.reloadData()
    let visibleContent = collectionView.indexPathsForVisibleItems.map {
      path in content(atIndexPath: path)
    }
    impressionTracker.collectionViewDidChangeVisibleContent(visibleContent)
  }
}

Package Metadata

Repository: promotedai/ios-metrics-sdk

Default branch: main

README: README.md