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

XCode dependency add step 1

2. Paste the above GitHub url to right top bar in opened window. Then click add package. You can keep `main` as branch.

XCode dependency add step 2

3. Click add package.

XCode dependency add step 3🚀

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:

swift
      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)
              return true
          }
      
          func application(_ application: UIApplication, configurationForConnecting connectingSceneSession: UISceneSession, options: UIScene.ConnectionOptions) -> UISceneConfiguration {
              return UISceneConfiguration(name: "Default Configuration", sessionRole: connectingSceneSession.role)
            }
        
        }

SceneDelegate:

swift
      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.sessionExitEvent(path: "HomepageScreen", 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

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 + daily_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 (like KeyChain). Then use it as metr_unique_identifier. Now, the hashing algorithm will be like hash(user_ip + metr_unique_identifier + daily_salt). In this approach, the metr_unique_identifier will be unchanged unless user explicitly removes this locally stored data hardly. 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. If you just want to use IP then just pass empty string '' as metr_unique_identifier. But, we strongly suggest to use a unique identifier for better tracking. metr_unique_identifier is optional but suggested.

metr_bypass_ip

This is an optional prop. If you see above final hash example with metr_unique_identifier: hash(user_ip + metr_unique_identifier + daily_salt), we still have IP in hash function. So, 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 will count as another unique count for that day. But, you can by pass this IP uniqueness with this prop. If you set this as "true" (* a string not boolean), then we will not use IP in hash function: hash(metr_unique_identifier + daily_salt). It is again optional but if you provided metr_unique_identifier we are suggesting setting it true for better tracking. If you did not provide metr_unique_identifier, then you can not set this setting to "true".

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 are two important system events in Metricalp screen_view and session_exit. We are tracking visited screens, screen durations, bounce rates etc based on these events. So, we strongly suggesting that you should trigger these events 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. When user leaves application (move to background or a complete exit) you should trigger a session_exit event. In above example, we are using sceneWillEnterForeground and sceneDidEnterBackground methods by iOS and triggering these events. You can use any other library or method to listen these events. You can also use any other method to trigger these events. But, you should trigger these events for better tracking.

swift
      ...
      ...
    func sceneWillEnterForeground(_ scene: UIScene) {
        Metricalp.screenViewEvent(path: "HomepageScreen", eventAttributes: nil, overrideAttributes: nil)
    }

    func sceneDidEnterBackground(_ scene: UIScene) {
        Metricalp.sessionExitEvent(path: "HomepageScreen", eventAttributes: nil, overrideAttributes: nil)
    }
      ...
      ...

Metricalp.screenViewEvent and Metricalp.sessionExitEvent methods provided by library to make it easier for you. You should provide current screen name (path) to these methods. You can also pass any additional data (custom props) to these methods 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.

swift
Metricalp.screenViewEvent(path: "MainScreen", eventAttributes: ["custom_prop1": "Unauthenticated User"], overrideAttributes: nil);

or

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

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:

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