Protocolo NowAnalyticsService - iOS

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 7 min. de leitura

    • O protocolo NowAnalyticsService fornece funções que permitem configurar propriedades de análise, configurações do usuário e eventos para gerenciar a coleta de dados de análise do usuário.

    Um objeto em conformidade com este protocolo é retornado por sharedAnalyticsService. Use-o em sua aplicação para executar chamadas de API.

    Tabela 1. Requisitos
    Nome Tipo Descrição
    acompanhamentoConsentimento Booliano Sinalizador que indica se o usuário consentiu com o acompanhamento de análise do dispositivo associado. Por padrão, os dispositivos são recusados. Definir explicitamente este valor como falso encerrará imediatamente qualquer sessão em andamento e excluirá os dados registrados localmente.
    Valores válidos:
    • verdadeiro: o usuário consentiu com o acompanhamento dos dados de análise neste dispositivo.
    • falso: acompanhamento de dados negado pelo usuário.

    NowAnalyticsService - addEvent(named eventName: cadeia de caracteres, com propriedades: [cadeia de caracteres: qualquer]?)

    Adiciona um evento de aplicação, como um usuário que atinge um nível ou tela específica, e permite a configuração de propriedades personalizadas no evento. Esses eventos aparecem no painel na ordem em que ocorreram.

    Esses eventos aparecem no painel de análise.

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    eventName nomeado Cadeia de caracteres Nome do evento a ser adicionado.
    com propriedades Matriz Opcional. Pares de chave-valor de propriedade personalizada para o evento. As chaves de propriedade não podem conter os sinais de ponto ('.') ou cifrão ('$'). Eles serão cortados.
    Tipos de valor compatíveis:
    • Data
    • NSNUlo
    • NSNumber
    • Strings
    • URL
    Nota:
    O tamanho total de eventName, chave de propriedades e valor não deve exceder 300 bytes (por evento). As cadeias de caracteres são codificadas em UTF-8. Eventos que excedem esse limite são ignorados.
    Tabela 3. Retornos
    Tipo Descrição
    Nenhum(a)

    O exemplo a seguir mostra como adicionar um evento "Login bem-sucedido" e um evento "Abrir caso" com propriedades.

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

    NowAnalyticsService - addScreenAction(named actionName: cadeia de caracteres)

    Adiciona uma ação personalizada à tela atual. Essas ações aparecem no painel do usuário como parte dos dados da sessão e descrevem uma mudança de tela em uma aplicação.

    Tabela 4. Parâmetros
    Nome Tipo Descrição
    ação nomeadaNome Cadeia de caracteres Nome da ação a ser adicionada à tela, como MyButtonClick.

    Tamanho máximo: 256 UTF-8 bytes
    Tabela 5. Retornos
    Tipo Descrição
    Nenhum 

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

    NowAnalyticsService - appendToUserProperty(named propertiesName: cadeia de caracteres, listItem: cadeia de caracteres)

    Anexa o item especificado à lista de propriedades do usuário especificada.

    Tabela 6. Parâmetros
    Nome Tipo Descrição
    nomeada propriedadeNome Cadeia de caracteres Nome da lista de propriedades do usuário à qual o listItem será anexado.
    item da lista Cadeia de caracteres Item de lista a ser anexado à propriedade.
    Tabela 7. Retornos
    Tipo Descrição
    Nenhum 

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

    NowAnalyticsService - deleteCurrentUserData(conclusão: @escaping ((_ sucesso: Bool) -> Anular))

    Exclui todos os dados de análise associados ao usuário atual. Este método também cancela a definição do usuário ativo atual e desativa este dispositivo do acompanhamento futuro.

    Para definir o usuário atual, use o método setUserId().

    Tabela 8. Parâmetros
    Nome Tipo Descrição
    conclusão @escaping ((_ sucesso: Bool) -> Void) Manipulador de conclusão a ser executado depois que os dados de análise forem excluídos.
    Valores de retorno para o manipulador de conclusão:
    • Sucesso: retorna um valor booliano verdadeiro.
    • Falha: anular - A falha pode ocorrer se os servidores do Appsee não puderem ser acessados, como quando não há conectividade. Se ocorrer uma falha, tente o método novamente.
    Tabela 9. Retornos
    Tipo Descrição
    Nenhum 

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

    NowAnalyticsService - incUserProperty(named propertiesName: cadeia de caracteres, por valor: Int)

    Incrementa ou decrementa o valor da propriedade numérica especificada pelo valor especificado.

    Tabela 10. Parâmetros
    Nome Tipo Descrição
    nomeada propriedadeNome Cadeia de caracteres Nome da propriedade do usuário a ser incrementada.
    por valor Números inteiros Valor para incrementar a propriedade. Insira um valor negativo para diminuir o valor.
    Tabela 11. Retornos
    Tipo Descrição
    Nenhum 

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

    NowAnalyticsService - installJavascriptInterface (no webView: WKWebView)

    Habilita a chamada dos métodos na API SNAnalytics() de dentro de um WebView usando JavaScript.

    Este método retorna um objeto SNMobileAnalytics que está disponível em JavaScript, o que expõe os métodos nativos.

    Tabela 12. Parâmetros
    Nome Tipo Descrição
    WebView WKWebView Objeto de exibição da Web no qual a interface JavaScript será injetada.
    Tabela 13. Retornos
    Tipo Descrição
    Objeto SNMobileAnalytics 

    // 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 propertiesName: cadeia de caracteres)

    Exclui a propriedade especificada para o usuário atual.

    Para definir o usuário atual, use o método setUserId().

    Tabela 14. Parâmetros
    Nome Tipo Descrição
    nomeada propriedadeNome Cadeia de caracteres Nome da propriedade do usuário a ser excluída.
    Tabela 15. Retornos
    Tipo Descrição
    Nenhum 

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

    NowAnalyticsService - setDelegate(_ delegado: NowAnalyticsServiceDelegate?)

    Define uma referência fraca para um delegado receber notificações.

    Tabela 16. Parâmetros
    Nome Tipo Descrição
    delegado NowAnalyticsServiceDelegate Opcional. Objeto que contém a referência à classe de delegado.
    // Register delegate
private var analyticsDelegate = NowAnalyticsDelegate()  // Keep ref of delegate
NowAnalytics.sharedAnalyticsService.setDelegate(analyticsDelegate)
    Tabela 17. Retornos
    Tipo Descrição
    Nenhum(a)

    Este exemplo mostra como definir uma classe de delegado para 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: cadeia de caracteres?)

    Define o ID do usuário da aplicação para o usuário atual. Passe nil para fazer logout do usuário atual.

    Tabela 18. Parâmetros
    Nome Tipo Descrição
    userId Cadeia de caracteres Opcional. Identificador de usuário específico da aplicação.

    Para desconectar o usuário atual, passe nil.

    O ID do usuário não deve conter marcadores HTML ou quaisquer dados pessoais, como nome, e-mail ou número de telefone.

    Tamanho máximo: 256 UTF-8 bytes
    Tabela 19. Retornos
    Tipo Descrição
    Nenhum 

    // 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: [Cadeia de caracteres: Qualquer])

    Define várias propriedades com os valores especificados para o usuário atual. As propriedades podem ser qualquer coisa que você queira rastrear no painel de um usuário.

    Você deve chamar a função setUserId() antes de chamar esta função.

    Tabela 20. Parâmetros
    Nome Tipo Descrição
    userProperties Matriz Pares de chave-valor das propriedades do usuário a serem definidos.
    Tipos de valor compatíveis:
    • NSNumber
    • Strings
    • Data
    • URL
    • NSNUlo

    A chave não pode conter pontos ('.') ou cifrões ('$').

    Tamanho máximo:
    • chave: 256 caracteres
    • valor: 1.000 caracteres
    Tabela 21. Retornos
    Tipo Descrição
    Nenhum 

    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 propertiesName: cadeia de caracteres, com valor: qualquer?)

    Define a propriedade especificada com o valor especificado para o usuário atual. Você pode definir qualquer propriedade que faça sentido para sua aplicação.

    Você deve chamar a função setUserId() antes de chamar esta função.

    Tabela 22. Parâmetros
    Nome Tipo Descrição
    nomeada propriedadeNome Cadeia de caracteres Nome da propriedade do usuário a ser definida. Não pode conter pontos ('.') ou cifrões ('$').

    Tamanho máximo: 256 caracteres
    com valor Qualquer Valor para definir a propriedade do usuário.
    Tipos de valor compatíveis:
    • Data
    • NSNUlo
    • NSNumber
    • Strings
    • URL

    Tamanho máximo: 1.000 caracteres
    Tabela 23. Retornos
    Tipo Descrição
    Nenhum 

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

    NowAnalyticsService - startScreen(named screenName: cadeia de caracteres)

    Registra em log a hora em que a tela associada aparece pela primeira vez na IU.

    Chame este método após o método viewDidAppear(_:).

    Tabela 24. Parâmetros
    Nome Tipo Descrição
    screenName chamado Cadeia de caracteres Nome da tela para registrar a hora de início, como TelaDeBoas-vindas . Pode ser qualquer coisa que você queira definir como uma tela e exibir/agregar em um painel de análise.

    Tamanho máximo: 256 UTF-8 bytes
    Tabela 25. Retornos
    Tipo Descrição
    Nenhum 

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