Interface do NowAnalyticsSDK - Android

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 8 min. de leitura

    • A interface do NowAnalyticsSDK fornece funções que permitem configurar propriedades de análise, configurações de usuário e eventos para gerenciar uma coleção de dados de análise de usuário.

    Tabela 1. Propriedades
    Nome Tipo Descrição
    configuração NowServiceConfiguration Configuração a ser associada ao serviço.

    NowAnalyticsSDK - addEvent(eventName: cadeia de caracteres)

    Adiciona um evento da aplicação, como um usuário que atinge um nível ou tela específica. Esses eventos aparecem no painel na ordem em que ocorreram.

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    eventName nomeado Cadeia de caracteres Nome do evento a ser adicionado.
    Tabela 3. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar essa função para adicionar um evento da aplicação.

    // Add event
NowAnalyticsSDK.getAnalyticsService().addEvent("Successful Login")

    NowAnalyticsSDK - addEvent(eventName: cadeia de caracteres, props: MutableMap<String, Any> )

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

    Tabela 4. Parâmetros
    Nome Tipo Descrição
    eventName Cadeia de caracteres Nome do evento a ser adicionado.
    props MutableMap Pares de chave-valor de propriedade personalizada para o evento.

    O tamanho total do nome do evento, chave de propriedade e valor não pode exceder 300 bytes por propriedade. Propriedades que excedem esse limite são ignoradas. As chaves de propriedade não podem conter sinais de ponto ('.') ou dólar ('$'). Se contiverem, eles serão cortados. As cadeias de caracteres são codificadas em UTF-8.

    Tipos de valor compatíveis:
    • Inteiro
    • Duplo
    • Flutuante
    • Cadeia de caracteres
    • Url
    • Booliano
    • Data
    Tabela 5. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para adicionar um evento de aplicação que inclui propriedades personalizadas para o evento.

    // Add event with properties
NowAnalyticsSDK.getAnalyticsService().addEvent("Open Case",
  mutableMapOf(
    "Screen Name" to "Case",
    "Case Number" to 123,
    "Case Priority" to 5
  )
)

    NowAnalyticsSDK - addScreenAction(actionName: String)

    Adiciona uma ação personalizada. 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 6. Parâmetros
    Nome Tipo Descrição
    actionName Cadeia de caracteres Nome da ação a ser adicionada à tela, como MyButtonClick.
    Tabela 7. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para adicionar uma ação personalizada à tela atual.

    // Add a custom action to the current screen
NowAnalyticsSDK.getAnalyticsService().addScreenAction("MyButtonClick")

    NowAnalyticsSDK - appendToUserProperty(propertyName: String, item: String)

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

    Tabela 8. Parâmetros
    Nome Tipo Descrição
    propertyName Cadeia de caracteres Nome da propriedade do usuário à qual o item da lista será anexado.
    item Cadeia de caracteres Item da lista a ser anexado à propriedade.
    Tabela 9. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para anexar um caso à lista especificada.

    // Append handled case to list
NowAnalyticsSDK.getAnalyticsService().appendToUserProperty("Case Identifiers", "TASK-1")

    NowAnalyticsSDK - configure(instanceURL: URL, configureCallbacks: ConfigureCallbacks?)

    Configura o URL da instância ServiceNow especificado e os retornos de chamada para o NowAnalytics.

    Depois que esse método é chamado, a configuração real é buscada na instância ServiceNow associada e sincronizada automaticamente.

    Tabela 10. Parâmetros
    Nome Tipo Descrição
    URL da instância URL URL da instância ServiceNow a ser associada ao serviço NowAnalyticfs.
    configurarRetornos de chamada ConfigurarRetornos de Chamada Opcional. Retorno de chamada a ser executado sempre que houver um erro de comunicação com a instância ServiceNow. Este retorno de chamada pode ser chamado a qualquer momento e pode ser chamado várias vezes por vários motivos.
    Tabela 11. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para configurar a instância especificada.

    // Init NowAnalytics after NowSDK is initialized
NowAnalyticsSDK.getAnalyticsService().configure(URL("https://my.instance.service-now.com"),
  // Optional - pass callback
  object: ConfigureCallbacks {
    override fun onFail(e: Exception) {
      // configuration failed
    }

    override fun onSuccess() {
      // configuration succeeded
    }
  }
)

    NowAnalyticsSDK - deleteCurrentUserData()

    Exclui todos os dados locais e remotos do usuário atual.

    Este método também desativa o usuário ativo atual e opta por excluir este dispositivo do acompanhamento de análises futuras.
    Nota:
    Este método executa uma chamada síncrona para os servidores SNAnalytics. Portanto, é recomendável que você execute isso em um thread lateral.
    Tabela 12. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 13. Retorna
    Tipo Descrição
    Booliano Sinalizador que indica se a exclusão foi bem-sucedida.
    Valores possíveis:
    • verdadeiro: a exclusão foi bem-sucedida.
    • false: falha na exclusão. Pode ocorrer falha se os servidores SNAnalytics não puderem ser acessados, por exemplo, quando não houver conectividade. O método deve ser repetido.

    O exemplo de código a seguir mostra como chamar essa função para excluir os dados do usuário atual.

    // Delete user data
NowAnalyticsSDK.getAnalyticsService().deleteCurrentUserData()

    NowAnalyticsSDK - getTrackingConsent()

    Retorna a resposta de consentimento do usuário atual para o acompanhamento de análise.

    Tabela 14. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 15. Retorna
    Tipo Descrição
    Booliano Sinalizador que indica se o usuário atual consentiu em ter seus dados coletados.
    Valores possíveis:
    • verdadeiro: o usuário concordou em ter seus dados coletados.
    • falso: o usuário recusou a coleta de dados.

    O exemplo de código a seguir mostra como chamar essa função para solicitar a resposta de consentimento do usuário atual para o acompanhamento de análise.

    // Get the current user tracking consent value
val curUserConsent = NowAnalytics.sharedAnalyticsService.getTrackingConsent()

    NowAnalyticsSDK - incUserProperty(propertyName: cadeia de caracteres, valor: duplo)

    Aumenta ou diminui o valor da propriedade numérica especificada pelo valor especificado.

    Tabela 16. Parâmetros
    Nome Tipo Descrição
    propertyName Cadeia de caracteres Nome da propriedade do usuário a ser incrementada.
    valor Duplo Valor para incrementar a propriedade. Insira um valor negativo para diminuir o valor.
    Tabela 17. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função.

    // Increment numeric_property_name by one
NowAnalyticsSDK.getAnalyticsService().incUserProperty("numeric_property_name", 1.0)

// Decrement numeric_property_name by one
NowAnalyticsSDK.getAnalyticsService().incUserProperty("numeric_property_name", -1.0)

    NowAnalyticsSDK - installJavascriptInterface(webView: WebView)

    Habilita a chamada de métodos javaScript.SNMobileAnalytics de dentro de um {@link Android.WebKit.WebView}, usando JavaScript.

    Tabela 18. Parâmetros
    Nome Tipo Descrição
    WebView WKWebView O {@link Android.WebKit.WebView} ao qual será anexado.
    Tabela 19. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar essa função para habilitar a chamada de métodos javaScript.SNMobileAnalytics.

    // Register JS object inside the web page
// This creates an object called 'SNMobileAnalytics' on JS that has 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}))
NowAnalyticsSDK.getAnalyticsService().installJavascriptInterface(webView)

    NowAnalyticsSDK - removeUserProperty(propertyName: String)

    Exclui a propriedade especificada para o usuário atual.

    Tabela 20. Parâmetros
    Nome Tipo Descrição
    propertyName Cadeia de caracteres Nome da propriedade do usuário a ser excluída.
    Tabela 21. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para remover a propriedade "Casos temporários".

    // Remove unnecessary property
NowAnalyticsSDK.getAnalyticsService().removeUserProperty("Temp Cases")

    NowAnalyticsSDK - setListener(nowAnalyticsListener: NowAnalyticsListener?)

    Define um ouvinte nos eventos do NowAnalytics, como mudanças de sessão e detecções de tela automáticas.

    Nota:
    Toda vez que você chama este método, o ouvinte é substituído.
    Tabela 22. Parâmetros
    Nome Tipo Descrição
    Ouvinte do nowAnalytics Ouvinte do NowAnalytics A interface que o NowAnalytics notifica para eventos de sessão.
    • onNowAnalyticsScreenDetected: chamado quando o NowAnalytics detecta automaticamente uma tela.
    • onNowAnalyticsSessionEnded: chamado após o término de uma sessão.
    • onNowAnalyticsSessionEnding: chamado pouco antes de uma sessão estar prestes a terminar, permitindo impedir que a sessão seja encerrada.
    • onNowAnalyticsSessionStarted: chamado quando uma sessão é iniciada.
    • onNowAnalyticsSessionStarting: chamado logo antes de uma sessão estar prestes a iniciar, permitindo impedir que a sessão seja iniciada.
    Tabela 23. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar essa função para definir o NowAnalyticsListener().

    // From anywhere in the code you can register the delegate
NowAnalyticsSDK.getAnalyticsService().setListener(NowAnalyticsListener())

    NowAnalyticsSDK - setTrackingConsent(consentGiven: booliano)

    Define a resposta de consentimento do usuário atual para o acompanhamento de análise.

    Tabela 24. Parâmetros
    Nome Tipo Descrição
    consentimentoGanhado Booliano Sinalizador que indica o consentimento do usuário atual para acompanhamento de análise.
    Valores válidos:
    • verdadeiro: o usuário consentiu em ter seus dados rastreados.
    • falso: o usuário optou por não ter seus dados rastreados.
    Tabela 25. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para definir a resposta de consentimento do usuário atual para acompanhamento de análise.

    // Enable tracking consent
NowAnalyticsSDK.getAnalyticsService().setTrackingConsent(true)

    NowAnalyticsSDK - setUserId(userId: String)

    Define o identificador de usuário específico da aplicação. Passe nil para desconectar o usuário atual.

    Tabela 26. Parâmetros
    Nome Tipo Descrição
    userId Cadeia de caracteres Identificador de usuário exclusivo específico da aplicação. Este identificador é usado para agregar relatórios para esse usuário no painel.
    Tabela 27. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar essa função para definir o identificador de usuário específico da aplicação como "João Silva".

    // Set User Id for proper identification
NowAnalyticsSDK.getAnalyticsService().setUserId("John Doe")

    NowAnalyticsSDK - setUserProperties(userProperties: MutableMap<String, Any> )

    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 para um usuário.

    Para definir o usuário atual, chame a função NowAnalyticsSDK - setUserId(userId: String).

    Tabela 28. Parâmetros
    Nome Tipo Descrição
    userProperties MutableMap Pares de chave-valor das propriedades do usuário a serem definidos.
    Tipos de valor compatíveis:
    • Número
    • Strings
    • Data
    • URL
    • Nulo
    Tabela 29. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para definir várias propriedades para o usuário atual.

    // Add several properties at once
NowAnalyticsSDK.getAnalyticsService().setUserProperties(
  mutableMapOf(
    "Cases Handled" to 100,
    "Last Login" to Date(),
    "Is Remote" to true,
    "Profile URL" to URL("https://www.servicenow.com")
  )
)

    NowAnalyticsSDK - setUserProperty(propertyName: cadeia de caracteres, propertyValue: Any)

    Define a propriedade especificada com o valor especificado para o usuário atual. As propriedades podem ser qualquer coisa que você queira rastrear no painel para um usuário.

    Para definir o usuário atual, chame a função NowAnalyticsSDK - setUserId(userId: String).

    Tabela 30. Parâmetros
    Nome Tipo Descrição
    propertyName Cadeia de caracteres Nome da propriedade do usuário a ser definida.
    valor Qualquer Valor para definir a propriedade do usuário.
    Tipos de valor compatíveis:
    • Número
    • Strings
    • Data
    • URL
    • Nulo
    Tabela 31. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para definir a propriedade "Função" como "Admin" para o usuário atual.

    // Set the "Role" property of the user to "Admin"
NowAnalyticsSDK.getAnalyticsService().setUserProperty("Role", "Admin")

    NowAnalyticsSDK - startScreen(screenName: cadeia de caracteres)

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

    Você normalmente chama este método do método onResume() da atividade.

    Tabela 32. 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.
    Tabela 33. Retorna
    Tipo Descrição
    Nenhum

    O exemplo de código a seguir mostra como chamar esta função para definir a hora de início da exibição da "WelcomeScreen".

    // Mark the appearance starting time of a screen
// This method should be usually called from the onResume() method
NowAnalyticsSDK.getAnalyticsService().startScreen("WelcomeScreen")