Requirements

• Xcode 9.0+
• iOS 9.0+

Installation

The UserReport iOS SDK can be installed in various ways.

CocoaPods

CocoaPods is a centralized dependency manager for Objective-C and Swift. Go here to learn more.

1. Add the project to your Podfile.

   pod 'UserReport'

2. Run pod install and open the .xcworkspace file to launch Xcode.

3. Import the UserReport framework.

   import UserReport

Swift Package Manager

Swift Package Manager is a tool for managing the distribution of Swift code

1. Go to File > Swift Packages > Add Package Dependency...
2. Put UserReport SDK Github url
3. Click Branch: ‘master’
4. Choose appropriate target

Manually

To install it manually drag the UserReport project into your app project in Xcode or add it as a git submodule. In your project folder enter:

$ git submodule add [email protected]:AudienceProject/userreport-ios-sdk.git

Configure Info.plist

Update your Info.plist with message that will inform the user why app is requesting permission to use data for tracking:

<plist ...>
    <dict ...>

        <key>NSUserTrackingUsageDescription</key>
        <string>This identifier will be used to deliver personalized ads to you.</string>

    </dict>
</plist>

Usage for screen/section tracking

Configure

Configure the UserReport iOS SDK using your PUBLISHER_ID and your MEDIA_ID.

Your PUBLISHER_ID and MEDIA_ID can be found on the Media Setting page in UserReport.

// Configure
UserReport.configure(sakId: "PUBLISHER_ID", mediaId: "MEDIA_ID")

Screen tracking

Automatic tracking

If you want to automatically measure all screen views, your application's ViewControllers should inherit from the UserReportViewController class.

Example of automatic tracking:

class ViewController: UserReportViewController {
    ...
}

Manual tracking

There are two types of tracking:

• Screen view tracking (UserReport.trackScreenView())
• Section view tracking (UserReport.trackSectionScreenView())

If a media (website) has one single topic, it can be tracked using UserReport.trackScreenView().

If a website has different sections, for instance Health, World news and Local news, then it should be tracked using both UserReport.trackScreenView() and UserReport.trackSectionScreenView(sectionId). The sectionId for a particular section can be found on the Media Setting page in UserReport.

Example of manual screen tracking:

class ViewController: UIViewController {
    override open func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)

        // Tracking screen view
        UserReport.trackScreenView()
    }
}

Example of manual section tracking:

class ViewController: UIViewController {
    override open func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)

        // Tracking section view (use both functions)
        UserReport.trackScreenView()
        UserReport.trackSectionScreenView(sectionId)
    }
}

Do not combine automatic and manual tracking

If you use the UserReport.trackSectionScreenView and/or UserReport.trackScreenView() methods, then automatic tracking should be disabled. As you can see in the manual tracking example, the ViewController does not inherit from UserReportViewController.

Usage for surveying

Configure

Configure the UserReport iOS SDK using your SAK_ID, your MEDIA_ID and information about the user.

Your SAK_ID and MEDIA_ID can be found on the Media Setting page in UserReport.

// Create user object (optional)
let user = UserReportUser()
user.email = "[email protected]"

// You can also specify a email hash
user.emailMd5 = "MD5_EMAIL_HASH"
user.emailSha1 = "SHA1_EMAIL_HASH"
user.emailSha256 = "SHA256_EMAIL_HASH"

// Provide additional social network information
user.facebookId = "FACEBOOK_ID"

//It is possible to override the default rules for when a survey will appear.
//However, the settings parameter is optional.
let settings = UserReportSettings()
settings.sessionScreensView = 5
settings.inviteAfterNSecondsInApp = 20

// Configure
UserReport.configure(sakId: "YOUR_SAK_ID", mediaId: "YOUR_MEDIA_ID", user: user, settings: settings)

Display mode

The survey can appear in two ways:

• .alert - show survey like an alert view (Default)
• .fullScreen - show survey in full-screen mode, like the modal view controller

To change the display mode, please specify following:

UserReport.setDisplayMode(.fullscreen)

Change settings

To update the default rules for appear the survey use follow: Though, it is recommended to pass UserReportSettings to configure method instead, use this method only when you want to change rules for already launched app

let settings = UserReportSettings()
settings.sessionScreensView = 5
settings.inviteAfterNSecondsInApp = 20

UserReport.updateSettings(settings)

Mute

For the survey not to appear on important screens, you can use a variable mute.

UserReport.mute = true

Do not forget to restore value back to false.

Update user info

When changing user data, you should also send the updated data to the UserReport iOS SDK.

let user = UserReportUser()
user.email = "[email protected]"

UserReport.updateUser(user)

Session info

UserReport SDK stores the data on the count of screens viewed and the time the application is used. If necessary, you can get this data from a variable session. The session contains the following values:

• screenView - number of screens viewed in the current session
• totalScreenView - number of screens viewed in all session
• sessionSeconds - number of seconds spent in the application for current session
• totalSecondsInApp - number of seconds spent in the application for all time
• localQuarantineDate - date until the survey will not appear again
• settings - current settings for the survey appearance

// Session information about the running time of the application and screen views
let session = UserReport.session

// Get current settings for appear survey
let currentSetting = session?.settings

Manually

If you decide to show the survey yourself, then you can use the following method:

UserReport.tryInvite()

Anonymous tracking mode

If anonymous tracking is enabled: all requests will be fired to the do-not-track domain and IDFA will never be sent. To enable anonymous mode you can use following method:

UserReport.setAnonymousTracking(true)

IDFA

The SDK relies on IDFAs, so make sure to mark the appropriate checkboxes when publishing your app.

License

UserReport iOS SDK is released under the Apache License 2.0. See LICENSE for details.