iOS tracking SDK for mobile apps

The Parse.ly iOS SDK is an iOS framework written in Swift providing Parse.ly tracking functionality to native iOS apps. Like any other framework you might include in your iOS app project, the Parse.ly SDK provides a programming interface usable from your application code.
It is also open source and can be found here on Github: https://github.com/Parsely/AnalyticsSDK-iOS

Integrating with Swift Package Manager

Starting with v0.2.2 the Parse.ly SDK can be integrated using Swift Packet Manager.

To use the SDK in a Swift Package Manager project, add the following line to the dependencies in your Package.swift file:

swift.package(url: "https://github.com/Parsely/AnalyticsSDK-iOS", from: "0.2.2")

Include “ParselyAnalytics” as a dependency for your target:

swift.target(name: "<target>", dependencies: [
	.product(name: "ParselyAnalytics", package: "AnalyticsSDK-iOS"),
]),

Below is an example of how you could integrate the SDK with your Package.swift file:

   dependencies: [
        .package(url: "https://github.com/Parsely/AnalyticsSDK-iOS", from: "0.2.2"),
    ],
    targets: [
        .target(
            name: "TryParsely",
            dependencies: [
                .product(name: "ParselyAnalytics", package: "AnalyticsSDK-iOS")
            ]
        ),
    ]

Integrating with CocoaPods

The Parsely Analytics SDK is available via Cocoapods. To start using the Parse.ly iOS SDK in your XCode iOS project, follow these steps:

• Add a line referencing the SDK to your project’s Podfile: pod 'ParselyAnalytics', '~> 0.0.1'
• Replace the version specifier in this Podfile line with the version of the “latest release” from this listing
• Run pod install from your project directory to install the SDK and its dependencies

Using the tracker

At app startup, configure the Parsely singleton. A good place to do this might be the top-level application delegate.

import ParselyAnalytics
// parsely should be a class attribute of AppDelegate
var parsely: Parsely!
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  self.parsely = Parsely.sharedInstance
  self.parsely.configure(siteId: "<PARSELY_SITE_ID>")
  // other app initialization...
  return true
}

Replace <PARSELY_SITE_ID> with your Parse.ly site ID. Often, this will be the domain name of your website.

Once you’ve done this, you can call tracking methods on self.parsely. Here are some examples:

self.parsely.trackPageView(url: "http://mysite.com/story1")
self.parsely.startEngagement(url: "http://mysite.com/story2")
self.parsely.stopEngagement()

Providing metadata

Pageview metadata is only required for URLs not accessible over the internet (i.e. app-only content) or if you are using an “in-pixel” integration. Otherwise, metadata will be gathered by Parse.ly’s crawling infrastructure.

There are two methods for providing Parse.ly with metadata for content that’s only accessible via the Mobile SDK:

1. Primary recommendation: updating metadata using the metadata API endpoint.
2. Back-up option: Sending metadata “in-pixel” with every event sent with the Mobile SDK. This should be used only in special cases. For example, this is an appropriate method for a mobile-app only company.

Metadata objects

Some methods in the SDK’s API accept ParselyMetadata objects as arguments. These objects are used to represent metadata for the content being tracked and conform to a similar standard to the Parsely metadata tag.

You can create a ParselyMetadata object to pass to a tracking function by calling the class’ constructor:

let metadata = ParselyMetadata(authors: ["Jane Doe"], section: "myvertical")
self.parsely.trackPageView("http://mysite.com/story1", metadata: metadata)

API Documentation

Parsely.configure()

Configure the Parsely tracking SDK for this particular run of the application. Should be called once per application load, before other Parsely SDK functions are called.

ParselyMetadata()

NOTE: This metadata class is functionally limited. It does not contain all metadata values. Only use this class to provide metadata if you are choosing to not use the recommended method above.

This is a class used to manage and reuse metadata conforming to Parsely’s schema. Pageview metadata is only required for URLs not accessible over the internet (i.e. app-only content) or if you are using an “in-pixel” integration. Otherwise, metadata will be gathered by Parse.ly’s crawling infrastructure.

Parsely.trackPageView()

Track a pageview event

Parsely.startEngagement() (heartbeat tracking)

Recommended implementation: Call startEngagement when a post is navigated to, and to call stopEngagement when it’s navigated away from.

Start engaged time tracking for the given URL. Once called, heartbeat events will automatically be sent periodically to capture engaged time for this url until engaged time tracking is stopped.

This call also automatically stops tracking engaged time for any urls that are not the current url.

The value of url should be a URL for which trackPageview has been called.

Parsely.stopEngagement()

Stop tracking engaged time for the currently engaged url. This method should be called when a user navigates away from a specific page or piece of content, when the application is backgrounded (using the applicationDidEnterBackground callback), and when the application is forcefully closed (using the applicationWillResignActive callback). Once called, one additional heartbeat event may be sent, after which heartbeat events will stop being sent.

Parsely.trackPlay()

Start tracking view time for a given video being viewed at a given url. Sends a videostart event for the given url/video combination. Once called, vheartbeat events will be sent periodically for this url/video combination until video view tracking is stopped. Stops tracking view time for any url/video combinations currently being tracked for view time.

Parsely.trackPause()

Stop tracking video view time for the currently viewing url/video combination. Once called, one additional vheartbeat event may be sent per previously-viewed url/video combination, after which vheartbeat events will stop being sent.

Parsely.resetVideo()

Unset tracking data for the given url/video combination. The next time trackPlay is called for that combination, it will behave as if it had never been tracked before during this run of the app. This differs from trackPause in that it unlocks videostart events, where that function does not.