Adding the Corvidae Pixel to your Apple Apps

Documentation for Corvidae iOS SDK v2.0.0

Corvidae iOS SDK Documentation (v2.0.0)

Overview

The Corvidae iOS SDK is designed to allow easy tracking and management of app analytics. Written in Swift, it provides a lazily loaded singleton class called Corvidae, which can be accessed using Corvidae.shared and will be initialised on the first call.

Corvidae Class

The Corvidae class is a singleton that is used for all configuration and tracking tasks.

Shared Instance:

You can access the shared instance directly using:

CODE

Corvidae.shared.[method]()

Or instantiate a shorthand reference for brevity:

CODE

let cvd = Corvidae.shared
cvd.[method]()

Methods

getConfig() -> (appId: String, hostname: String, property: String)

Returns the current configuration properties for the SDK.

Returns:

A tuple containing the current appId, hostname, and property.

CODE

let config = Corvidae.shared.getConfig()
print(config.appId)      // "yourAppId"
print(config.hostname)   // "yourHostname.com"
print(config.property)   // "yourProperty"

trackView(appId: String, hostname: String: property: String, screenLocation: String?, screenName: String?)

The trackView() method tracks a screen view in your app. It requires config to be set and optionally accepts screenLocation, and screenName. Use this method whenever the context of the app meaningfully changes, such as navigating between a Home view and a Product Details view.

Parameters:

appId (String) - appId is specific to your account. It will be given to you by your Customer Success Manager when you onboard and does not need to change. It is the same across all tracking for your account.
hostname (String) - hostname is a string representation of the subdomain on which your Corvidae pixel is hosted. For example corvidae.example.com
property (String) - property is a string identifier for the property currently being tracked. The value is equal to the “property” you have created in your Corvidae account. For example iOS-App-EU
screenLocation (String?) - This optional argument is intended to hold the “address” of the users current position in your app, be that a screen, view, or route, depending on your navigation architecture.
- If your app supports deep linking it is likely to be something like my-app://example.com/product/details/10456?language=en-US
- If your app supports Universal Links it will be more like https://example.com/product/details/10456?language=en-US
screenName (String?) - A simple string representation of the current screen, such as Home or Product Details: My Product. This can often be standardised using .navigationTitle or a similar mechanism.

Usage:

View Event:

CODE

Corvidae.shared.trackView(
  appId: "myappeu1"
  hostname: "corvidae.example.com"
  property: "iOS-App-EU"
) { success, error in DispatchQueue.main.async {} }

Logging:

The DispatchQueue can be used for troubleshooting if necessary

CODE

Corvidae.shared.trackView(
  appId: "myappeu1"
  hostname: "corvidae.example.com"
  property: "iOS-App-EU"
) { success, error in
  DispatchQueue.main.async {
    if success {
      print("Success")
    } else {
      print("Failure")
    }
  }
}

trackInboundView(appId: String, hostname: String: property: String, screenLocation: String?, screenName: String?, deepLink: String?, referrer: String?)

The trackInboundView() method is an extension of the trackView() method intended for use when a visit is inbound from an external source. It is crucially important that this method is used when an inbound link carries information about it’s referrer.

Parameters:

appId (String) - appId is specific to your account. It will be given to you by your Customer Success Manager when you onboard and does not need to change. It is the same across all tracking for your account.
hostname (String) - hostname is a string representation of the subdomain on which your Corvidae pixel is hosted. For example corvidae.example.com
property (String) - property is a string identifier for the property currently being tracked. The value is equal to the “property” you have created in your Corvidae account. For example iOS-App-EU
screenLocation (String?) - This optional argument is intended to hold the “address” of the users current position in your app, be that a screen, view, or route, depending on your navigation architecture.
- If your app supports deep linking it is likely to be something like my-app://example.com/product/details/10456?language=en-US
- If your app supports Universal Links it will be more like https://example.com/product/details/10456?language=en-US
screenName (String?) - A simple string representation of the current screen, such as Home or Product Details: My Product. This can often be standardised using .navigationTitle or a similar mechanism.
deepLink
referrer

Deep Links Usage:

If your app supports deep linking the deepLink URL should be caught in the appropriate scene, such as in openURLContexts using URLContexts.first?url

CODE

let appId = "myappeu1"
let hostname = "corvidae.example.com"
property = "iOS-App-EU"

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext) {
  if let deepLink = URLContexts.first?.url {
    Corvidae.shared.trackInboundView(
      appId: appId,
      hostname: hostname,
      property: property,
      screenLocation: "my-app://example.com/product/details/10456?language=en-US",
      screenName: "Product Details: My Product",
      deepLink: deepLink,
    ) { success, error in DispatchQueue.main.async{} }
  } else {
    Corvidae.shared.trackView(
      appId: appId,
      hostname: hostname,
      property: property,
      screenLocation: "my-app://example.com/product/details/10456?language=en-US",
      screenName: "Product Details: My Product",
    ) { success, error in DispatchQueue.main.async{} }
  }
}

Universal Links Usage:

If your app supports Universal Links the URL should be caught in the appropriate scene, such as in application(_, continue, restorationHandler) for App Delegates, and scene(_, continue) for Scene Delegates, using NSUserActivityTypeBrowsingWeb. We advise passing both webpageURL and referrerURL.

CODE

let appId = "myappeu1"
let hostname = "corvidae.example.com"
property = "iOS-App-EU"

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  if userActivity.actibityType == NSUserActivityTypeBrowsingWeb {
    if let universalLinkUrl = userActivity.webpageURL {
      Corvidae.shared.trackInboundView(
      appId: appId,
      hostname: hostname,
      property: property,
      screenLocation: universalLinkUrl,
      screenName: "Product Details: My Product",
      deepLink: universalLinkUrl,
      referrer: userActivity.referrerURL
      ) { success, error in DispatchQueue.main.async{} }
    }
  }
  if let deepLink = URLContexts.first?.url {
    
  } else {
    Corvidae.shared.trackView(
      appId: appId,
      hostname: hostname,
      property: property,
      screenLocation: universalLinkUrl,
      screenName: "Product Details: My Product",
    ) { success, error in DispatchQueue.main.async{} }
  }
}

Support

For more information or troubleshooting assistance, please contact your Customer Success Manager.