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: |
|
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: |
|
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 ( |
|
parseResourceName |
Function |
Não |
- |
Parser personalizado para o nome do recurso ( |
|
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 |
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 |
|
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 |
|
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: |
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ãosampled-- indica se a amostragem selecionou esta sessãostartTime-- timestamp de início da sessãolastTime-- 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: |
|
trackUserInteractions |
Boolean |
Não |
false |
Define se devem ser coletados cliques em todos os elementos, incluindo tags não interativas como |
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
buttonoua. O SDK fará a coleta automaticamente por correspondência de ancestral.**Use
trackUserInteractions**: DefinatrackUserInteractions: truepara 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**: ChameArmsRum.sendCustom()para reportar manualmente eventos de clique fora do escopo padrão de coleta. Para detalhes sobre os parâmetros, consulte sendCustom.
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: |
|
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, |
|
|
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: |
|
|
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 |
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
truepara 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 |
|
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: |
|
|
delay |
Number |
Não |
0 |
Atraso em milissegundos antes do início da detecção após um evento gatilho (exceto |
|
|
tester |
String \ |
Function |
Sim |
- |
Método de detecção. Valores válidos: |
|
ignoreUrlList |
|
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 |
|
|
Carregamento da página concluído |
|
|
Ocorrência de um erro global de JavaScript |
|
|
Alteração na rota (history ou hash) |
|
|
Página prestes a fechar |
Métodos de detecção
|
Método |
Funcionamento |
|
|
Verifica se existem nós e se contêm |
|
|
Define pontos de amostragem na área alvo e verifica se o elemento DOM superior em cada ponto pertence a um conjunto permitido de elementos |
|
|
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 |
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 |
|
|
Cores tratadas como "branco". Formato: |
|
fillColor |
String |
|
Cor de preenchimento aplicada a imagens, vídeos, canvases, SVGs e iframes durante a captura. Não deve sobrepor |
|
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 ( |
|
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 |
|
[] |
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: |
|
checkPoints |
Number |
10 |
Número de pontos radiais de amostragem. Total de pontos: cruz/cruz intersecionada = |
||
|
threshold |
Number |
0.8 |
Limiar da taxa de tela branca |
||
|
whiteBoxElements |
|
[] |
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 viaevaluateApi,sendCustom,sendExceptionousendResource) 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
Acesse Application List e abra sua aplicação.
Navegue até Application Settings > SDK config.
Defina os valores de configuração desejados.
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, |
|
|
duration |
String |
Sim |
Tempo de resposta |
|
|
success |
Number |
Não |
Resultado: |
|
|
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,
},
});