Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Enviar eventos do Measurement Protocol para o Google Analytics

Este guia explica como enviar a um servidor do Analytics os eventos de fluxos de app e Web do Measurement Protocol do Google Analytics. Assim, você pode conferir eventos do Measurement Protocol nos seus relatórios do Analytics.

Os identificadores e parâmetros necessários para solicitações do Measurement Protocol dependem de você estar enviando eventos para um fluxo da Web ou um fluxo de app.

Para fluxos da Web (normalmente instrumentados com gtag.js ou Gerenciador de tags do Google), use o measurement_id no URL da solicitação e o client_id no corpo JSON para identificar a instância do usuário. O client_id precisa corresponder ao ID gerado pela tag do Google Analytics no seu site.
Para fluxos de apps (instrumentados com o SDK do Firebase), use o firebase_app_id no URL da solicitação e o app_instance_id no corpo JSON, que são fornecidos pelo SDK do Google Analytics para Firebase.

Este guia fornece exemplos para os dois cenários.

Principais componentes de solicitação por tipo de stream

Componente	Fluxo da Web (gtag.js/GTM)	Fluxo do app (Firebase)
Parâmetro de URL da transmissão	`measurement_id`	`firebase_app_id`
Parâmetro de URL do API Secret	Obrigatório	Obrigatório
Campo do corpo JSON do ID do dispositivo	`client_id`	`app_instance_id`

Escolha a plataforma a ser retratada neste guia:

Essa guia mostra instruções para enviar eventos do seu servidor que se correlacionam com a atividade do usuário em um fluxo de app usando o SDK do Google Analytics para Firebase. Essas solicitações usam firebase_app_id e app_instance_id.

Pré-requisitos

Para enviar eventos usando o Measurement Protocol, você precisa de identificadores específicos da sua propriedade do Google Analytics ou projeto do Firebase.

API secret

O api_secret é usado para autenticar suas solicitações. É fundamental manter esse segredo em confidencialidade.

Para criar um novo secret:

Acesse o Google Analytics e navegue até sua conta e propriedade.
Clique em Administrador no canto inferior esquerdo.
Em Coleta de dados e modificação, clique em Fluxos de dados.
Selecione o fluxo de dados da Web ou de app.
Clique em Chaves secretas da API do Measurement Protocol.
Clique em Criar.
Dê um apelido para a chave e clique em Criar.
Copie o Valor do secret.
Importante:o api_secret é particular. Não exponha a chave no código do lado do cliente do seu site ou app.
- Risco de segurança:expor o api_secret permite que terceiros não autorizados enviem dados arbitrários ou de spam à sua propriedade do Google Analytics, o que pode corromper seus relatórios.
- Uso correto:o Measurement Protocol foi projetado principalmente para ambientes do lado do servidor ou confiáveis (como sistemas off-line ou comunicação de servidor para servidor).
- Acompanhamento do lado do cliente:se você precisar enviar eventos diretamente de um navegador da Web, use a tag do Google (gtag.js) ou o Gerenciador de tags do Google.
- Extensões do Chrome:para extensões do Chrome Manifest V3, não é possível carregar código remoto como gtag.js. Nesse caso, o Measurement Protocol é a abordagem recomendada. Consulte Usar o Google Analytics em extensões do Chrome.

ID do app do Firebase

O firebase_app_id identifica seu app do Firebase. Ele não é o mesmo que o app_instance_id.

Para encontrar o ID do app do Firebase:

Abra seu projeto no console do Firebase.
Clique no ícone de engrenagem de configurações ao lado de Visão geral do projeto e selecione Configurações do projeto.
Na guia Geral, acesse a seção Seus apps.
Selecione o app específico para iOS ou Android.
Copie o valor do ID do app.

Formatar a solicitação

O Measurement Protocol do Google Analytics só oferece suporte a solicitações POST HTTP.

Para enviar um evento, use este formato:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

É necessário informar o seguinte nos parâmetros de consulta do URL da solicitação (consulte Pré-requisitos para saber como encontrar ou criar esses valores):

api_secret: a chave secreta da API para autenticar a solicitação.
firebase_app_id: o ID do app Firebase do seu aplicativo.

Você precisa fornecer um corpo de solicitação no formato JSON POST body para o Measurement Protocol. Veja um exemplo:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

Você precisa fornecer app_instance_id no corpo da solicitação para identificar uma instalação exclusiva do seu app para dispositivos móveis. Isso é diferente do firebase_app_id, que identifica o app em si. Para mais informações sobre o app_instance_id e como recuperá-lo usando o SDK do Firebase, consulte a documentação de referência app_instance_id.

Embora session_start seja um nome de evento reservado, criar um novo session_id gera uma nova sessão sem a necessidade de enviar session_start. Saiba como as sessões são contabilizadas.

Testar

Confira um exemplo que você pode usar para enviar vários eventos de uma só vez. Este exemplo envia um evento tutorial_begin e um evento join_group ao servidor do Google Analytics, inclui informações geográficas usando o campo user_location e inclui informações do dispositivo usando o campo device.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

O formato de firebase_app_id é específico da plataforma. Consulte o ID do aplicativo em Objetos e arquivos de configuração do Firebase.

Substituir carimbo de data/hora

O Measurement Protocol usa o carimbo de data/hora first encontrado na seguinte lista para cada evento e propriedade do usuário na solicitação:

O timestamp_micros do evento ou da propriedade do usuário.
O timestamp_micros da solicitação.
O horário em que o Measurement Protocol recebe a solicitação.

O exemplo a seguir envia uma marca de tempo no nível da solicitação que se aplica a todos os eventos e propriedades do usuário na solicitação. Como resultado, o Measurement Protocol atribui um carimbo de data/hora de requestUnixEpochTimeInMicros aos eventos tutorial_begin e join_group e à propriedade do usuário customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

O exemplo a seguir envia um carimbo de data/hora no nível da solicitação, um carimbo de data/hora no nível do evento e um carimbo de data/hora no nível da propriedade do usuário. Como resultado, o Measurement Protocol atribui os seguintes carimbos de data/hora:

tutorialBeginUnixEpochTimeInMicros para o evento tutorial_begin
customerTierUnixEpochTimeInMicros para a propriedade do usuário customer_tier
requestUnixEpochTimeInMicros para o evento join_group e a propriedade do usuário newsletter_reader.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Comportamento de validação para eventos passados e propriedades do usuário

Os eventos e as propriedades do usuário podem ser atualizados em até 72 horas. Se o valor de timestamp_micros for anterior a 72 horas, o Measurement Protocol vai aceitar ou rejeitar o evento ou a propriedade do usuário da seguinte forma:

Se validation_behavior não estiver definido ou estiver definido como RELAXED, o Measurement Protocol vai aceitar o evento ou a propriedade do usuário, mas vai substituir o carimbo de data/hora por 72 horas atrás.
Se o validation_behavior estiver definido como ENFORCE_RECOMMENDATIONS, o Measurement Protocol vai rejeitar o evento ou a propriedade do usuário.

Os eventos enviados usando o Measurement Protocol que devem ser unidos ou processados em conjunto com eventos coletados pelo SDK do Google Analytics para Firebase ou pela gtag.js precisam ser recebidos pelo Google Analytics em até 48 horas após o carimbo de data/hora do evento original do lado do cliente. Eventos recebidos depois disso podem não ser processados como esperado, principalmente para fins como atribuição de conversão.

Limitações

As limitações a seguir são válidas para o envio de eventos do Measurement Protocol ao Google Analytics:

As solicitações podem ter no máximo 25 eventos.
Os eventos podem ter no máximo 25 parâmetros.
Os eventos podem ter até 25 propriedades do usuário.
Os nomes das propriedades do usuário podem ter, no máximo, 24 caracteres.
Os valores de propriedade do usuário precisam ter, no máximo, 36 caracteres.
Os nomes dos eventos precisam ter no máximo 40 caracteres alfanuméricos e sublinhados, além de começar com um caractere alfabético.
Os nomes dos parâmetros (incluindo os parâmetros de item) precisam ter no máximo 40 caracteres alfanuméricos e sublinhados, além de começar com um caractere alfabético.
Os valores de parâmetros, incluindo os de itens, precisam ter no máximo 100 caracteres em uma propriedade padrão do Google Analytics e 500 caracteres em uma propriedade do Google Analytics 360.

Esse limite não se aplica aos parâmetros session_id e session_number quando os valores são fornecidos pelas variáveis incorporadas ID da sessão do Google Analytics e Número da sessão do Google Analytics no Gerenciador de Tags do Google.
Os parâmetros de itens podem ter no máximo 10 parâmetros personalizados.
O corpo da postagem precisa ter menos de 130 KB.
Eventos de app relacionados ao Measurement Protocol que são enviados ao Google Analytics não adicionam usuários de apps para preencher os públicos-alvo de pesquisa no Google Ads.
Alguns nomes de eventos, parâmetros e propriedades do usuário são reservados e não podem ser usados. Consulte Nomes reservados para mais detalhes.

Nomes reservados

O Measurement Protocol tem vários nomes reservados que não podem ser usados para eventos, parâmetros ou propriedades do usuário.

Os nomes de eventos a seguir são pontos comuns de confusão:

screen_view: esse evento é permitido apenas para streams de apps. Para fluxos da Web, use page_view.
ad_impression: esse evento é permitido apenas para streams de apps.
in_app_purchase: esse evento é permitido apenas para streams de apps. Para fluxos da Web, use o evento purchase.

Para outros requisitos de cada caso de uso, consulte casos de uso comuns.