Integration with iOS
iOS is the most magical mobile platform in the world. We are very happy to having an official integration library for iOS. If you are looking for Android please check Android docs, if you are looking for React Native please check React Native docs and for other mobile integrations please check mobile integration. If you are with iOS, you are in the right place. Let's start!
Installation
First thing you need to do is adding Metricalp package to your project. No worries, it is very simple process. You will add it on XCode through Metricalp iOS Github package.
The GitHub package link is: https://github.com/metricalp/ios copy and keep it.
1. Open your project in XCode, click File in top menu. Then click Add Package Dependencies...
2. Paste the above GitHub url to right top bar in opened window. Then click add package. You can keep `main` as branch.
3. Click add package.
🚀That's all. Congrats on you, now you are ready to use Metricalp in your application. Let's go 🚀
Usage
We tried to make integration flexible and smooth to keep developer experience in best level. Here we will share a complete AppDelegate and SceneDelegate examples to show how you can integrate Metricalp to your iOS app. We will describe the code step by step as detailed below.
AppDelegate:
import UIKit
import metricalpios
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Metricalp.initMetricalp(attributes: ["tid": "mam48", "app": "ExampleiOSApp@1.0.0", "metr_user_language": "English-US", "metr_unique_identifier": "<GENERATED_UUID>"], initialScreen: nil, eventAttributes: nil)
return true
}
func application(_ application: UIApplication, configurationForConnecting connectingSceneSession: UISceneSession, options: UIScene.ConnectionOptions) -> UISceneConfiguration {
return UISceneConfiguration(name: "Default Configuration", sessionRole: connectingSceneSession.role)
}
}SceneDelegate:
import UIKit
import metricalpios
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
var window: UIWindow?
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
guard let _ = (scene as? UIWindowScene) else { return }
}
func sceneWillEnterForeground(_ scene: UIScene) {
Metricalp.screenViewEvent(path: "HomepageScreen", eventAttributes: nil, overrideAttributes: nil)
}
func sceneDidEnterBackground(_ scene: UIScene) {
Metricalp.appLeaveEvent(eventAttributes: nil, overrideAttributes: nil)
}
}We know it is a very basic app codes but it will help to get it fundamentals, trust us. Firstly, we imported import metricalpios library in both files which we call methods through it.
The first method to call is Metricalp.initMetricalp. This is the most important one to properly integrate library. We will init Metricalp to collect events. It is important to do this in entrypoint file (AppDelegate). Metricalp.initMetricalp takes attributes [String: String], initial screen path (for auto triggered first screen_view as optional). If provide initial screen as nil, then it will skip auto triggered first screen_view event. Let's explain:
Metricalp.initMetricalp() Attributes Argument Props
app
You should provide your app name and version. It is important to provide version to track it in dashboard. You can provide it as AppName@Version syntax ExampleApp@1.0.0 like above example.
metr_user_language
You should provide your current app language. You can provide it as Language (long name)-Country(ISO Code) syntax English-US like above example or Spanish-ES orTurkish-TR etc. If you are not sure about country, you can provide unknown. For example English-unknown
metr_unique_identifier (required)
We need to explain this metr_unique_identifier prop. Normally in Web tracking, while Metricalp is not using cookies as we mentioned in many places, we are identifying users with their IP addresses in one-way hashes. The formula is something like this: hash(user_ip + user_agent + salt). Here ip + user_agent is almost unique for every user. But in mobile apps, user agent strings are inconsistent and not reliable. So we need to have a unique identifier for every user. We left this unique identifier to you. You can use any unique identifier for your app. For example if it is an authorization app and you are tracking only after users logged-in, then you can provide user ids. Or you can use device related real unique identifiers (Android and iOS has some native methods to get it). Or, you can generate a random UUID when user first opens the app and store it in local storage. Then use it as metr_unique_identifier. Now, the hashing algorithm will be like hash(user_ip + metr_unique_identifier + salt). In this approach, the metr_unique_identifier will be unchanged unless user removes and re-installs the app. But that is fair enough. If it is not enough for you, you can provide your own unique identifier as we mentioned above. User ID or device identifier or any other combination.
metr_bypass_ip
This is an optional prop. Possible values are "enable" or "disable". If you see above final hash example with metr_unique_identifier: hash(user_ip + metr_unique_identifier + salt), we still have IP info in the hash. Then, when user for example in Wifi and then changed to mobile network, then IP will be changed. While metr_unique_identifier is same, because of IP change, it may count as another unique count for that day. This setting removes also ip from hash. If you set this as "enable", then we will not use IP in hash function (as default): hash(metr_unique_identifier + salt). But if you pass disable, then ip will also used in hash function: hash(user_ip + metr_unique_identifier + salt). We are not suggesting this because breaking unique count with ip is meaningless in most scenarios for mobile. Then, we set this settings default as enable. So, in most scenarios just do not pass this option, let it be default (enable).
tid (required)
You should provide your TID (a.k.a Tracking ID) to initMetricalp method. You can get it from Metricalp dashboard. It is required. If you don't provide it, you will get an error. You can find your tid in Embed & Share Tracker page.
There is one important system event in Metricalp screen_view. We are tracking visited screens, bounce rates etc based on this event. So, we strongly suggesting that you should trigger this event in your app additional to any custom events. In your navigation logic, on every screen change by user you should trigger a screen_view event. In above example, we are using sceneWillEnterForeground method by iOS and triggering this event. You can trigger it in somewhere else, place is not important but we are advising that you should trigger this event in somewhere for better tracking.
...
...
func sceneWillEnterForeground(_ scene: UIScene) {
Metricalp.screenViewEvent(path: "HomepageScreen", eventAttributes: nil, overrideAttributes: nil)
}
...
...Metricalp.screenViewEvent method provided by library to make it easier for you. You should provide current screen name (path) to this method. You can also pass any additional data (custom props) to this method as second argument (again [String: String]). The third argument is another String dictionary if you wish override initial props (settings) for current event otherwise just pass nil.
Metricalp.screenViewEvent(path: "MainScreen", eventAttributes: ["custom_prop1": "Unauthenticated User"], overrideAttributes: nil);or
Metricalp.screenViewEvent(path: "MainScreen", eventAttributes: ["theme": "Dark Theme"], overrideAttributes: nil);Here the theme is a custom prop alias. You can check Custom Event & Props docs for detailed info.
There is another important thing is generating necessary leave events on application leave. Metricalp also provides a custom method for this Metricalp.appLeaveEvent(). You can see that we are triggering this appLeave event in onStop handler. This helps us to catch screen view durations of users. You can also pass any additional data (custom props) to this method as first argument argument (again [String: String]). The second argument is another String dictionary if you wish override initial props (settings) for current event otherwise just pass nil.
func sceneDidEnterBackground(_ scene: UIScene) {
Metricalp.appLeaveEvent(eventAttributes: nil, overrideAttributes: nil)
}Basically that is all. You successfully integrated your iOS app with Metricalp now. One more thing is, you can also create some custom events to get more deep insights.
Custom Events
There is also another method from library for custom events: Metricalp.customEvent. It takes event type as first argument and data attributes as second argument. The third argument is another String Dictionary if you wish override initial props (settings) for current event otherwise just pass nil. You can use it like:
Metricalp.customEvent(type: "button_click", eventAttributes: ["path": "HomepageScreen", "custom_prop1": "top_button", "theme": "dark"], overrideAttributes: nil);Here we passed path info, also we passed top_button info as custom_prop. We passed another custom prop theme but we used alias this time. You can check Custom Event & Props for detailed info. Now with power of custom events and props you can track and analyze any event to get deep insights in your iOS app easily.