Adding the Corvidae Pixel to your Apple Apps - iOS SDK v2.2.3

iOS SDK v2.2.3

Overview

Corvidae is a simple and lightweight analytics SDK designed to track events in iOS applications.

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.

Links

• GitHub

• Docarchive

Version changes

• Thread safety for concurrent requests using dispatchQueue

• Improved error handling

• Added debug logs for Xcode DEBUG_MODE

• [BREAKING] Added support for independent referrerURL parameter. Separated the trackView method into trackView and trackInboundView for ease of use.

• Improved documentation comments

• Compatible with iOS 8+

• Compatible with Swift projects only

Installation

To install CorvidaeLib via SPM:

Swift Package Manager (SPM)

1. Open your Xcode project.

2. Go to File > Add Package Dependencies....

3. In the dialog that appears, enter the URL of the CorvidaeLib repository:
   https://github.com/corvidae-ai/CorvidaeLib.git

4. Click "Copy Dependency"

Initialisation & Access

Corvidae uses a singleton pattern for initialization. The shared instance is lazily instantiated on its first use.

First import CorvidaeCore into your chosen .swift file

import CorvidaeCore

Then call the SDK directly using Corvidae.shared, or create a reference brevity:

let cvd = Corvidae.shared

Creating your Corvidae.plist

The Corvidae.shared instance requires config to be set in a Corvidae.plist at your application root.

First, create a new .plist (Property List) file in your Xcode project.

1. Right-click on your project in the Xcode file navigator.

2. Choose New File.

3. Right-click or ctrl+click your application root folder.

4. Select New File From Template

5. Select Property List under Resource.

6. Name the file `Corvidae.plist`.

7. Inside `Corvidae.plist`, add the required keys value pairs.

• **appId**: Your Corvidae unique identifier

• **hostname**: The hostname of your Corvidae subdomain

• **property**: The name of your iOS application's "property" within Corvidae

Your .plist should look something like the following. If you are unsure about these values please contact your Customer Success Manager.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>appId</key>
    <string>examplecomuk</string>
    <key>hostname</key>
    <string>corvidae.example.com</string>
    <key>property</key>
    <string>example.com</string>
</dict>
</plist>

Tracking Views

You can track a screen view (e.g., when a significant UI change occurs taking the user to new content) by calling the trackView method.

Corvidae.shared.trackView(
    screenLocation: "com.domain.myApp://product/123456",
    screenName: "Product: 123456"
)

Parameters:

• screenLocation: The location of the screen within the app. For most cases a full deep link or universal link location reference is preferred e.g. myapp://products/view/10894

• screenName: The name of the screen.

Tracking Inbound Views

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.

Additional parameters

• deepLink: The deep link URL if applicable. It is critically important that when inbound traffic is detected from an external source that a deep link is provided and the inbound URL includes query parameters identifying its source. For example `

• referrer: The URL of the referring page.

With deep links

When your application detects an incoming visit with a deep link call the trackInboundView method with the deepLink parameter set as a valid URL in String format. visit from an external URL please also pass the full URL including query string via the deepLink parameter. If your application detects the referring URL of incoming traffic, please pass it via the referrer parameter.

Corvidae.shared.trackView(
    screenLocation: "com.domain.myApp://product/123456",
    screenName: "Home",
    deepLink: "com.domain.myApp://product/123456?utm_source=google"
)

With referrers

When your application detects an incoming visit where a referrer URL is available (via connectionOptions, NSUserActivity, or a third part deferred deeplinking service) call the trackInboundView method with the referrer parameter set as a valid URL in String format.

Corvidae.shared.trackView(
    screenLocation: "com.domain.myApp://product/123456",
    screenName: "Home",
    referrer: "https://google.com"
)

With both deep link and referrer

If both of these conditions are true the method can be supplied with both values.

Corvidae.shared.trackView(
    screenLocation: "com.domain.myApp://product/123456",
    screenName: "Home",
    deepLink: "com.domain.myApp://product/123456?utm_source=google"
    referrer: "https://google.com"
)

Tracking Transactions

To track a transaction (e.g., when a user makes a purchase), use the trackTransaction method. You must provide the transactionType, transactionId, and transactionTotal. Other parameters such as shipping, tax, and currency are optional.

swiftCopycorvidae.trackTransaction(
    transactionType: "purchase",
    transactionId: "12345",
    transactionTotal: 99.99,
    screenLocation: "Checkout",
    screenName: "Checkout Screen",
    shipping: 5.00,
    tax: 2.50,
    currency: "USD"
)
 

Parameters:

• transactionType: Type of transaction (e.g., "purchase").

• transactionId: Unique identifier for the transaction.

• transactionTotal: The total value of the transaction.

• screenLocation: The location where the transaction occurred.

• screenName: The screen where the transaction was initiated.

• shipping: The shipping cost (optional).

• tax: The tax amount (optional).

• currency: The currency of the transaction (optional).

Documentation

Documentation can be found

1. Here

2. As a Docarchive on the latest GitHub release

3. On the GitHub repository

4. After adding CorvidaeLib to your project

   1. As a readme in the package

      

   2. In your Xcode Workspace Documentation

      

   3. And in Xcode Quick Help

      

Features

Session Management

The SDK manages sessions automatically. A session ID is created when the app starts, and it is reset when 30 minutes have passed since the last event was tracked or when a deep link is provided.

• Session ID: Generated on the first app launch and automatically persists throughout the session.

• Session Reset: The session is reset automatically after 30 minutes of inactivity or when a deep link is provided.

Error Types

• CorvidaeError.invalidURL: If a supplied URL is invalid.

• CorvidaeError.configFileNotFound: If the Corvidae.plist configuration file is missing.

• CorvidaeError.configFileReadingFailed: If there was an error reading the configuration file.

• CorvidaeError.missingMandatoryParameters: If required parameters are missing in a transaction request.

Thread Safety

The SDK is designed to be thread-safe, meaning that you don’t need to worry about concurrency issues when calling its methods. The internal state is updated safely in a multithreaded environment.

iOS Compatibility

The SDK is compatible with iOS 8.0 and higher. If you need to support earlier versions, please get in touch.

FAQ

How to enable debug mode in Xcode?

• Open the project in Xcode.

• Go to Product -> Scheme -> Edit Scheme.

• In the Run section, select the Arguments tab.

• Under Environment Variables, add a new variable:

  • Key: DEBUG_MODE

  • Value: YES