Todos os produtos
Search
Central de documentação

Application Real-Time Monitoring Service:Referência de configuração do RUM SDK para web e HTML5

Última atualização: Aug 17, 2026

O SDK de Real User Monitoring (RUM) para web e HTML5 oferece opções de configuração para coleta de dados, gerenciamento de sessões, filtragem de eventos e detecção de tela branca. Esta referência aborda configurações comuns do SDK, APIs de tempo de execução e exemplos de uso.

Parâmetros de inicialização

Passe estes parâmetros para ArmsRum.init() para configurar o SDK na inicialização.

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

pid

String

Sim

-

ID da aplicação

endpoint

String

Sim

-

Endpoint para envio de dados

env

String

Não

prod

Ambiente da aplicação. Valores válidos: prod, gray, pre, daily, local

version

String

Não

-

Versão da aplicação

user

Object

Não

-

Configurações do usuário. Consulte Parâmetros de usuário

spaMode

String

Não

false

Modo de rastreamento de rotas para aplicações de página única (SPA). Valores válidos: hash, history, auto, false

beforeReport

Function

Não

-

Callback invocado antes do envio de cada relatório para modificar ou bloquear os dados reportados

reportConfig

Object

Não

-

Configurações de envio de dados. Consulte Parâmetros de reportConfig

sessionConfig

Object

Não

-

Configurações de amostragem e armazenamento de sessão. Consulte Parâmetros de sessionConfig

collectors

Object

Não

-

Alternadores dos coletores de dados. Consulte Parâmetros de collectors

parseViewName

Function

Não

-

Parser personalizado para o nome da visualização (view.name). Recebe a URL da página como entrada

parseResourceName

Function

Não

-

Parser personalizado para o nome do recurso (resource.name). Recebe a URL do recurso como entrada

evaluateApi

Function

Não

-

Parser personalizado para eventos de API. Consulte Parâmetros de evaluateApi

filters

Object

Não

-

Regras de filtragem de eventos. Consulte Parâmetros de filters

whiteScreen

Object

Não

-

Configurações de detecção de tela branca. Consulte Parâmetros de whiteScreen

properties

Object

Não

-

Propriedades personalizadas globais anexadas a todos os eventos. Consulte Parâmetros de properties

remoteConfig

Object

Não

-

Entrega de configuração dinâmica. Consulte Configuração dinâmica

Inicialização via CDN

Ao carregar o SDK pela Alibaba Cloud Content Delivery Network (CDN), acesse-o pelo namespace global RumSDK.default:

const ArmsRum = window.RumSDK.default;

// Initialize the SDK after it has loaded.
// Skip this step if you defined window.__rum before the SDK script tag.
ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

// Update configuration at runtime
ArmsRum.setConfig('env', 'pre');

Inicialização via npm

import ArmsRum from '@arms/rum-browser';

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
});

Parâmetros de usuário

Associe as sessões do RUM às suas contas de negócio pelo objeto user.

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

id

String

Não

-

ID do usuário. O SDK gera este valor automaticamente e ele não pode ser modificado

name

String

Não

-

Nome de usuário

tags

String

Não

-

Tags do usuário

Importante

Não sobrescreva user.id. O SDK gera esse valor automaticamente, e sua substituição afeta os cálculos de visitantes únicos (UV). Para vincular sessões ao seu sistema de contas, use user.name ou user.tags.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  user: {
    name: 'your user.name',
    tags: 'your user.tags',
  },
});

Parâmetros de reportConfig

Controle o intervalo de envio e o tamanho do lote de dados.

Parâmetro

Tipo

Obrigatório

Padrão

Intervalo válido

Descrição

flushTime

Number

Não

3000

0 -- 10000

Intervalo de envio em milissegundos. Defina como 0 para envio imediato

maxEventCount

Number

Não

20

1 -- 100

Número máximo de eventos por lote

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  reportConfig: {
    flushTime: 0,       // Report immediately
    maxEventCount: 50,  // Up to 50 events per batch
  },
});

Parâmetros de sessionConfig

Configure a amostragem de sessões, os limites de duração e o armazenamento.

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

sampleRate

Number

Não

1

Taxa de amostragem de 0 a 1. Por exemplo, 0.5 amostra 50% das sessões

maxDuration

Number

Não

86400000

Duração máxima da sessão em milissegundos (padrão: 24 horas)

overtime

Number

Não

3600000

Tempo limite de inatividade da sessão em milissegundos (padrão: 1 hora)

storage

String

Não

localStorage

Local de armazenamento dos dados da sessão. Valores válidos: cookie, localStorage

Detalhes de armazenamento

O parâmetro storage determina onde o SDK persiste os seguintes dados:

  • _arms_uid -- o ID único do usuário (user.id)

  • _arms_session -- metadados da sessão no formato ${sessionId}-${sampled}-${startTime}-${lastTime}:

    • sessionId -- identificador único da sessão

    • sampled -- indica se a amostragem selecionou esta sessão

    • startTime -- timestamp de início da sessão

    • lastTime -- timestamp da última atividade

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  sessionConfig: {
    sampleRate: 0.5,          // Sample 50% of sessions
    maxDuration: 86400000,    // 24-hour maximum
    overtime: 3600000,        // 1-hour inactivity timeout
    storage: 'cookie',        // Use cookie instead of localStorage
  },
});

Parâmetros de collectors

Ative ou desative coletores de dados individuais. Todos os coletores vêm habilitados por padrão.

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

perf

Boolean \

Object

Não

true

Dados de desempenho da página

webvitals

Boolean \

Object

Não

true

Métricas Web Vitals

api

Boolean \

Object

Não

true

Requisições de API (XMLHttpRequest, fetch)

staticResource

Boolean \

Object

Não

true

Requisições de recursos estáticos

consoleError

Boolean \

Object

Não

true

Erros de console

jsError

Boolean \

Object

Não

true

Erros de JavaScript

action

Boolean \

Object

Não

true

Comportamento do usuário. Por padrão, o SDK coleta eventos de clique em seis tipos de elementos DOM: button, a, input, select, option e textarea. Cliques em tags não interativas, como div, dt e span, não são coletados automaticamente, mesmo com cursor:pointer, onclick, role=button ou tabindex:0 definido. O SDK chama getClosestTargetAncestorElement para percorrer a árvore DOM em busca do ancestral interativo mais próximo; assim, um elemento envolvido por uma tag button ou a é coletado por correspondência de ancestral

trackUserInteractions

Boolean

Não

false

Define se devem ser coletados cliques em todos os elementos, incluindo tags não interativas como div, dt e span. Quando ativado, o SDK também registra coordenadas do clique e informações da viewport, adequado para análise de mapas de calor

Escopo de coleta e alternativas

Caso os elementos a rastrear estejam fora do escopo padrão de coleta, utilize uma das abordagens abaixo:

  • Ajuste a estrutura DOM (recomendado): Envolva o elemento a monitorar em uma tag button ou a. O SDK fará a coleta automaticamente por correspondência de ancestral.

  • **Use trackUserInteractions**: Defina trackUserInteractions: true para que o SDK colete eventos de clique em todos os elementos, inclusive tags não interativas. Essa abordagem é ideal para análises de mapa de calor.

  • **Use a API sendCustom**: Chame ArmsRum.sendCustom() para reportar manualmente eventos de clique fora do escopo padrão de coleta. Para detalhes sobre os parâmetros, consulte sendCustom.

Nota

Testes com @arms/rum-browser v0.1.13 indicam que collectors.action foi renomeado para collectors.click, com trackUserInteractions tornando-se uma subopção de collectors.click. Verifique os nomes dos parâmetros correspondentes à versão do SDK em uso.

Exemplo

Desative o rastreamento de interações do usuário:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  collectors: {
    action: false,
  },
});

Parâmetros de evaluateApi

A função evaluateApi personaliza a interpretação de eventos XMLHttpRequest e fetch. Ela recebe três argumentos e retorna um Promise<IApiBaseAttr>.

Argumentos de entrada

Parâmetro

Tipo

Descrição

options

Object

Parâmetros da requisição: url, headers e data. Os campos exatos dependem do método da requisição

response

Object

Corpo da resposta

error

Error

Objeto de erro. Presente apenas quando a requisição falha

Tipo de retorno (IApiBaseAttr)

Os campos retornados substituem os padrões do SDK. Campos omitidos mantêm seus valores padrão.

Campo

Tipo

Obrigatório

Descrição

name

String

Não

Nome da API, geralmente uma URL convergida (máximo de 1.000 caracteres). Por exemplo, /list/$id para /list/123. Tem precedência sobre parseResourceName

message

String

Não

Breve descrição da chamada de API (máximo de 1.000 caracteres)

success

Number

Não

Resultado da requisição: 1 = sucesso, 0 = falha, -1 = desconhecido

duration

Number

Não

Duração total da API

status_code

Number \

String

Não

Código de status

snapshots

String

Não

Snapshot de diagnóstico (máximo de 5.000 caracteres). Armazena reqHeaders, params e resHeaders. Não é indexado e não pode ser usado para consultas ou agregações

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  evaluateApi: async (options, response, error) => {
    let respText = '';
    if (response && response.text) {
      respText = await response.text();
    }

    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      snapshots: JSON.stringify({
        params: 'page=1&size=10',
        response: respText.substring(0, 2000),
        reqHeaders: '',
        resHeaders: '',
      }),
      properties: {
        prop_msg: 'custom msg',
        prop_num: 1,
      },
    };
  },
});

Parâmetros de filters

Exclua eventos específicos de recursos ou exceções do relatório.

Parâmetro

Tipo

Obrigatório

Descrição

resource

MatchOption \

MatchOption[]

Não

Exclui eventos de recursos estáticos e de API (XMLHttpRequest, fetch) correspondentes

exception

MatchOption \

MatchOption[]

Não

Exclui eventos de exceção correspondentes

Tipo MatchOption

type MatchOption = string | RegExp | ((value: string) => boolean);
  • String -- corresponde a qualquer URL ou mensagem iniciada com o valor especificado. Por exemplo, 'https://api.aliyun.com' corresponde a 'https://api.aliyun.com/v1/resource'.

  • RegExp -- compara URLs ou mensagens com uma expressão regular.

  • Function -- recebe a URL ou mensagem como entrada. Retorne true para excluir o evento.

Ao passar um array de valores MatchOption, as condições são avaliadas em ordem. O evento será excluído se qualquer condição for atendida.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  filters: {
    exception: [
      'Test error',                           // Messages starting with 'Test error'
      /^Script error\.?$/,                    // Messages matching this regex
      (msg) => msg.includes('example-error'), // Custom match function
    ],
    resource: [
      'https://example.com/',   // URLs starting with 'https://example.com/'
      /localhost/i,             // URLs containing 'localhost'
      (url) => url.includes('example-resource'),
    ],
  },
});

Parâmetros de whiteScreen

Detecte estados de tela em branco ou tela branca na sua aplicação. Compatível com Chrome 40+ e IE 9+.

Parâmetro

Tipo

Descrição

detectionRules

Array<DetectionRule>

Uma ou mais regras de detecção. As regras são executadas na ordem configurada

DetectionRule

Parâmetro

Tipo

Obrigatório

Padrão

Descrição

target

String

Sim

-

Seletor CSS do elemento a monitorar

test_when

Array

Sim

-

Eventos que disparam a detecção. Valores válidos: LOAD, ERROR, ROUTE_CHANGE, LEAVE

delay

Number

Não

0

Atraso em milissegundos antes do início da detecção após um evento gatilho (exceto ERROR e LEAVE)

tester

String \

Function

Sim

-

Método de detecção. Valores válidos: HAS_CONTENT, SAMPLE, SCREENSHOT ou uma função personalizada

ignoreUrlList

Array<String>

Não

[]

URLs de página a ignorar

configOptions

ConfigOptions

Não

-

Opções específicas do testador. Consulte ConfigOptions

Eventos gatilho

Evento

Descrição

LOAD

Carregamento da página concluído

ERROR

Ocorrência de um erro global de JavaScript

ROUTE_CHANGE

Alteração na rota (history ou hash)

LEAVE

Página prestes a fechar

Métodos de detecção

Método

Funcionamento

HAS_CONTENT

Verifica se existem nós e se contêm textContent

SAMPLE

Define pontos de amostragem na área alvo e verifica se o elemento DOM superior em cada ponto pertence a um conjunto permitido de elementos

SCREENSHOT

Captura uma imagem canvas e compara blocos de pixels para calcular a taxa de tela branca

Função personalizada

Recebe o elemento alvo como entrada. Retorna um CustomTesterResult ou Promise<CustomTesterResult>

Tipo CustomTesterResult:

type CustomTesterResult = {
  hasContent: boolean;               // true = content exists; false = white screen detected
  message?: string;                  // Error message
  snapshot?: Record<string, any>;    // Diagnostic data
}

ConfigOptions

Opções específicas para os métodos de detecção SCREENSHOT e SAMPLE.

Opções de SCREENSHOT:

Parâmetro

Tipo

Padrão

Descrição

colorRange

Array<String>

['rgb(255, 255, 255)']

Cores tratadas como "branco". Formato: rgb(r, g, b)

fillColor

String

'rgba(0, 100, 200, 255)'

Cor de preenchimento aplicada a imagens, vídeos, canvases, SVGs e iframes durante a captura. Não deve sobrepor colorRange

horizontalOffset

Number

0

Deslocamento horizontal (px) a partir da borda esquerda do elemento alvo. Use para excluir uma barra lateral esquerda

verticalOffset

Number

0

Deslocamento vertical (px) a partir da borda superior do elemento alvo. Use para excluir uma barra de navegação superior

pixels

Number

10

Tamanho do bloco de pixels (pixels x pixels) para comparação

threshold

Number

0.8

Limiar da taxa de tela branca. Uma taxa acima desse valor dispara um evento de tela branca

dpr

Number

0.3

Proporção de escala para a imagem capturada

ignoreElements

Array<String>

[]

Seletores CSS de elementos a excluir das capturas

Opções de SAMPLE:

Parâmetro

Tipo

Padrão

Descrição

sampleMethod

`1 \

2 \

3`

2

Padrão de amostragem: 1 = cruz, 2 = cruz intersecionada, 3 = arroz

checkPoints

Number

10

Número de pontos radiais de amostragem. Total de pontos: cruz/cruz intersecionada = 4 * checkPoints + 1; arroz = 8 * checkPoints + 1

threshold

Number

0.8

Limiar da taxa de tela branca

whiteBoxElements

Array<String>

[]

Seletores CSS de elementos considerados "brancos". Quando o elemento superior em um ponto de amostragem corresponder a qualquer seletor, a contagem de tela branca aumenta

Opção compartilhada:

Tanto SCREENSHOT quanto SAMPLE suportam a opção debug (Boolean, padrão: false). Quando ativada, os detalhes da detecção são impressos no console das ferramentas de desenvolvedor do navegador.

Exemplos

Detecção baseada em captura de tela:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SCREENSHOT',
      configOptions: {
        colorRange: ['rgb(255, 255, 255)', 'rgb(0, 0, 0)'],
        threshold: 0.9,
        pixels: 10,
        horizontalOffset: 210,
        verticalOffset: 50,
      },
    }],
  },
});

Detecção baseada em amostragem:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SAMPLE',
      configOptions: {
        sampleMethod: 2,
        checkPoints: 10,
        threshold: 0.9,
        whiteBoxElements: ['.el-skeleton'],
      },
    }],
  },
});

Função de detecção personalizada:

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: async (element) => {
        return {
          hasContent: false,
          message: 'Custom error message',
          snapshot: {
            checkPoints: 100,
            rate: 0.99,
            checkdata: '......',
          },
        };
      },
    }],
  },
});

Parâmetros de properties

Anexe propriedades personalizadas globais a todos os eventos reportados.

Parâmetro

Tipo

Obrigatório

Descrição

[key: string]

String \

Number

Não

Par chave-valor personalizado. A chave deve ser uma string compatível com a especificação JSON, com no máximo 50 caracteres (truncada se maior). Valor string: máximo de 2.000 caracteres. Valores que não sejam string ou number são descartados

Comportamento de mesclagem

  • Propriedades globais (definidas em init()) e propriedades no nível do evento (definidas via evaluateApi, sendCustom, sendException ou sendResource) são mescladas no momento do armazenamento.

  • As propriedades no nível do evento têm precedência. Se a mesma chave existir em ambos os níveis, o valor do evento prevalece.

  • Após a mesclagem, mantém-se no máximo 20 pares chave-valor. Os pares excedentes são ordenados por chave e removidos.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // Keys longer than 50 characters are truncated
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    // String values longer than 2,000 characters are truncated
    more_than_2000_value_limit: new Array(2003).join('1'),
    // Invalid types -- these pairs are removed
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Configuração dinâmica

O SDK suporta entrega remota de definições de configuração. Durante o carregamento inicial, o SDK busca configurações remotas que substituem os valores estáticos de init() e atualiza funcionalidades como instrumentação e envio de dados adequadamente.

Etapa 1: Configure no console ARMS

  1. Acesse Application List e abra sua aplicação.

  2. Navegue até Application Settings > SDK config.

  3. Defina os valores de configuração desejados.

  4. Clique em Confirm Update Dynamic Configuration para enviar as configurações ao servidor remoto do Object Storage Service (OSS).

Etapa 2: Ative no SDK

Adicione o campo remoteConfig ao seu código de inicialização, informando a region onde sua aplicação está hospedada.

CDN:

window.__rum = {
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // Example: "ap-southeast-1" for Singapore
  }
};
<script async src="https://xxid-sdk.rum.aliyuncs.com/v2/browser-sdk.js"></script>

npm:

import ArmsRum from '@arms/rum-browser';

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  remoteConfig: {
    region: "cn-hangzhou"  // Example: "ap-southeast-1" for Singapore
  }
});

Comportamento de cache

Após obter a configuração remota, o SDK armazena as definições em cache localmente. Nas inicializações subsequentes, o SDK prioriza a configuração armazenada em cache.

A configuração dinâmica requer a versão do SDK 0.0.37 ou posterior ao importar via CDN com versão fixada.

Parâmetros resolvidos automaticamente

O SDK resolve automaticamente estas propriedades a partir de endereços IP e cabeçalhos User-Agent. Valores definidos explicitamente têm precedência sobre os valores resolvidos automaticamente.

Parâmetro

Tipo

Obrigatório

Descrição

device

Object

Não

Informações do dispositivo

os

Object

Não

Informações do sistema operacional e container

geo

Object

Não

Geolocalização

isp

Object

Não

Informações do ISP/operadora

net

Object

Não

Informações da conexão de rede

Para detalhes dos campos, consulte a seção Common properties no tópico Dados de log.

Exemplo

ArmsRum.init({
  pid: "<your-app-id>",
  endpoint: "<your-endpoint>",
  geo: {
    country: 'your custom country info',
    city: 'your custom city info',
  },
});

APIs do SDK

Após a inicialização, use estes métodos para modificar configurações e reportar dados personalizados.

getConfig

Recupere a configuração atual do SDK:

const config = ArmsRum.getConfig();

setConfig

Atualize a configuração do SDK em tempo de execução. Passe um único par chave-valor ou um objeto de configuração completo:

// Set a single value
ArmsRum.setConfig('env', 'pre');

// Set multiple values
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

Reporte um evento personalizado. Os campos type e name são obrigatórios.

Parâmetro

Tipo

Obrigatório

Descrição

type

String

Sim

Tipo do evento

name

String

Sim

Nome do evento

group

String

Não

Grupo do evento

value

Number

Não

Valor numérico

properties

Object

Não

Propriedades personalizadas

ArmsRum.sendCustom({
  type: 'CustomEventType1',
  name: 'customEventName2',
  group: 'customEventGroup3',
  value: 111.11,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendException

Reporte uma exceção personalizada. Os campos name e message são obrigatórios.

Parâmetro

Tipo

Obrigatório

Descrição

name

String

Sim

Nome da exceção

message

String

Sim

Mensagem da exceção

file

String

Não

Arquivo de origem

stack

String

Não

Rastreamento de pilha

line

Number

Não

Número da linha

column

Number

Não

Número da coluna

properties

Object

Não

Propriedades personalizadas

ArmsRum.sendException({
  name: 'customErrorName',
  message: 'custom error message',
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendResource

Reporte um evento de recurso personalizado. Os campos name, type e duration são obrigatórios.

Parâmetro

Tipo

Obrigatório

Descrição

name

String

Sim

Nome do recurso

type

String

Sim

Tipo do recurso (por exemplo, css, javascript, xmlhttprequest, fetch, api, image, font)

duration

String

Sim

Tempo de resposta

success

Number

Não

Resultado: 1 = sucesso, 0 = falha, -1 = desconhecido

method

String

Não

Método HTTP

status_code

Number \

String

Não

Código de status

message

String

Não

Mensagem de resposta

url

String

Não

URL da requisição

trace_id

String

Não

ID de rastreamento distribuído

properties

Object

Não

Propriedades personalizadas

ArmsRum.sendResource({
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});