Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.

iOS SDK FAQ

What platforms does Countly iOS SDK support?

Even though its official name is Countly iOS SDK, it supports all Apple platforms (macOS, tvOS and watchOS), in addition to iOS. You can use the same SDK for all kinds of projects with different set of features available for each platform. You can also see how to integrate it into your projects by checking our sample apps here.

Which features are available for each platform?

In addition to Analytics, Custom Events and User Profiles features, Countly iOS SDK has Push Notifications, Crash Reporting, Auto View Tracking, APM & Star-Rating features for iOS platform. Availability of these features for platforms are as follows:

  • iOS
    Analytics, Custom Events, User Profiles, Push Notifications, Crash Reporting, Auto View Tracking, Star-Rating, APM[1]

  • macOS
    Analytics, Custom Events, User Profiles, Crash Reporting[2], APM

  • tvOS
    Analytics, Custom Events, User Profiles, Auto View Tracking, APM

  • watchOS
    Analytics, Custom Events, User Profiles, APM

[1]: APM feature is currently in beta phase and intentionally disabled as it has some conflicts with other 3rd party libraries. For further help please contact us.

[2]: Crash Reporting feature on macOS is currently in beta phase and intentionally disabled. For further help please contact us.

Can I integrate Countly iOS SDK using CocoaPods?

We keep our Countly.podspec file up-to-date, so you can integrate Countly iOS SDK using CocoaPods. But, please make sure you read our notes to avoid issues.

How can I tell which Countly iOS SDK version I am using?

You can check for kCountlySDKVersion constant in Countly iOS SDK source. It is defined like NSString* const kCountlySDKVersion = @"18.08";

What is the difference between Default Properties and Custom Properties of User Profiles?

User Profiles (only available in Enterprise Edition) has two kinds of properties: Default Properties and Custom Properties.

Default Properties are predefined fields like name, username, email, birth year, organization, gender, phone number and profile picture. They are displayed on their own place in User Profiles section. You can set them using default properties on Countly.user singleton ( Ex: Countly.user.email = @"john@doe.com"; ) and record them using [Countly.user save]; method.

Custom Properties are custom defined key-value pairs. You can set them using Countly.user.custom dictionary ( Ex: Countly.user.custom = @{@"testkey1":@"testvalue1", @"testkey2":@"testvalue2"}; ) and record them using [Countly.user save]; method as well.

In addition to this, you can use Custom Property Modifers to set, unset or modify Custom Properties and record your changes using [Countly.user save]; method again.

For details please see User Profiles documentation.

How can I handle logged in and logged out users?

When a user logs in on your app and you have a uniquely identifiable string for that user (like userid or email address), you can use it instead of device ID to track all info afterwards, without losing all the data generated by that user so far. You can use userLoggedIn: method ( Ex: [Countly.sharedInstance userLoggedIn:@"user123@example.com"]; ). This will replace previously used device ID on device, and merge all existing data on server.

Later, when the user logs out, you can use [Countly.sharedInstance userLoggedOut]; method which will switch back to default deviceID and track that device anonymously.

Why events are not displayed on Countly Server dashboard?

Custom events are queued and not sent to server until next updateSessionPeriod (60 seconds by default) or eventSendThreshold (10 by default) is reached. So, a little bit delay for displaying custom events on Countly Server dashboard may be expected, while seeing session data immediately.

In addition to this, Countly iOS SDK sends previously stored requests if exists any, followed by a begin_session request, when it starts. If your app records any custom events meanwhile, these event will be queued and sent to server when all previously queued request are successfully completed.

How should I answer IDFA related questions on iTunesConnect?

Apple has some rules on IDFA usage in the apps depending on purpose. If you are getting warnings about it while sending your app to the App Store, please read this document.

What is zero-IDFA and what should I do about it?

Basically, it is an Apple restriction about Identifier for Advertising introduced on iOS10. If you are using Countly iOS SDK newer than version 16.06.4, you do not need to do anything. Otherwise, please read our blog post for more info.

Why some of the requests can not be processed by Countly Server?

There was a query string encoding bug in Countly iOS SDK on versions 16.02.01 and 16.06. Due to this bug, some carrier names (especially Chinese) in query string cannot be parsed. It is fixed on version 16.06.1. If you are using one of the specified versions, please update the SDK.

Is it possible to use Countly iOS SDK with another crash SDK?

In iOS there can be only one uncaught exception handler. Even though it is possible to save the previous handler and pass the uncaught exception to the previous handler as well, it is not safe to assume that it will work in all cases. As we can't know how other SDKs are implemented or whether iOS will give enough time for the all the handlers to do their work before terminating the app. So, we advise to use Countly as the only crash handler.

How can manually I record push notification custom button actions?

If you have set doNotShowAlertForNotifications flag on initial configuration object to handle push notifications manually, you can create your own custom UI to show notification message and action buttons as you wish. For this, just implement - (void) application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler method in your application's delegate. For details of handling notification manually please see Handling Notifications Manually section.

How can I get rid of compiler warning "No rule to process file"?

If you get Warning: no rule to process file '../countly-sdk-ios/README.md' of type net.daringfireball.markdown for architecture arm64 in Xcode, it means README.md (and/or CHANGELOG.md) file is added to Build Phases > Compile Sources in your target. Please remove README.md from Compile Sources list.

What is the average data size of a Countly iOS SDK request sent to Countly Server?

While there are several types of request Countly iOS SDK sends to Countly Server, most common ones are:

  • Begin Session Request
    It is sent on every app launch (and session start after coming back from the background), and it includes basic metrics.
    An example Begin Session request (498 bytes) :
http://mycountlyserver.com/i?app_key=0000000000000000000000000000000000000000
&device_id=00000000-0000-0000-0000-000000000000
&timestamp=1534402860000&hour=16&dow=5&tz=540
&sdk_version=18.08&sdk_name=objc-native-ios
&begin_session=1
&metrics=%7B%22_device%22%3A%22iPhone9%2C1%22%2C%22_os%22%3A%22iOS%22%2C%22_os_version%22%3A%2211.4.1%22%2C%22_locale%22%3A%22en_JP%22%2C%22_density%22%3A%22%402x%22%2C%22_resolution%22%3A%22750x1334%22%2C%22_app_version%22%3A%221.0%22%2C%20%22_carrier%22%3A%22NTT%22%7D
  • Update Session Request
    It is sent every 60 seconds by default, but it depends Countly iOS SDK initial configuration.
    An example Update Session request (233 bytes) :
http://mycountlyserver.com/i?app_key=0000000000000000000000000000000000000000
&device_id=00000000-0000-0000-0000-000000000000
&timestamp=1534402920000&hour=16&dow=5&tz=540
&sdk_version=18.08&sdk_name=objc-native-ios
&session_duration=60
  • End Session Request
    It is sent at the end of a session, when the app goes to background or terminates.
    An example End Session request (247 bytes) :
http://mycountlyserver.com/i?app_key=0000000000000000000000000000000000000000
&device_id=00000000-0000-0000-0000-000000000000
&timestamp=1534402956000&hour=16&dow=5&tz=540
&sdk_version=18.08&sdk_name=objc-native-ios
&session_duration=36
&end_session=1
  • Other Requests
    For Events, User Details, Push Notifications, Crash Reporting, View Tracking, Feedbacks, Consents and some other features, Countly iOS SDK sends various requests with various data sizes. Frequency and size of these requests depend on Countly iOS SDK initial configuration and your app's use cases, as well as the end user.

What metrics data is collected by Countly iOS SDK?

Countly iOS SDK collects following metrics by default:

  • Device Model
  • Screen Resolution
  • Screen Density
  • OS Name
  • OS Version
  • App Version
  • Locale Identifier
  • Carrier

And if Apple Watch feature is enabled:

  • Paired Apple Watch Presence
  • watchOS App Install Status