Integración con iOS

iOS es la plataforma móvil más mágica del mundo. Estamos muy contentos de tener una biblioteca de integración oficial para iOS. Si buscas Android, por favor revisa la documentación de Android, si buscas React Native por favor revisa la documentación de React Native y para otras integraciones móviles por favor revisa la integración móvil. Si estás con iOS, estás en el lugar correcto. ¡Empecemos!

Instalación

Lo primero que debes hacer es añadir el paquete de Metricalp a tu proyecto. No te preocupes, es un proceso muy simple. Lo añadirás en XCode a través del paquete de Metricalp iOS en GitHub.

El enlace del paquete de GitHub es: https://github.com/metricalp/ios, cópialo y guárdalo.

1. Abre tu proyecto en XCode, haz clic en Archivo en el menú superior. Luego haz clic en Agregar Dependencias de Paquete...

Paso 1 de agregar dependencia en XCode

2. Pega la URL de GitHub anterior en la barra superior derecha de la ventana abierta. Luego haz clic en añadir paquete. Puedes mantener `main` como rama.

Paso 2 de agregar dependencia en XCode

3. Haz clic en añadir paquete.

Paso 3 de agregar dependencia en XCode🚀

Eso es todo. Felicitaciones, ahora estás listo para usar Metricalp en tu aplicación. ¡Vamos allá! 🚀

Uso

Intentamos hacer la integración flexible y fluida para mantener la experiencia del desarrollador al mejor nivel. Aquí compartiremos ejemplos completos de AppDelegate y SceneDelegate para mostrar cómo puedes integrar Metricalp en tu aplicación iOS. Describiremos el código paso a paso como se detalla a continuación.

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": "[email protected]", "metr_user_language": "Spanish-ES", "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:

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.appLeaveEvent(eventAttributes: nil, overrideAttributes: nil)
          }
        
      }

Sabemos que son códigos de aplicación muy básicos, pero ayudarán a comprender los fundamentos, confía en nosotros. Primero, importamos la biblioteca import metricalpios en ambos archivos desde los cuales llamamos métodos.

El primer método que se llama es Metricalp.initMetricalp. Este es el más importante para integrar correctamente la biblioteca. Inicializaremos Metricalp para recopilar eventos. Es importante hacerlo en el archivo de punto de entrada (AppDelegate). Metricalp.initMetricalp toma atributos [String: String], la pantalla inicial path (para el primer screen_view activado automáticamente como opcional). Si proporcionas la pantalla inicial como nil, omitirá el primer evento de screen_view activado automáticamente. Vamos a explicar:

Metricalp.initMetricalp() Atributos Argumentos Propiedades

app

Debes proporcionar el nombre y la versión de tu aplicación. Es importante proporcionar la versión para rastrearla en el tablero. Puedes proporcionarlo en la sintaxis AppName@Version [email protected] como en el ejemplo anterior.

metr_user_language

Debes proporcionar el idioma actual de tu aplicación. Puedes proporcionarlo en la sintaxis Idioma (nombre largo)-País (código ISO) Spanish-ES como en el ejemplo anterior o German-DE oTurkish-TR etc. Si no estás seguro sobre el país, puedes proporcionar desconocido. Por ejemplo, Spanish-unknown

metr_unique_identifier (requerido)

Necesitamos explicar esta propiedad metr_unique_identifier. Normalmente en el seguimiento web, mientras Metricalp no utiliza cookies, como hemos mencionado en muchos lugares, identificamos a los usuarios con sus direcciones IP en hashes unidireccionales. La fórmula es algo así: hash(user_ip + user_agent + salt). Aquí ip + user_agent es casi único para cada usuario. Pero en las aplicaciones móviles, las cadenas de agentes de usuario son inconsistentes y poco fiables. Por lo tanto, necesitamos un identificador único para cada usuario. Dejamos este identificador único a ti. Puedes usar cualquier identificador único para tu aplicación. Por ejemplo, si es una aplicación de autorización y solo realizas un seguimiento después de que los usuarios hayan iniciado sesión, entonces puedes proporcionar los ID de usuario. O puedes usar identificadores únicos relacionados con el dispositivo (Android e iOS tienen algunos métodos nativos para obtenerlos). O puedes generar un UUID aleatorio cuando el usuario abra la aplicación por primera vez y guardarlo en el almacenamiento local. Luego úsalo como metr_unique_identifier. Ahora, el algoritmo de hash será algo así: hash(user_ip + metr_unique_identifier + salt). En este enfoque, el metr_unique_identifier no cambiará a menos que el usuario elimine y reinstale la aplicación. Pero eso es lo suficientemente justo. Si no es suficiente para ti, puedes proporcionar tu propio identificador único como mencionamos anteriormente. ID de usuario o identificador de dispositivo o cualquier otra combinación.

metr_bypass_ip

Esta es una propiedad opcional. Los valores posibles son "enable" o "disable". Si ves el ejemplo de hash final anterior con metr_unique_identifier: hash(user_ip + metr_unique_identifier + salt), todavía tenemos información de IP en el hash. Luego, cuando el usuario, por ejemplo, está en Wifi y luego cambia a la red móvil, la IP cambiará. Mientras que metr_unique_identifier es el mismo, debido al cambio de IP, puede contarse como otro recuento único para ese día. Esta configuración también elimina la IP de la función hash. Si estableces esto en "enable", entonces no usaremos la IP en la función hash (por defecto): hash(metr_unique_identifier + salt). Pero si pasas disable, entonces la IP también se usará en la función hash: hash(user_ip + metr_unique_identifier + salt). No sugerimos esto porque romper el recuento único con la IP no tiene sentido en la mayoría de los escenarios para móviles. Entonces, establecemos esta configuración por defecto en enable. Así que, en la mayoría de los escenarios, simplemente no pases esta opción, déjala como predeterminado (enable).

tid (requerido)

Debes proporcionar tu TID (también conocido como ID de seguimiento) al método initMetricalp. Puedes obtenerlo desde el tablero de Metricalp. Es obligatorio. Si no lo proporcionas, recibirás un error. Puedes encontrar tu tid en la página Embed & Share Tracker.

Hay un evento de sistema importante en Metricalp screen_view. Rastreamos las pantallas visitadas, las tasas de rebote, etc. basándonos en este evento. Por lo tanto, recomendamos encarecidamente que actives este evento en tu aplicación además de cualquier evento personalizado. En tu lógica de navegación, en cada cambio de pantalla por el usuario, debes activar un evento screen_view. En el ejemplo anterior, estamos utilizando el método sceneWillEnterForeground de iOS y activando este evento. Puedes activarlo en otro lugar, el lugar no es importante, pero te aconsejamos que actives este evento en algún lugar para un mejor seguimiento.

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

El método Metricalp.screenViewEvent proporcionado por la biblioteca facilita la tarea. Debes proporcionar el nombre de la pantalla actual (ruta) a este método. También puedes pasar cualquier dato adicional (propiedades personalizadas) a este método como segundo argumento (nuevamente [String: String]). El tercer argumento es otro diccionario de cadenas si deseas sobrescribir las propiedades iniciales (configuraciones) para el evento actual, de lo contrario, solo pasa nil.

swift
Metricalp.screenViewEvent(path: "MainScreen", eventAttributes: ["custom_prop1": "Usuario no autenticado"], overrideAttributes: nil);

o

swift
Metricalp.screenViewEvent(path: "MainScreen", eventAttributes: ["theme": "Tema Oscuro"], overrideAttributes: nil);

Aquí el tema es un alias de propiedad personalizada. Puedes revisar los Eventos y Propiedades Personalizadas para más información.

Hay otra cosa importante que es generar los eventos de salida necesarios al salir de la aplicación. Metricalp también proporciona un método personalizado para esto: Metricalp.appLeaveEvent(). Puedes ver que estamos activando este evento appLeave en el controlador onStop. Esto nos ayuda a capturar las duraciones de la vista de pantalla de los usuarios. También puedes pasar cualquier dato adicional (propiedades personalizadas) a este método como primer argumento (nuevamente [String: String]). El segundo argumento es otro diccionario de cadenas si deseas sobrescribir las propiedades iniciales (configuraciones) para el evento actual, de lo contrario, solo pasa nil.

swift
 func sceneDidEnterBackground(_ scene: UIScene) {
                     Metricalp.appLeaveEvent(eventAttributes: nil, overrideAttributes: nil)
       }

Básicamente, eso es todo. Has integrado con éxito tu aplicación iOS con Metricalp ahora. Una cosa más, también puedes crear algunos eventos personalizados para obtener conocimientos más profundos.

Eventos Personalizados

También hay otro método de la biblioteca para eventos personalizados: Metricalp.customEvent. Toma el tipo de evento como primer argumento y los atributos de datos como segundo argumento. El tercer argumento es otro diccionario de cadenas si deseas sobrescribir las propiedades iniciales (configuraciones) para el evento actual, de lo contrario, solo pasa nil. Puedes usarlo así:

swift
Metricalp.customEvent(type: "button_click", eventAttributes: ["path": "HomepageScreen", "custom_prop1": "botón superior", "theme": "oscuro"], overrideAttributes: nil);

Aquí pasamos la información de la ruta, también pasamos el botón superior como una propiedad personalizada. Pasamos otra propiedad personalizada tema, pero esta vez usamos un alias. Puedes consultar Eventos y Propiedades Personalizadas para obtener información detallada. Ahora, con el poder de los eventos y propiedades personalizados, puedes rastrear y analizar cualquier evento para obtener conocimientos profundos en tu aplicación iOS de manera fácil.