Este guia explica como enviar a um servidor do Google 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 Google Analytics.
Os identificadores e parâmetros necessários para solicitações do Measurement Protocol dependem se você está enviando eventos para um fluxo da Web ou um fluxo de app.
- Para fluxos da Web (normalmente instrumentados com gtag.js ou o Gerenciador de tags do Google), use o
measurement_idno URL da solicitação e oclient_idno corpo JSON para identificar a instância do usuário. Oclient_idprecisa corresponder ao ID gerado pela tag do Google Analytics no seu site. - Para fluxos de app (instrumentados com o SDK do Firebase), use o
firebase_app_idno URL da solicitação e oapp_instance_idno corpo JSON, que são fornecidos pelo SDK do Google Analytics para Firebase.
Este guia oferece exemplos para os dois cenários.
Principais componentes da solicitação por tipo de fluxo
| Componente | Fluxo da Web (gtag.js/GTM) | Fluxo de app (Firebase) |
|---|---|---|
| Parâmetro de URL do fluxo de dados | measurement_id |
firebase_app_id |
| Parâmetro de URL da chave secreta da API | 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:
Esta 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 do projeto do Firebase.
API secret
O api_secret é usado para autenticar suas solicitações. É fundamental manter essa chave secreta.
Para criar um novo secret:
- Acesse o Google Analytics e navegue até sua conta e propriedade.
- Clique em Admin no canto inferior esquerdo.
- Em Coleta de dados e modificação, clique em Fluxos de dados.
- Selecione seu fluxo de dados da Web ou do app.
- Clique em Chaves secretas da API do Measurement Protocol.
- Clique em Criar.
- Insira um apelido para a chave secreta e clique em Criar.
Copie o valor da chave secreta.
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 de 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 detalhes sobre como encontrar ou criar estes valores):
api_secret: a chave secreta da API para autenticar a solicitação.firebase_app_id: o ID do app do Firebase do seu aplicativo.
É necessário fornecer um corpo de solicitação no formato JSON POST para o Measurement Protocol. Confira 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 do 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 tutorial_begin evento e um
join_group evento para o 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 primeiro carimbo de data/hora encontrado na lista a seguir para cada evento e propriedade do usuário na solicitação:
- O
timestamp_microsdo evento ou da propriedade do usuário. - O
timestamp_microsda solicitação. - O horário em que o Measurement Protocol recebe a solicitação.
O exemplo a seguir envia um carimbo de data/hora 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:
tutorialBeginUnixEpochTimeInMicrospara o eventotutorial_begincustomerTierUnixEpochTimeInMicrospara a propriedade do usuáriocustomer_tierrequestUnixEpochTimeInMicrospara o eventojoin_groupe a propriedade do usuárionewsletter_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 e propriedades do usuário anteriores
Os eventos e as propriedades do usuário podem ser atualizados em até 72 horas. Se o valor timestamp_micros for anterior a 72 horas, o Measurement Protocol aceitará ou rejeitará o evento ou a propriedade do usuário da seguinte maneira:
- Se o
validation_behaviornão estiver definido ou estiver definido comoRELAXED, o Measurement Protocol aceitará o evento ou a propriedade do usuário, mas substituirá o carimbo de data/hora por 72 horas atrás. - Se o
validation_behaviorestiver definido comoENFORCE_RECOMMENDATIONS, o Measurement Protocol rejeitará o evento ou a propriedade do usuário.
Os eventos enviados usando o Measurement Protocol que se destinam a ser unidos ou processados em conjunto com eventos coletados pelo SDK do Google Analytics para Firebase ou gtag.js precisam ser recebidos pelo Google Analytics em até 48 horas do carimbo de data/hora original do evento do lado do cliente. Os eventos recebidos mais tarde podem não ser processados conforme o 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:
É possível enviar no máximo 100 milhões de solicitações sem conversão por hora para cada propriedade. Uma solicitação é sem conversão se nenhum dos eventos na solicitação for um evento principal para o qual há uma conversão no Google Ads. Se você exceder esse limite, o Measurement Protocol vai ignorar silenciosamente todas as solicitações sem conversão da propriedade pelo restante da hora.
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 dos parâmetros, incluindo os valores de parâmetros de itens, precisam ter no máximo 100 caracteres para uma propriedade padrão do Google Analytics e 500 caracteres para uma propriedade do Google Analytics 360.
Esse limite não se aplica aos parâmetros
session_idesession_numberquando os valores são fornecidos pelas variáveis integradas de ID da sessão do Analytics e número da sessão do 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 aplicativos 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 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 seguintes nomes de eventos são pontos comuns de confusão:
screen_view: esse evento só é permitido para fluxos de app. Para fluxos da Web, usepage_view.ad_impression: esse evento só é permitido para fluxos de app.in_app_purchase: esse evento só é permitido para fluxos de app. Para fluxos da Web, use opurchaseevento em vez disso.
Para requisitos adicionais de cada caso de uso, consulte casos de uso comuns.