Come integrare Engagement in iOSHow to Integrate Engagement on iOS

Questa procedura descrive il modo più semplice per attivare le funzioni di analisi e monitoraggio di Engagement in un'applicazione per iOS.This procedure describes the simplest way to activate Engagement's Analytics and Monitoring functions in your iOS application.

L'Engagement SDK richiede iOS7 o versione successiva e XCode 8: la destinazione della distribuzione dell'applicazione deve essere almeno iOS 7.The Engagement SDK requires iOS7+ and Xcode 8+: the deployment target of your application must be at least iOS 7.

Nota

Se si dipende davvero da XCode 7, è possibile usare iOS Engagement SDK v3.2.4.If you really depend on XCode 7 then you may use the iOS Engagement SDK v3.2.4. Esiste un bug noto nel modulo di copertura di questa precedente versione che si verifica durante l'esecuzione sui dispositivi iOS 10. Per altri dettagli, vedere l'integrazione del modulo di copertura.There is a known bug on the Reach module of this previous version while running on iOS 10 devices see the reach module integration for more details. Se si sceglie di utilizzare l'SDK v3.2.4, ignorare l'importazione di UserNotifications.framework nel passaggio successivo.If you choose to use the SDK v3.2.4 then just skip the UserNotifications.framework import in the next step.

I passaggi seguenti sono sufficienti per attivare la segnalazione dei log necessari per calcolare tutte le statistiche relative a utenti, sessioni, attività, arresti anomali del sistema e dati tecnici.The following steps are enough to activate the report of logs needed to compute all statistics regarding Users, Sessions, Activities, Crashes and Technicals. La segnalazione dei log necessari per calcolare altre statistiche quali eventi, errori e processi deve essere eseguita manualmente mediante l'API di Engagement. Vedere Come usare l'API di Engagement in iOS poiché queste statistiche dipendono dall'applicazione.The report of logs needed to compute other statistics like Events, Errors and Jobs must be done manually using the Engagement API (see How to use the advanced Mobile Engagement tagging API in your iOS app since these statistics are application dependent.

Incorporare l'SDK di Engagement nel progetto iOSEmbed the Engagement SDK into your iOS project

  • Scaricare l’SDK per iOS da qui.Download the iOS SDK from here.
  • Aggiungere Engagement SDK nel progetto iOS: in Xcode fare clic con il pulsante destro del mouse sul progetto, quindi scegliere "Add files to ..." (Aggiungi file a) e infine selezionare la cartella EngagementSDK.Add the Engagement SDK to your iOS project: in Xcode, right click on your project and select "Add files to ..." and choose the EngagementSDK folder.
  • Per il funzionamento di Engagement sono necessari framework aggiuntivi: nell'area di esplorazione dei progetti aprire il riquadro del progetto, quindi selezionare la destinazione corretta.Engagement requires additional frameworks to work: in the project explorer, open your project pane and select the correct target. Aprire la scheda Build Phases (Crea fasi) e nel menu Link Binary With Libraries (Collega binario con librerie) aggiungere i framework come illustrato di seguito:Then, open the "Build phases" tab and in the "Link Binary With Libraries" menu, add these frameworks:

    • UserNotifications.framework: impostare il collegamento come OptionalUserNotifications.framework - set the link as Optional
    • AdSupport.framework: impostare il collegamento come OptionalAdSupport.framework - set the link as Optional
    • SystemConfiguration.framework
    • CoreTelephony.framework
    • CFNetwork.framework
    • CoreLocation.framework
    • libxml2.dylib

Nota

È possibile rimuovere il framework AdSupport.The AdSupport framework can be removed. Engagement necessita di questo framework per raccogliere l'identificatore IDFA (Identifier for Advertising).Engagement needs this framework to collect the IDFA. È tuttavia possibile disabilitare la raccolta di identificatori IDFA <ios-sdk-engagement-idfa> per conformarsi ai nuovi criteri Apple relativi a questo ID.However, IDFA collection can be disabled <ios-sdk-engagement-idfa> to comply with the new Apple policy regarding this ID.

Inizializzare Engagement SDKInitialize the Engagement SDK

È necessario modificare il delegato dell'applicazione:You need to modify your Application Delegate:

  • Nella parte superiore del file di implementazione importare l'agente di Engagement:At the top of your implementation file, import the Engagement agent:

    [...]
    #import "EngagementAgent.h"
    
  • Inizializzare Engagement all'interno del metodo 'applicationDidFinishLaunching:' o 'application:didFinishLaunchingWithOptions:':Initialize Engagement inside the method 'applicationDidFinishLaunching:' or 'application:didFinishLaunchingWithOptions:':

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
      [...]
      [EngagementAgent init:@"Endpoint={YOUR_APP_COLLECTION.DOMAIN};SdkKey={YOUR_SDK_KEY};AppId={YOUR_APPID}"];
      [...]
    }
    

Segnalazione di baseBasic reporting

Per attivare la segnalazione di tutti i log richiesti da Engagement per il calcolo delle statistiche relative a utenti, sessioni, attività, arresti anomali del sistema e dati tecnici, è sufficiente fare in modo che tutte le sottoclassi UIViewController ereditino dalle classi EngagementViewController (stessa regola per UITableViewController -> EngagementTableViewController).In order to activate the report of all the logs required by Engagement to compute Users, Sessions, Activities, Crashes and Technical statistics, you can simply make all your UIViewController sub-classes inherit from the EngagementViewController classes (same rule for UITableViewController -> EngagementTableViewController).

Senza Engagement:Without Engagement :

#import <UIKit/UIKit.h>

@interface Tab1ViewController : UIViewController<UITextFieldDelegate> {
  UITextField* myTextField1;
  UITextField* myTextField2;
}

@property (nonatomic, retain) IBOutlet UITextField* myTextField1;
@property (nonatomic, retain) IBOutlet UITextField* myTextField2;

Con Engagement:With Engagement :

#import <UIKit/UIKit.h>
#import "EngagementViewController.h"

@interface Tab1ViewController : EngagementViewController<UITextFieldDelegate> {
  UITextField* myTextField1;
  UITextField* myTextField2;
}

@property (nonatomic, retain) IBOutlet UITextField* myTextField1;
@property (nonatomic, retain) IBOutlet UITextField* myTextField2;

Metodo alternativo: chiamare startActivity() manualmenteAlternate method: call startActivity() manually

Se non si può o non si vuole eseguire l'overload delle classi UIViewController, è possibile avviare le attività chiamando direttamente i metodi di EngagementAgent.If you cannot or do not want to overload your UIViewController classes, you can instead start your activities by calling EngagementAgent's methods directly.

Importante

iOS SDK chiama automaticamente il metodo endActivity() quando viene chiusa l'applicazione.The iOS SDK automatically calls the endActivity() method when the application is closed. Di conseguenza, è CONSIGLIABILE chiamare il metodo startActivity ogni volta che l'attività dell'utente cambia e non chiamare MAI il metodo endActivity poiché questo metodo forza la chiusura della sessione corrente.Thus, it is HIGHLY recommended to call the startActivity method whenever the activity of the user change, and to NEVER call the endActivity method, since calling this method forces the current session to be ended.

Segnalazione della posizioneLocation reporting

Le condizioni del servizio Apple non permettono alle applicazioni di usare la verifica della posizione per scopi puramente statistici.Apple terms of service do not allow applications to use location tracking for statistics purpose only. È quindi consigliabile abilitare la segnalazione della posizione solo se l'applicazione usa la verifica della posizione anche per altri scopi.Thus, it is recommended to enable location reports only if your application also use the location tracking for another reason.

A partire da iOS 8, è necessario fornire una descrizione dell'uso dei servizi di posizione da parte dell'app, impostando una stringa per la chiave NSLocationWhenInUseUsageDescription o NSLocationAlwaysUsageDescription nel file Info.plist dell'app.Starting with iOS 8, you must provide a description for how your app uses location services by setting a string for the key NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription in your app's Info.plist file. Se si vuole segnalare la posizione in background con Engagement, aggiungere la chiave NSLocationAlwaysUsageDescription.If you want to report location in the background with Engagement, add the key NSLocationAlwaysUsageDescription. In tutti gli altri casi, aggiungere la chiave NSLocationWhenInUseUsageDescription.In all other cases, add the key NSLocationWhenInUseUsageDescription. Si noti che sono necessari sia NSLocationAlwaysAndWhenInUseUsageDescription sia NSLocationWhenInUseUsageDescription per indicare il percorso in background in iOS 11.Note that you need both NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationWhenInUseUsageDescription to report background location on iOS 11.

Segnalazione differita della posizioneLazy area location reporting

La segnalazione differita della posizione consente di segnalare il paese, l'area geografica e la località associati ai dispositivi.Lazy area location reporting allows to report the country, region and locality associated to devices. Questo tipo di segnalazione della posizione usa solo le posizioni di rete, sulla base dell'ID di cella o della connessione Wi-Fi.This type of location reporting only uses network locations (based on Cell ID or WIFI). L'area del dispositivo viene segnalata al massimo una volta per sessione.The device area is reported at most once per session. Il GPS non viene mai usato, per cui l'impatto di questo tipo di segnalazione della posizione sulla batteria è minimo, se non addirittura nullo.The GPS is never used, and thus this type of location report has very few (not to say no) impact on the battery.

Le aree segnalate vengono usate per calcolare statistiche geografiche relative a utenti, sessioni, eventi ed errori.Reported areas are used to compute geographic statistics about users, sessions, events and errors. Possono essere usate anche come criteri nelle campagne Reach.They can also be used as criterion in Reach campaigns. L'ultima area conosciuta segnalata per un dispositivo può essere recuperata grazie all' API del dispositivo.The last known area reported for a device can be retrieved thanks to the [Device API].

Per abilitare la segnalazione differita della posizione, aggiungere la riga seguente dopo l'inizializzazione dell'agente di Engagement:To enable lazy area location reporting, add the following line after initializing the Engagement agent:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [...]
  [[EngagementAgent shared] setLazyAreaLocationReport:YES];
  [...]
}

Segnalazione della posizione in tempo realeReal time location reporting

La segnalazione della posizione in tempo reale consente di segnalare la latitudine e la longitudine associate ai dispositivi.Real time location reporting allows to report the latitude and longitude associated to devices. Per impostazione predefinita, la segnalazione differita della posizione usa solo posizioni di rete (in base all'ID di cella o alla connessione Wi-Fi) ed è attiva solo quando l'applicazione viene eseguita in primo piano, ad esempio durante una sessione.By default, this type of location reporting only uses network locations (based on Cell ID or WIFI), and the reporting is only active when the application runs in foreground (i.e. during a session).

Le posizioni in tempo reale NON sono usate per calcolare dati statistici.Real time locations are NOT used to compute statistics. L'unico scopo è consentire l'uso del criterio di definizione del recinto virtuale in tempo reale <Reach-Audience-geofencing> nelle campagne di copertura.Their only purpose is to allow the use of real time geo-fencing <Reach-Audience-geofencing> criterion in Reach campaigns.

Per abilitare la segnalazione della posizione in tempo reale, aggiungere la riga seguente dopo l'inizializzazione dell'agente di Engagement:To enable real time location reporting, add the following line after initializing the Engagement agent:

[[EngagementAgent shared] setRealtimeLocationReport:YES];

Segnalazione basata su GPSGPS based reporting

Per impostazione predefinita, la segnalazione della posizione in tempo reale usa solo posizioni di rete.By default, real time location reporting only uses network based locations. Per abilitare l'uso di posizioni basate su GPS (che sono molto più precise), aggiungere:To enable the use of GPS based locations (which are far more precise), add:

[[EngagementAgent shared] setFineRealtimeLocationReport:YES];

Segnalazione in backgroundBackground reporting

Per impostazione predefinita, la segnalazione della posizione in tempo reale è attiva solo quando l'applicazione viene eseguita in primo piano, ad esempio durante una sessione.By default, real time location reporting is only active when the application runs in foreground (i.e. during a session). Per abilitare la segnalazione anche in background, aggiungere:To enable the reporting also in background, add:

[[EngagementAgent shared] setBackgroundRealtimeLocationReport:YES withLaunchOptions:launchOptions];

Nota

Quando l'applicazione viene eseguita in background, vengono segnalate solo le posizioni basate sulla rete, anche se è abilitato il GPS.When the application runs in background, only network based locations are reported, even if you enabled the GPS.

Se si implementa questa funzione, viene chiamato startMonitoringSignificantLocationChanges quando l'applicazione passa in background.Implementation of this function will call startMonitoringSignificantLocationChanges when your application goes into the background. Si noti che l'applicazione verrà riavviata automaticamente in background in caso di arrivo di un nuovo evento relativo alla posizione.Be aware that it will automatically relaunch your application into the background if a new location event arrives.

Segnalazione avanzataAdvanced reporting

Facoltativamente, per segnalare eventi, errori e processi specifici dell'applicazione, è necessario usare l'API di Engagement mediante i metodi della classe EngagementAgent .Optionally, if you want to report application specific events, errors and jobs, you need to use the Engagement API through the methods of the EngagementAgent class. Un oggetto di questa classe può essere recuperato chiamando il metodo statico [EngagementAgent shared] .An object of this class can be retrieved by calling the [EngagementAgent shared] static method.

L'API di Engagement consente di usare tutte le funzionalità avanzate di Engagement ed è descritta in dettaglio nell'argomento dedicato all'uso dell'API in iOS, oltre che nella documentazione tecnica relativa alla classe EngagementAgent .The Engagement API allows to use all of Engagement's advanced capabilities and is detailed in the How to Use the Engagement API on iOS (as well as in the technical documentation of the EngagementAgent class).

Disabilitare la raccolta IDFADisable IDFA collection

Per impostazione predefinita, Engagement usa l'identificatore IDFA per identificare un utente in modo univoco.By default, Engagement will use the IDFA to uniquely identify a user. Se però si usano annunci pubblicitari altrove nell'app, è possibile che l'app venga respinta dal processo di verifica di App Store.But if you’re not using advertising elsewhere in the app, you might be rejected by the App Store review process. La raccolta IDFA può essere disabilitata mediante l'aggiunta della macro del preprocessore ENGAGEMENT_DISABLE_IDFA nel file con estensione pch (o nella sezione Build Settings dell'applicazione).IDFA collection can be disabled by adding the preprocessor macro ENGAGEMENT_DISABLE_IDFA in your pch file (or in the Build Settings of your application). In questo modo è possibile assicurarsi che la build dell'applicazione non includa riferimenti a ASIdentifierManager, advertisingIdentifier o isAdvertisingTrackingEnabled.This will ensure that there is no references to ASIdentifierManager, advertisingIdentifier or isAdvertisingTrackingEnabled in the application build.

Integrazione nel file prefix.pch :Integration in the prefix.pch file:

#define ENGAGEMENT_DISABLE_IDFA
...

È possibile verificare la corretta disabilitazione della raccolta IDFA nell'applicazione controllando i log di test di Engagement.You can verify that the IDFA collection is properly disabled in your application by checking the Engagement test logs. Per altre informazioni, vedere la documentazione sul test di integrazione <ios-sdk-engagement-test-idfa>.See the Integration Test<ios-sdk-engagement-test-idfa> documentation for further information.

Disabilitare la segnalazione di logDisable log reporting

Uso di una chiamata del metodoUsing a method call

Se si vuole che Engagement non invii più log, è possibile chiamare:If you want Engagement to stop sending logs, you can call:

[[EngagementAgent shared] setEnabled:NO];

Questa chiamata è persistente: usa NSUserDefaults per archiviare le informazioni.This call is persistent: it uses NSUserDefaults to store the information.

È possibile abilitare di nuovo la segnalazione di log chiamando la stessa funzione con YES.You can enable log reporting again by calling the same function with YES.

Integrazione nel bundle di impostazioniIntegration in your settings bundle

Anziché chiamare questa funzione, è possibile integrare questa impostazione direttamente nel file Settings.bundle esistente.Instead of calling this function, you can also integrate this setting directly in your existing Settings.bundle file. La stringa engagement_agent_enabled deve essere usata come identificatore di preferenze e deve essere associata a un'opzione di attivazione/disattivazione (PSToggleSwitchSpecifier).The string engagement_agent_enabled must be used as a the preference identifier and it must be associated to a toggle switch(PSToggleSwitchSpecifier).

L'esempio seguente di Settings.bundle mostra come implementarla:The following example of Settings.bundle shows how to implement it:

<dict>
    <key>PreferenceSpecifiers</key>
    <array>
        <dict>
            <key>DefaultValue</key>
            <true/>
            <key>Key</key>
            <string>engagement_agent_enabled</string>
            <key>Title</key>
            <string>Log reporting enabled</string>
            <key>Type</key>
            <string>PSToggleSwitchSpecifier</string>
        </dict>
    </array>
    <key>StringsTable</key>
    <string>Root</string>
</dict>