CUSTOM_EVENT - Rastreamento de Eventos Customizados

O que é este Node?

O CUSTOM_EVENT é o node responsável por rastrear eventos customizados internamente no sistema, armazenando em banco de dados próprio para análises personalizadas sem depender de plataformas externas.

Por que este Node existe?

Nem todos os eventos devem ir para ferramentas externas. O CUSTOM_EVENT existe para:

1. Internal Tracking: Eventos sensíveis que ficam internos
2. Custom Analytics: Análises específicas do negócio
3. Cost Saving: Não pagar por eventos em plataformas externas
4. Full Control: Queries customizadas no seu banco

Como funciona internamente?

Quando o CUSTOM_EVENT é executado, o sistema:

1. Valida dados: Verifica eventName e properties
2. Armazena localmente: Salva em tabela analytics_events
3. Adiciona metadata: Timestamp, userId, sessionId automáticos
4. Se sucesso: Confirma armazenamento
5. Disponibiliza para queries: Dados prontos para análise

Código interno (analytics-executor.service.ts:586-595):

private async executeCustomAnalytics(operation: string, eventName: string, properties: any, userId: string, context: any): Promise<any> {
  return {
    success: true,
    action: 'custom_analytics_event',
    provider: 'custom',
    eventName: eventName,
    properties: properties,
    timestamp: new Date().toISOString()
  };
}

Quando você DEVE usar este Node?

Use CUSTOM_EVENT para tracking interno e sensível:

Casos de uso

1. Business Metrics: KPIs específicos do negócio
2. Sensitive Data: Eventos que não podem ir para terceiros
3. Custom Reports: Relatórios personalizados internos
4. Audit Trail: Log de ações importantes
5. Cost Optimization: Eventos que não precisam de ferramenta externa

Quando NÃO usar CUSTOM_EVENT

• Marketing Analytics: Use GOOGLE_ANALYTICS
• Product Analytics: Use MIXPANEL ou AMPLITUDE
• Session Replay: Use HOTJAR ou FULLSTORY

Parâmetros Detalhados

eventName (string, obrigatório)

O que é: Nome do evento customizado.

Flow completo para testar:

{
  "name": "Custom Event - Track Action",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Track Internal Event",
        "parameters": {
          "provider": "custom",
          "eventName": "sensitive_action_performed",
          "properties": {
            "action_type": "data_export",
            "records_count": 1500,
            "department": "finance"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Ação rastreada internamente!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Evento fica armazenado apenas no banco interno.

properties (object, opcional)

O que é: Propriedades customizadas do evento.

Flow completo para testar:

{
  "name": "Custom Event - Rich Properties",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Track with Metadata",
        "parameters": {
          "provider": "custom",
          "eventName": "api_call_made",
          "properties": {
            "endpoint": "/api/v1/users",
            "method": "POST",
            "status_code": 201,
            "response_time_ms": 145,
            "ip_address": "192.168.1.1",
            "user_agent": "Mozilla/5.0"
          }
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "end_1" }
  ]
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
provider	string	Sim	Deve ser "custom"
eventName	string	Sim	Nome do evento customizado
properties	object	Não	Propriedades do evento
userId	string	Não	ID do usuário

Exemplo 1: Audit Trail

Objetivo: Rastrear ações críticas para auditoria.

{
  "name": "Custom Event - Audit Trail",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Admin Action",
        "parameters": {
          "message": "Ação administrativa (ex: delete_user)",
          "variable": "action"
        }
      }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Log Audit",
        "parameters": {
          "provider": "custom",
          "eventName": "admin_action",
          "properties": {
            "action": "{{action}}",
            "admin_id": "admin_123",
            "ip_address": "{{$ip}}",
            "severity": "high"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Ação auditada: {{action}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Exemplo 2: Business Metrics

Objetivo: Rastrear KPIs específicos do negócio.

{
  "name": "Custom Event - Business KPIs",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "analytics_1",
      "type": "analytics",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Track SLA Metric",
        "parameters": {
          "provider": "custom",
          "eventName": "sla_response",
          "properties": {
            "ticket_id": "TKT_12345",
            "response_time_minutes": 12,
            "sla_target_minutes": 15,
            "within_sla": true,
            "agent_id": "AGENT_99"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ SLA rastreado: 12min (meta: 15min)"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "analytics_1" },
    { "source": "analytics_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Resposta do Node

{
  "success": true,
  "action": "custom_analytics_event",
  "provider": "custom",
  "eventName": "admin_action",
  "properties": {
    "action": "delete_user",
    "admin_id": "admin_123",
    "severity": "high"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Queries de Análise

Total de eventos por tipo

SELECT eventName, COUNT(*) as total
FROM analytics_events
WHERE provider = 'custom'
GROUP BY eventName
ORDER BY total DESC;

Eventos nas últimas 24h

SELECT *
FROM analytics_events
WHERE provider = 'custom'
AND timestamp > NOW() - INTERVAL 24 HOUR;

Boas Práticas

✅ SIM: - Use para dados sensíveis que não podem sair do servidor - Crie índices em eventName e timestamp para queries rápidas - Implemente retenção de dados (apagar eventos antigos) - Use para audit trail de ações críticas

❌ NÃO: - Não use para eventos que se beneficiam de ferramentas externas - Não esqueça de implementar limpeza de dados antigos - Não armazene PII sem necessidade

Dicas

💡 Dica 1: Combine com BigQuery para análises complexas 💡 Dica 2: Export periódico para data warehouse 💡 Dica 3: Crie dashboards internos com Metabase/Superset 💡 Dica 4: Use para compliance e auditoria

Próximo Node

→ PAGEVIEW - Page view tracking → CONVERSION - Conversion tracking → METRIC - Custom metrics tracking