Protocole NowAnalyticsService : iOS

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 7 minutes de lecture

    • Le protocole NowAnalyticsService fournit des fonctions qui vous permettent de configurer les propriétés d’analyse, les paramètres utilisateur et les événements pour la gestion de la collecte de données d’analyse utilisateur.

    Un objet conforme à ce protocole est renvoyé par sharedAnalyticsService. Utilisez-le dans votre application pour effectuer des appels d’API.

    Tableau 1. Besoins
    Nom Type Description
    trackingConsent Booléen Marqueur indiquant si l’utilisateur a consenti au suivi de l’analyse pour l’appareil associé. Par défaut, les appareils sont désabonnés. La définition explicite de cette valeur sur faux termine immédiatement toute session en cours et supprime les données enregistrées localement.
    Valeurs valides :
    • true : l’utilisateur a consenti au suivi des données d’analyse sur cet appareil.
    • false : l’utilisateur a refusé le suivi des données.

    NowAnalyticsService : addEvent(named eventName : String, with properties : [String : Any] ?)

    Ajoute un événement d’application, par exemple lorsqu’un utilisateur atteint un niveau ou un écran spécifique, et active la définition de propriétés personnalisées sur l’événement. Ces événements apparaissent sur le tableau de bord dans l’ordre dans lequel ils se sont produits.

    Ces événements s’affichent dans votre tableau de bord d’analyse.

    Tableau 2. Paramètres
    Nom Type Description
    eventName nommé Chaîne Nom de l’événement à ajouter.
    avec des propriétés Tableau Facultatif. Paires clé-valeur de propriété personnalisées pour l’événement. Les clés de propriété ne doivent pas contenir de signes de point (« . ») ou de dollar (« $ »). Ils seront coupés.
    Types de valeurs pris en charge :
    • Date
    • NSNull
    • NSNumber (en anglais seulement)
    • Chaînes
    • URL
    Remarque :
    La taille totale de la clé et de la valeur , eventNamepropriétés ne doit pas dépasser 300 octets (par événement). Les chaînes sont codées en UTF-8. Les événements qui dépassent cette limite sont ignorés.
    Tableau 3. Renvoie
    Type Description
    Aucun

    L’exemple suivant montre comment ajouter un événement « Connexion réussie » et un événement « Ticket ouvert » avec des propriétés.

    // Add event with properties
NowAnalytics.sharedAnalyticsService.addEvent(
  named: "Open Case", with: ["Screen Name": "Case",
                             "Case Number": "123",
                             "Case Priority": 5
])

    NowAnalyticsService : addScreenAction (actionName nommée : chaîne)

    Ajoute une action personnalisée à l’écran actuel. Ces actions apparaissent dans le tableau de bord de l’utilisateur dans le cadre des données de session et décrivent un changement d’écran dans une application.

    Tableau 4. Paramètres
    Nom Type Description
    actionName nommé Chaîne Nom de l’action à ajouter à l’écran, par exemple MyButtonClick.

    Longueur maximale : 256 UTF-8 octets
    Tableau 5. Renvoie
    Type Description
    Aucun 

    // Add event
NowAnalytics.sharedAnalyticsService.addEvent(named: "Successful Login")

    NowAnalyticsService : appendToUserProperty(named propertyName : String, listItem : String)

    Ajoute l’élément spécifié à la liste de propriétés de l’utilisateur spécifié.

    Tableau 6. Paramètres
    Nom Type Description
    propertyName nommé Chaîne Nom de la liste de propriétés de l’utilisateur à laquelle ajouter l’élément listItem .
    listItem (en anglais seulement) Chaîne Élément de liste à ajouter à la propriété.
    Tableau 7. Renvoie
    Type Description
    Aucun 

    // Append handled case to list
NowAnalytics.sharedAnalyticsService.appendToUserProperty(named: "Case Identifiers", listItem: "TASK-1")

    NowAnalyticsService : deleteCurrentUserData(complétion : @escaping ((_ success : Bool) -> Void))

    Supprime toutes les données d’analyse associées à l’utilisateur actuel. Cette méthode annule également l’utilisateur actif actuel et désinscrit cet appareil du suivi futur.

    Pour définir l’utilisateur actuel, utilisez la méthode setUserId().

    Tableau 8. Paramètres
    Nom Type Description
    achèvement @escaping ((_ success : Bool) -> Void) Gestionnaire de complétion à exécuter après la suppression des données d’analyse.
    Valeurs de retour pour le gestionnaire de complétion :
    • Réussite : renvoie une valeur booléenne vrai.
    • Échec : Nul - Une défaillance peut se produire si les serveurs Appsee ne sont pas accessibles, par exemple lorsqu’il n’y a pas de connectivité. En cas d’échec, réessayez la méthode.
    Tableau 9. Renvoie
    Type Description
    Aucun 

    // Delete user data
NowAnalytics.sharedAnalyticsService.deleteCurrentUserData(completion: { (success) -> Void in
  if success {
    // deletion succeeded
  } else {
    // deletion failed
  }
})

    NowAnalyticsService : incUserProperty(named propertyName : chaîne, par valeur : Int)

    Incrémente ou diminue la valeur de la propriété numérique spécifiée de la valeur spécifiée.

    Tableau 10. Paramètres
    Nom Type Description
    propertyName nommé Chaîne Nom de la propriété utilisateur à incrémenter.
    Par valeur Entier Valeur d’incrémentation de la propriété. Entrez une valeur négative pour décrémenter la valeur.
    Tableau 11. Renvoie
    Type Description
    Aucun 

    // Increment the "Cases Handled" count
NowAnalytics.sharedAnalyticsService.incUserProperty(named: "Cases Handled", by: 2)

    NowAnalyticsService : installJavascriptInterface(into webView : WKWebView)

    Active l’appel des méthodes dans l’API SNAnalytics() à partir d’un WebView à l’aide de JavaScript.

    Cette méthode retourne un objet SNMobileAnalytics disponible en JavaScript, qui expose les méthodes natives.

    Tableau 12. Paramètres
    Nom Type Description
    webView WKWebView (en anglais seulement) Objet de webview dans lequel injecter l’interface JavaScript.
    Tableau 13. Renvoie
    Type Description
    Objet SNMobileAnalytics (en anglais seulement) 

    // Register JS object inside the web page
// This will create an object named 'SNMobileAnalytics' on JS that will have the following methods:
// SNMobileAnalytics.setUserId(userId)                  example: SNMobileAnalytics.setUserId("John Doe")
// SNMobileAnalytics.startScreen(screenName)            example: SNMobileAnalytics.startScreen("WelcomeScreen")
// SNMobileAnalytics.addScreenAction(actionName)        example: SNMobileAnalytics.addScreenAction("MyButtonClick")
// SNMobileAnalytics.addEvent(eventName, properties)    example: SNMobileAnalytics.addEvent("Successful Login")
//                                                               SNMobileAnalytics.addEvent("Successful Login", JSON.stringify({"Screen Name": "Case", "Case Number": "123", "Case Priority": 5}))
NowAnalytics.sharedAnalyticsService.installJavascriptInterface(into: webView)

    NowAnalyticsService : removeUserProperty(named propertyName : String)

    Supprime la propriété spécifiée pour l’utilisateur actuel.

    Pour définir l’utilisateur actuel, utilisez la méthode setUserId().

    Tableau 14. Paramètres
    Nom Type Description
    propertyName nommé Chaîne Nom de la propriété de l’utilisateur à supprimer.
    Tableau 15. Renvoie
    Type Description
    Aucun 

    // Remove unnecessary property
NowAnalytics.sharedAnalyticsService.removeUserProperty(named: "Temp Cases")

    NowAnalyticsService : setDelegate(_ delegate : NowAnalyticsServiceDelegate ?)

    Définit une référence faible pour qu’un délégué reçoive des notifications.

    Tableau 16. Paramètres
    Nom Type Description
    délégué NowAnalyticsServiceDelegate Facultatif. Objet qui contient la référence à la classe delegate.
    // Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)
    Tableau 17. Renvoie
    Type Description
    Aucun

    Cet exemple montre comment définir une classe de délégué pour NowAnalyticsServiceDelegate.

    // Define a delegate class for NowAnalyticsServiceDelegate
class NowAnalyticsDelegate: NowAnalytics.NowAnalyticsServiceDelegate {
  func nowAnalyticsSessionShouldStart() -> Bool {
    // Session is about to start, return true to allow session to start
    return true
  }

  func nowAnalyticsSessionDidStart(_ sessionId: String) {
    // Session was started
  }

  func nowAnalyticsSessionShouldEnd(_ sessionId: String) -> Bool {
    // Session is about to end, return true to allow session to end
    return true
  }

  func nowAnalyticsSessionDidEnd(_ sessionId: String) {
    // Session was ended
  }

  func nowAnalyticsDidDetectScreen(_ screenName: String) -> String? {
    // Example of skipping specific screen detection
    if (screenName == "LoginViewController") {
      return nil
    }

    // Example of appending a prefix for every screen detected
    return "MyApp_" + screenName
  }
}

// Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)

    NowAnalyticsService : setUserId(_ userId : chaîne ?)

    Définit l’ID d’utilisateur de l’application pour l’utilisateur actuel. Transmettez nil pour déconnecter l’utilisateur actuel.

    Tableau 18. Paramètres
    Nom Type Description
    userId Chaîne Facultatif. Identificateur d’utilisateur spécifique à l’application.

    Pour déconnecter l’utilisateur actuel, transmettez nil.

    L’ID utilisateur ne doit pas contenir de balises HTML ni de données personnelles telles que le nom, l’adresse e-mail ou le numéro de téléphone.

    Longueur maximale : 256 UTF-8 octets
    Tableau 19. Renvoie
    Type Description
    Aucun 

    // Add several properties at once
NowAnalytics.sharedAnalyticsService.setUserProperties([
  "Cases Handled": 100,
  "Last Login": Date(),
  "Is Remote": true,
  "Profile URL": URL(string: "https://www.servicenow.com")!
])

    NowAnalyticsService : setUserProperties(_ userProperties : [String : Any])

    Définit plusieurs propriétés avec les valeurs spécifiées pour l’utilisateur actuel. Les propriétés peuvent être tout ce que vous souhaitez suivre sur le tableau de bord pour un utilisateur.

    Vous devez appeler la fonction setUserId() avant d’appeler cette fonction.

    Tableau 20. Paramètres
    Nom Type Description
    UserProperties (en anglais seulement) Tableau Paires clé-valeur des propriétés utilisateur à définir.
    Types de valeurs pris en charge :
    • NSNumber (en anglais seulement)
    • Chaînes
    • Date
    • URL
    • NSNull

    La clé ne doit pas contenir de points (« . ») ou de signes dollar (« $ »).

    Longueur maximale :
    • clé : 256 caractères
    • Valeur : 1 000 caractères
    Tableau 21. Renvoie
    Type Description
    Aucun 

    import NowAnalytics

// Initialize the Analytics SDK
NowAnalytics.configure(for: URL(string: "https://my.instance.service-now.com")!)

// Enable tracking consent
NowAnalytics.sharedAnalyticsService.trackingConsent = true

// Set User Id for proper identification
NowAnalytics.sharedAnalyticsService.setUserId("John Doe")

// Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

// Add several properties at once
NowAnalytics.sharedAnalyticsService.setUserProperties([
    "Cases Handled": 100,
    "Last Login": Date(),
    "Is Remote": true,
    "Profile URL": URL(string: "https://www.servicenow.com")!
])

    NowAnalyticsService : setUserProperty(named propertyName : chaîne, avec la valeur : Quelconque ?)

    Définit la propriété spécifiée avec la valeur spécifiée pour l’utilisateur actuel. Vous pouvez définir n’importe quelle propriété qui a du sens pour votre application.

    Vous devez appeler la fonction setUserId() avant d’appeler cette fonction.

    Tableau 22. Paramètres
    Nom Type Description
    propertyName nommé Chaîne Nom de la propriété utilisateur à définir. Ne peut pas contenir de points (« . ») ou de signes dollar (« $ »).

    Longueur maximale : 256 caractères
    avec la valeur N'importe lequel Valeur sur laquelle définir la propriété d’utilisateur.
    Types de valeurs pris en charge :
    • Date
    • NSNull
    • NSNumber (en anglais seulement)
    • Chaînes
    • URL

    Longueur maximale : 1 000 caractères
    Tableau 23. Renvoie
    Type Description
    Aucun 

    // Set the "Role" property of the user to "Admin"
NowAnalytics.sharedAnalyticsService.setUserProperty(named: "Role", with: "Admin")

    NowAnalyticsService : startScreen(named screenName : String)

    Consigne l’heure à laquelle l’écran associé apparaît pour la première fois dans l’interface utilisateur.

    Appelez cette méthode après la méthode viewDidAppear(_ :).

    Tableau 24. Paramètres
    Nom Type Description
    screenName nommé Chaîne Nom de l’écran pour lequel consigner l’heure de début, par exemple WelcomeScreen . Il peut s’agir de tout ce que vous souhaitez définir comme un écran et afficher/regrouper sur un tableau de bord d’analyse.

    Longueur maximale : 256 UTF-8 octets
    Tableau 25. Renvoie
    Type Description
    Aucun 

    // Mark the appearance starting time of a screen
// This method should be usually called from the viewDidAppear
NowAnalytics.sharedAnalyticsService.startScreen(named: "WelcomeScreen")