API de Registro de ações: como os clientes usam eventos de perfil em seus próprios fluxos de trabalho

Gostaria de experimentar o Octo Browser com desconto?
Use o código promocional OCTOBLOG para obter 30% de desconto em qualquer assinatura. Esta oferta é válida apenas para novos usuários.

Direitos de acesso sem verificação manual

Um dos nossos clientes tem funcionários de diferentes departamentos trabalhando com perfis do Octo Browser. Cada funcionário tem seu próprio nível de acesso por meio de uma extensão personalizada usada com o Octo. Antes de conceder as permissões necessárias, o sistema precisa saber quem está trabalhando atualmente com um perfil específico.

Sem o Registro de ações, não havia como ver exatamente quem estava iniciando um perfil. O sistema de nível de acesso precisava contar com indicadores indiretos: ele podia detectar que um perfil estava sendo usado, mas não quem o estava usando.

O processo mudou quando adicionamos o evento profiles.started: user_email ao Registro de ações, para que as permissões pudessem ser aplicadas automaticamente. Essa conexão de evento → permissões tornou-se a base para a maioria das automações internas de nossos clientes.

É um mecanismo de execução contínua que responde a cada início de perfil em tempo real. Os eventos são processados em tempo real e armazenados nos próprios bancos de dados dos clientes.

Nosso cliente precisou de um desenvolvedor e cerca de uma hora para integrar o Registro de ações. O Registro de ações foi adicionado ao seu sistema de permissões existente como um módulo adicional, em vez de exigir que o processo fosse reconstruído do zero.

Contabilidade de equipe em segundos em vez de horas

Outro cliente trabalha com um grande volume de contas usando uma equipe distribuída: muitas pessoas e muitos perfis sendo processados simultaneamente. Nessa escala, é fácil perder de vista o panorama geral: quantos perfis cada pessoa está manipulando, quantos estão prontos, quantos foram atribuídos, quantos foram excluídos, e por quem e por quê.

Antes de mudar para seu próprio sistema, a equipe acompanhava tudo em planilhas. Qualquer visão geral da equipe exigia passar manualmente por tags e registros. A coleta de dados atualizados demorava de algumas horas a um dia inteiro e, no momento em que o relatório ficava pronto, algumas das informações já estavam desatualizadas.

Depois que expandimos o Registro de ações, o cliente criou seu próprio CRM que recebe eventos de perfil por meio da API e os reúne em uma única visão geral: em quantos perfis cada funcionário está trabalhando, quantos estão prontos, quantos foram atribuídos e quantos foram excluídos, com cada ação vinculada à pessoa que a realizou e quando.

Todos os dados são exibidos em um painel como contadores e status e atualizados automaticamente. Um relatório que antes levava horas para ser preparado agora pode ser gerado em 30 segundos — tudo o que você precisa fazer é abrir a seção correspondente.

O sistema foi desenvolvido sem um desenvolvedor interno, usando ferramentas de codificação de IA. Levou uma semana para criar uma versão funcional do CRM com integração de API. 

De que outras formas você pode usar o Registro de ações 

A API do Octo pode lidar com diferentes tarefas: controle operacional em tempo real, rastreamento de atividades e automação de processos internos. Em ambos os casos descritos acima, a integração levou horas ou dias em vez de meses e não exigiu uma equipe de desenvolvimento dedicada.

O princípio é o mesmo em todos os cenários: o Octo envia eventos de atividade de perfil em tempo real, enquanto o sistema do cliente decide como processá-los e armazená-los e para o que usá-los.

As necessidades reais dos clientes desempenham um papel importante no desenvolvimento do Registro de ações. Eventos como profiles.transferred, profiles.deleted e profiles.proxy_changed, entre outros, foram adicionados a pedido de equipes que já haviam construído fluxos de trabalho em torno da API, mas careciam dos dados necessários. A lista de eventos continuará a se expandir.

Além dos casos de uso descritos acima, o Registro de ações pode ser usado para outras tarefas:

• Faturamento e cálculos internos: o run_duration de profiles.stopped fornece a duração exata da sessão, útil se você cobra dos funcionários com base no tempo real de trabalho com um perfil, sem um rastreador de tempo separado.

• Auditoria de exclusão: profiles.deleted e profiles.trashed, juntamente com user_email, permitem que você descubra rapidamente quem excluiu um perfil específico e quando, sem precisar perguntar à equipe.

• Rastreamento de transferência de perfil: profiles.transferred contém ambos os lados em um único registro (o remetente e o destinatário), eliminando a necessidade de combinar dados de diferentes fontes.

• Notificações de perda de dados: profiles.force_stopped significa que um perfil em execução foi movido para um status inativo porque não foi fechado normalmente. O trabalho realizado no perfil no momento da parada forçada não é sincronizado, portanto, os colegas que estavam trabalhando com ele devem ser avisados de que suas alterações não serão salvas. Saiba mais em nossa documentação.

• Rastreamento de alteração de proxy: proxy_assigned / proxy_unassigned / proxy_changed são adequados para cenários em que sistemas externos precisam saber o proxy atual do perfil sem consultá-lo periodicamente.

Existe uma limitação importante: o Registro de ações funciona como um fluxo e armazena dados apenas pelas últimas 24 horas. Portanto, se precisar de eventos para auditoria ou análises de longo prazo, você precisará salvá-los em seu próprio sistema à medida que chegam.

Agora vamos dar uma olhada nos eventos disponíveis e como trabalhar com eles. 

Como funciona o Registro de ações no Octo Browser

• Tipo: WebSocket

• URL: wss://app.octobrowser.net/api/v2/automation/ws/action_log

• Autorização: token no cabeçalho X-Octo-Api-Token

Após a conexão, o servidor envia eventos automaticamente à medida que ocorrem — nenhuma solicitação repetida é necessária. Cada mensagem é uma StreamPage: uma matriz de eventos e uma watermark.

{
  "items": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "action": "profiles.started",
      "time": 1707053400,
      "user_email": "user@example.com",
      "object_type": "profile",
      "object_id": "a1b2c3d4e5f67890abcdef1234567890",
      "object_title": "Octo Browser Profile",
      "data": {
        "connection_data": {
          "ip": "203.0.113.42",
          "countryCode": "FR",
          "countryName": "France",
          "subdivisions": ["Île-de-France", "Paris"],
          "postalCode": "75008",
          "cityName": "Paris",
          "timezone": "Europe/Paris",
          "lat": 48.8566,
          "lon": 2.3522,
          "languages": ["fr", "en-US", "en"],
          "isp": "Example Networks Ltd",
          "connectionType": "Cable/DSL"
        }
      }
    }
  ],
  "watermark": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "time": 1707053400
  }
}

{
  "items": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "action": "profiles.started",
      "time": 1707053400,
      "user_email": "user@example.com",
      "object_type": "profile",
      "object_id": "a1b2c3d4e5f67890abcdef1234567890",
      "object_title": "Octo Browser Profile",
      "data": {
        "connection_data": {
          "ip": "203.0.113.42",
          "countryCode": "FR",
          "countryName": "France",
          "subdivisions": ["Île-de-France", "Paris"],
          "postalCode": "75008",
          "cityName": "Paris",
          "timezone": "Europe/Paris",
          "lat": 48.8566,
          "lon": 2.3522,
          "languages": ["fr", "en-US", "en"],
          "isp": "Example Networks Ltd",
          "connectionType": "Cable/DSL"
        }
      }
    }
  ],
  "watermark": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "time": 1707053400
  }
}

O Registro de ações atualmente suporta dez tipos de eventos:

• profiles.started — perfil iniciado;

• profiles.stopped — perfil interrompido;

• profiles.force_stopped — perfil interrompido à força;

• profiles.transferred — perfil transferido para outro usuário;

• profiles.trashed — perfil movido para a lixeira;

• profiles.deleted — perfil excluído;

• profiles.updated — perfil atualizado;

• profiles.proxy_assigned — proxy atribuído ao perfil;

• profiles.proxy_unassigned — proxy removido do perfil;

• profiles.proxy_changed — proxy alterado para outro. 

Para lidar com interrupções de conexão, cada mensagem contém uma watermark — o UUID e a data/hora do evento mais recente. Ao reconectar, basta passar este UUID no parâmetro after_uuid: o fluxo enviará tudo o que aconteceu durante o tempo de inatividade sem perder ou duplicar eventos. Outra opção é começar de um ponto específico no tempo usando from_timestamp. Há apenas uma limitação: os eventos são armazenados por 24 horas. Este é um fluxo ao vivo, não um arquivo.

Isso também funciona com operações em lote: se um funcionário mover 100 perfis para a lixeira de uma só vez, todos os 100 eventos aparecerão no fluxo, cada um com seu próprio object_id — nenhum será perdido ou duplicado.

Você pode saber mais sobre como o Registro de ações funciona aqui.

O que há em data — detalhamento evento por evento

Os campos dentro de data dependem da action. Aqui está o que é fornecido para cada um dos dez tipos:

profiles.stopped

A duração da sessão é fornecida no formato ISO 8601, em vez de um número de segundos:

{
  "action": "profiles.stopped",
  "data": {
    "run_duration": "PT19.627134S"
  }
}

{
  "action": "profiles.stopped",
  "data": {
    "run_duration": "PT19.627134S"
  }
}

profiles.updated

changeset não é uma lista fixa de campos, mas um campo dinâmico: contém apenas o que mudou desta vez. Por exemplo, quando várias configurações de perfil são alteradas de uma só vez, você obtém:

{
  "action": "profiles.updated",
  "data": {
    "changeset": {
      "description": {
        "old_value": "",
        "new_value": "Test action log"
      },
      "start_pages": {
        "added": ["http://google.com", "http://facebook.com"],
        "removed": []
      },
      "storage_options": {
        "added": ["serviceworkers", "localstorage"],
        "removed": []
      },
      "bookmarks": {
        "added": ["https://ebay.com", "https://amazon.com"],
        "removed": []
      },
      "launch_args": {
        "added": ["--start-maximized"],
        "removed": []
      },
      "images_load_limit": {
        "old_value": null,
        "new_value": 10240
      },
      "local_cache": {
        "old_value": false,
        "new_value": true
      },
      "fingerprint": {}
    }
  }
}

{
  "action": "profiles.updated",
  "data": {
    "changeset": {
      "description": {
        "old_value": "",
        "new_value": "Test action log"
      },
      "start_pages": {
        "added": ["http://google.com", "http://facebook.com"],
        "removed": []
      },
      "storage_options": {
        "added": ["serviceworkers", "localstorage"],
        "removed": []
      },
      "bookmarks": {
        "added": ["https://ebay.com", "https://amazon.com"],
        "removed": []
      },
      "launch_args": {
        "added": ["--start-maximized"],
        "removed": []
      },
      "images_load_limit": {
        "old_value": null,
        "new_value": 10240
      },
      "local_cache": {
        "old_value": false,
        "new_value": true
      },
      "fingerprint": {}
    }
  }
}

Você pode ver dois padrões:

• para valores individuais (description, images_load_limit, local_cache), é fornecido um par de old_value / new_value;

• para listas (start_pages, storage_options, bookmarks, launch_args), é fornecido added / removed.

A fingerprint é uma exceção: a chave aparece quando a impressão digital realmente mudou, mas é sempre um objeto vazio, sem detalhes do que mudou dentro dele. A regra geral é simples: se um campo não mudou, sua chave não aparecerá em changeset.

profiles.deleted

{
  "action": "profiles.deleted",
  "data": {
    "manual": true
  }
}

{
  "action": "profiles.deleted",
  "data": {
    "manual": true
  }
}

profiles.proxy_changed

Compara os proxies antigo e novo em um único evento:

{
  "action": "profiles.proxy_changed",
  "data": {
    "old_proxy_uuid": "370b0ce963194f68803a812dd42db4be",
    "old_proxy_title": "Netlabs GB England",
    "old_url": "socks5://user:pass@proxy.example.com:1080",
    "new_proxy_uuid": "9c51385c3e2b417d9b34fc305a49d4f6",
    "new_proxy_title": "Netlabs GB England Towcester",
    "new_url": "socks5://user:pass@proxy2.example.com:1080"
  }
}

{
  "action": "profiles.proxy_changed",
  "data": {
    "old_proxy_uuid": "370b0ce963194f68803a812dd42db4be",
    "old_proxy_title": "Netlabs GB England",
    "old_url": "socks5://user:pass@proxy.example.com:1080",
    "new_proxy_uuid": "9c51385c3e2b417d9b34fc305a49d4f6",
    "new_proxy_title": "Netlabs GB England Towcester",
    "new_url": "socks5://user:pass@proxy2.example.com:1080"
  }
}

profiles.proxy_assigned e profiles.proxy_unassigned retornam os mesmos campos, mas sem os prefixos old_ / new_ — um conjunto de campos por evento em vez de uma comparação.

O campo temporary: true é separado e significa que o proxy foi adicionado por meio de uma ação rápida (por exemplo, colando uma linha correspondente) em vez de ser atribuído normalmente por meio das configurações do perfil. 

profiles.trashed e exclusão automática

profiles.trashed vem com data vazios, assim como force_stopped. Se o perfil não for restaurado ou excluído manualmente, ele será excluído automaticamente após 72 horas. Saiba mais na documentação da lixeira. 

profiles.transferred

Um único evento contém ambos os lados:

{
  "action": "profiles.transferred",
  "user_email": "sender@example.com",
  "data": {
    "receiver": "receiver@example.com"
  }
}

{
  "action": "profiles.transferred",
  "user_email": "sender@example.com",
  "data": {
    "receiver": "receiver@example.com"
  }
}

user_email — como em qualquer outro evento, este é o e-mail do usuário que realizou a ação, ou seja, o remetente da transferência.

data.receiver — o destinatário. 

Conectando e reconectando

Você pode se conectar usando qualquer cliente que suporte WebSocket.

Usando Node.js, fica assim:

const WebSocket = require('ws');

const ws = new WebSocket('wss://app.octobrowser.net/api/v2/automation/ws/action_log', {
  headers: {
    'X-Octo-Api-Token': 'Octo API Token'
  }
});

ws.on('open', () => console.log('Connected!'));
ws.on('message', (data) => {
  const parsed = JSON.parse(data.toString());
  console.log(JSON.stringify(parsed, null, 2));
  console.log('');
});
ws.on('error', (err) => console.log('Error:', err.message));
ws.on('close', () => console.log('Connection closed'));

const WebSocket = require('ws');

const ws = new WebSocket('wss://app.octobrowser.net/api/v2/automation/ws/action_log', {
  headers: {
    'X-Octo-Api-Token': 'Octo API Token'
  }
});

ws.on('open', () => console.log('Connected!'));
ws.on('message', (data) => {
  const parsed = JSON.parse(data.toString());
  console.log(JSON.stringify(parsed, null, 2));
  console.log('');
});
ws.on('error', (err) => console.log('Error:', err.message));
ws.on('close', () => console.log('Connection closed'));

O que significa cada campo no evento recebido:

• uuid — o identificador do evento em si, não do perfil; exclusivo para cada registro, mesmo se vários eventos ocorrerem no mesmo segundo;

• action — o tipo de ação da lista acima;

• time — o horário do evento no formato Unix;

• user_email — o endereço de e-mail do usuário que realizou a ação;

• object_type — o tipo de objeto ao qual o evento se refere;

• object_id — o identificador do próprio perfil, separado do UUID do evento;

• object_title — o nome do perfil no momento do evento;

• data — detalhes que dependem da action, conforme descrito acima.

Se um perfil for interrompido, um segundo evento — profiles.stopped — será enviado com um novo uuid mas com o mesmo object_id, porque se trata do mesmo perfil. Você pode usar o object_id para vincular todos os eventos de um perfil em um único histórico do seu lado — o object_id não muda durante a vida útil do perfil, desde o início até a exclusão.

Para retomar o fluxo após a interrupção de uma conexão, basta salvar o uuid da última watermark recebida e passá-lo em after_uuid:

const WebSocket = require('ws');

const ws = new WebSocket('wss://app.octobrowser.net/api/v2/automation/ws/action_log?after_uuid=UUID', {
  headers: {
    'X-Octo-Api-Token': 'Octo API Token'
  }
});

ws.on('open', () => console.log('Connected!'));
ws.on('message', (data) => {
  const parsed = JSON.parse(data.toString());
  console.log(JSON.stringify(parsed, null, 2));
  console.log('');
});
ws.on('error', (err) => console.log('Error:', err.message));
ws.on('close', () => console.log('Connection closed'));

const WebSocket = require('ws');

const ws = new WebSocket('wss://app.octobrowser.net/api/v2/automation/ws/action_log?after_uuid=UUID', {
  headers: {
    'X-Octo-Api-Token': 'Octo API Token'
  }
});

ws.on('open', () => console.log('Connected!'));
ws.on('message', (data) => {
  const parsed = JSON.parse(data.toString());
  console.log(JSON.stringify(parsed, null, 2));
  console.log('');
});
ws.on('error', (err) => console.log('Error:', err.message));
ws.on('close', () => console.log('Connection closed'));

A conexão enviará imediatamente os eventos que ocorreram após esse UUID e continuará funcionando como um fluxo regular. Você só precisará especificar o after_uuid novamente após a próxima interrupção.

Se você não tiver uma marca d'água salva — por exemplo, após um longo tempo de inatividade quando você sabe apenas o horário aproximado da desconexão, pode começar de um horário específico usando from_timestamp (tempo Unix em segundos):

const WebSocket = require('ws');

const ws = new WebSocket('wss://app.octobrowser.net/api/v2/automation/ws/action_log?from_timestamp=TIMESTAMP', {
  headers: {
    'X-Octo-Api-Token': 'Octo API Token'
  }
});

ws.on('open', () => console.log('Connected!'));
ws.on('message', (data) => {
  const parsed = JSON.parse(data.toString());
  console.log(JSON.stringify(parsed, null, 2));
  console.log('');
});
ws.on('error', (err) => console.log('Error:', err.message));
ws.on('close', () => console.log('Connection closed'));

const WebSocket = require('ws');

const ws = new WebSocket('wss://app.octobrowser.net/api/v2/automation/ws/action_log?from_timestamp=TIMESTAMP', {
  headers: {
    'X-Octo-Api-Token': 'Octo API Token'
  }
});

ws.on('open', () => console.log('Connected!'));
ws.on('message', (data) => {
  const parsed = JSON.parse(data.toString());
  console.log(JSON.stringify(parsed, null, 2));
  console.log('');
});
ws.on('error', (err) => console.log('Error:', err.message));
ws.on('close', () => console.log('Connection closed'));

Se você está apenas começando com a automação, explicamos a API do Octo Browser em mais detalhes em um artigo separado.

Artigo relacionado

Automatizando o Octo Browser usando a API — um guia completo

Conclusão

O Registro de ações permite que você use eventos do Octo Browser como parte de sua própria infraestrutura: envie-os para um CRM, sistema de controle de acesso, plataforma de análise ou outras ferramentas internas. O Octo informa o que aconteceu com um perfil, e você decide como processar, armazenar e usar esses dados.

Se você tem um caso de uso para isso, fale conosco! Muitos dos eventos disponíveis hoje foram adicionados especificamente em resposta a tarefas do mundo real de equipes que trabalham com a API.