Integrazione con iOS

iOS è la piattaforma mobile più magica del mondo. Siamo molto felici di avere una libreria di integrazione ufficiale per iOS. Se cerchi Android, controlla la documentazione Android, se cerchi React Native controlla la documentazione di React Native e per altre integrazioni mobili controlla l'integrazione mobile. Se sei con iOS, sei nel posto giusto. Iniziamo!

Installazione

La prima cosa che devi fare è aggiungere il pacchetto Metricalp al tuo progetto. Non preoccuparti, è un processo molto semplice. Lo aggiungerai su XCode tramite il pacchetto Metricalp iOS GitHub.

Il link del pacchetto GitHub è: https://github.com/metricalp/ios, copialo e conservalo.

1. Apri il tuo progetto in XCode, fai clic su File nel menu in alto. Quindi fai clic su Aggiungi Dipendenze Pacchetto...

2. Incolla l'URL di GitHub sopra nella barra in alto a destra nella finestra aperta. Quindi fai clic su aggiungi pacchetto. Puoi mantenere `main` come ramo.

3. Fai clic su aggiungi pacchetto.

🚀

È tutto. Congratulazioni, ora sei pronto per usare Metricalp nella tua applicazione. Andiamo 🚀

Utilizzo

Abbiamo cercato di rendere l'integrazione flessibile e fluida per mantenere l'esperienza dello sviluppatore al massimo livello. Qui condivideremo esempi completi di AppDelegate e SceneDelegate per mostrare come integrare Metricalp nella tua app iOS. Descriveremo il codice passo dopo passo come dettagliato di seguito.

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": "Italian-IT", "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)
          }
        
      }

Sappiamo che sono codici di app molto basici, ma aiuteranno a comprenderne i fondamenti, fidati di noi. Per prima cosa, abbiamo importato la libreria import metricalpios in entrambi i file da cui chiamiamo i metodi.

Il primo metodo chiamato è Metricalp.initMetricalp. Questo è il più importante per integrare correttamente la libreria. Inizializzeremo Metricalp per raccogliere eventi. È importante farlo nel file del punto di ingresso (AppDelegate). Metricalp.initMetricalp prende attributi [String: String], il percorso dello schermo iniziale path (per il primo screen_view attivato automaticamente come opzionale). Se fornisci lo schermo iniziale come nil, salterà il primo evento screen_view attivato automaticamente. Spieghiamo:

Metricalp.initMetricalp() Proprietà degli Argomenti degli Attributi

app

Devi fornire il nome e la versione della tua app. È importante fornire la versione per tracciarla nel dashboard. Puoi fornirlo come sintassi AppName@Version ExampleApp@1.0.0 come nell'esempio precedente.

metr_user_language

Devi fornire la lingua attuale della tua app. Puoi fornirla come sintassi Lingua (nome lungo)-Paese (codice ISO) Italian-IT come nell'esempio precedente o Spanish-ES oTurkish-TR ecc. Se non sei sicuro del paese, puoi fornire unknown. Ad esempio, Italian-unknown

metr_unique_identifier (richiesto)

Dobbiamo spiegare questa proprietà metr_unique_identifier. Normalmente nel tracciamento web, mentre Metricalp non utilizza i cookie, come abbiamo menzionato in molti luoghi, identifichiamo gli utenti con i loro indirizzi IP in hash a senso unico. La formula è qualcosa del tipo: hash(user_ip + user_agent + salt). Qui ip + user_agent è quasi unico per ogni utente. Ma nelle app mobili, le stringhe degli agenti utente sono incoerenti e non affidabili. Quindi abbiamo bisogno di un identificatore unico per ogni utente. Questo identificatore unico lo lasciamo a te. Puoi usare qualsiasi identificatore unico per la tua app. Ad esempio, se è un'app di autorizzazione e tracci solo dopo che gli utenti hanno effettuato l'accesso, puoi fornire gli ID utente. Oppure puoi usare identificatori unici correlati al dispositivo (Android e iOS hanno alcuni metodi nativi per ottenerli). Oppure, puoi generare un UUID casuale quando l'utente apre l'app per la prima volta e salvarlo nella memoria locale. Quindi usalo come metr_unique_identifier. Ora, l'algoritmo di hash sarà qualcosa del tipo: hash(user_ip + metr_unique_identifier + salt). In questo approccio, il metr_unique_identifier rimarrà invariato a meno che l'utente non rimuova e reinstalli l'app. Ma è abbastanza giusto. Se non è sufficiente per te, puoi fornire il tuo identificatore unico come abbiamo menzionato sopra. ID utente o identificatore del dispositivo o qualsiasi altra combinazione.

metr_bypass_ip

Questa è una proprietà opzionale. I valori possibili sono "enable" o "disable". Se vedi l'esempio di hash finale sopra con metr_unique_identifier: hash(user_ip + metr_unique_identifier + salt), abbiamo ancora le informazioni IP nell'hash. Poi, quando l'utente ad esempio è in Wifi e poi passa alla rete mobile, l'IP cambierà. Mentre metr_unique_identifier è lo stesso, a causa del cambio IP, potrebbe essere conteggiato come un altro conteggio unico per quel giorno. Questa impostazione rimuove anche l'IP dalla funzione hash. Se imposti questa opzione su "enable", non useremo l'IP nella funzione hash (per impostazione predefinita): hash(metr_unique_identifier + salt). Ma se passi disable, allora anche l'IP verrà utilizzato nella funzione hash: hash(user_ip + metr_unique_identifier + salt). Non consigliamo questo perché rompere il conteggio unico con l'IP è senza senso nella maggior parte degli scenari per il mobile. Quindi, impostiamo questa impostazione come predefinita su enable. Quindi, nella maggior parte degli scenari, semplicemente non passare questa opzione, lascia che sia predefinita (enable).

tid (richiesto)

Devi fornire il tuo TID (alias Tracking ID) al metodo initMetricalp. Puoi ottenerlo dal dashboard Metricalp. È richiesto. Se non lo fornisci, riceverai un errore. Puoi trovare il tuo tid nella pagina Embed & Share Tracker.

C'è un evento di sistema importante in Metricalp screen_view. Tracciamo gli schermi visitati, i tassi di rimbalzo, ecc. basandoci su questo evento. Quindi, raccomandiamo vivamente di attivare questo evento nella tua app oltre a qualsiasi evento personalizzato. Nella tua logica di navigazione, ad ogni cambio di schermo da parte dell'utente, dovresti attivare un evento screen_view. Nell'esempio sopra, stiamo utilizzando il metodo sceneWillEnterForeground di iOS e attivando questo evento. Puoi attivarlo in un altro posto, il luogo non è importante, ma ti consigliamo di attivare questo evento da qualche parte per un miglior tracciamento.

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

Il metodo Metricalp.screenViewEvent fornito dalla libreria ti facilita il lavoro. Devi fornire il nome dello schermo attuale (percorso) a questo metodo. Puoi anche passare qualsiasi dato aggiuntivo (proprietà personalizzate) a questo metodo come secondo argomento (ancora [String: String]). Il terzo argomento è un altro dizionario di stringhe se desideri sovrascrivere le proprietà iniziali (impostazioni) per l'evento corrente, altrimenti passa semplicemente nil.

Metricalp.screenViewEvent(path: "MainScreen", eventAttributes: ["custom_prop1": "Utente non autenticato"], overrideAttributes: nil);

o

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

Qui il tema è un alias di proprietà personalizzata. Puoi controllare i Eventi e Proprietà Personalizzati per maggiori informazioni.

C'è un'altra cosa importante che è generare i necessari eventi di uscita all'uscita dell'applicazione. Metricalp fornisce anche un metodo personalizzato per questo: Metricalp.appLeaveEvent(). Puoi vedere che stiamo attivando questo evento appLeave nel gestore onStop. Questo ci aiuta a catturare le durate della visualizzazione dello schermo degli utenti. Puoi anche passare qualsiasi dato aggiuntivo (proprietà personalizzate) a questo metodo come primo argomento (ancora [String: String]). Il secondo argomento è un altro dizionario di stringhe se desideri sovrascrivere le proprietà iniziali (impostazioni) per l'evento corrente, altrimenti passa semplicemente nil.

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

Fondamentalmente questo è tutto. Ora hai integrato con successo la tua app iOS con Metricalp. Una cosa in più, puoi anche creare alcuni eventi personalizzati per ottenere approfondimenti più dettagliati.

Eventi Personalizzati

C'è anche un altro metodo dalla libreria per eventi personalizzati: Metricalp.customEvent. Prende il tipo di evento come primo argomento e gli attributi dei dati come secondo argomento. Il terzo argomento è un altro dizionario di stringhe se desideri sovrascrivere le proprietà iniziali (impostazioni) per l'evento corrente, altrimenti passa semplicemente nil. Puoi usarlo così:

Metricalp.customEvent(type: "button_click", eventAttributes: ["path": "HomepageScreen", "custom_prop1": "pulsante superiore", "theme": "scuro"], overrideAttributes: nil);

Qui abbiamo passato le informazioni sul percorso, abbiamo anche passato il pulsante superiore come proprietà personalizzata. Abbiamo passato un'altra proprietà personalizzata tema, ma questa volta abbiamo usato un alias. Puoi controllare Eventi e Proprietà Personalizzati per informazioni dettagliate. Ora con il potere degli eventi e delle proprietà personalizzati, puoi tracciare e analizzare qualsiasi evento per ottenere approfondimenti dettagliati nella tua app iOS facilmente.