Tech docs
Integration Docs
iOS Tracking SDK

iOS Tracking SDK

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.

#Including the framework in a project

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 ParselyTracker

// 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()

#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.

ParameterTypeRequiredDescription
siteIdStringyesThe Parsely site ID for which the pageview event should be counted. Can be overridden on individual tracking method calls.
handleLifecycleBoolnoIf true, set up listeners to handle tracking across application lifecycle events. Defaults to true.

#ParselyMetadata()

A class used to manage and reuse metadata conforming to Parsely's schema.

ParameterTypeRequiredDescription
canonical_urlString?noA post's Parse.ly canonical URL. For videos, overridden with the videoID method argument and thus can be omitted
pub_dateDate?noThe date this piece of content was published
titleString?noThe title of the content
authorsArray?noThe names of the authors of the content. Up to 10 authors are accepted
image_urlString?noURL at which the main image for this content is located
sectionString?noThe category or vertical to which this content belongs
tagsArray?noUser-defined tags for the content. Up to 20 are allowed
durationTimeInterval?noThe duration of the content. For videos, overridden by the duration method argument and thus can be omitted

#Parsely.trackPageView()

Track a pageview event

ParameterTypeRequiredDescription
urlStringyesThe url of the page that was viewed
urlrefStringnoThe url of the page that linked to the viewed page. Analogous to HTTP referer
metadataParselyMetadata?noMetadata for the viewed page
extraDataDictionary<String, Any>?noA dictionary of additional information to send with the generated pageview event
siteIdStringnoThe Parsely site ID for which the pageview event should be counted

#Parsely.startEngagement()

Start tracking engaged time for a given url. Once called, heartbeat events will be sent periodically for this url until engaged time tracking is stopped. Stops tracking engaged time for any urls currently being tracked for engaged time.

ParameterTypeRequiredDescription
urlStringyesThe url of the page being engaged with
urlrefStringnoThe url of the page that linked to the page being engaged with. Analogous to HTTP referer
extraDataDictionary<String, Any>?noA dictionary of additional information to send with generated heartbeat events
siteIdStringnoThe Parsely site ID for which the heartbeat events should be counted

#Parsely.stopEngagement()

Stop tracking engaged time for the currently engaged url. 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.

ParameterTypeRequiredDescription
urlStringyesThe url at which the video is being viewed. Equivalent to the url of the page on which the video is embedded. If the video is not embedded in a page, should contain a well-formatted URL on your domain (e.g. http://<PARSELY_SITE_ID>/app-videos). This URL doesn't need to return a 200 status when crawled, but must be well-formatted so Parse.ly systems recognize it as belonging to your site.
urlrefStringnoThe url of the page that linked to the page on which the video is being viewed. Analogous to HTTP referer
videoIDStringyesA string uniquely identifying the video within your Parsely account
durationTimeIntervalyesThe duration of the video
metadataParselyMetadata?noMetadata for the video being viewed
extraDataDictionary<String, Any>?noA dictionary of additional information to send with generated vheartbeat events
siteIdStringnoThe Parsely site ID for which the video events should be counted

#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.

ParameterTypeRequiredDescription
urlStringyesThe url at which the video was being viewed. Equivalent to the url of the page on which the video is embedded
vIdStringyesThe video ID string for the video being reset
rocket emoji