Este guia explica como enviar Fluxo da Web e do app do Measurement Protocol do Google Analytics eventos para um servidor do Google Analytics. Assim, você pode conferir os eventos do Measurement Protocol no seus relatórios do Google Analytics.
Escolha a plataforma a ser retratada neste guia:
Formatar a solicitação
O Measurement Protocol para o Google Analytics 4 só oferece suporte a solicitações POST
HTTP.
Para enviar um evento, use este formato:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data>
É necessário informar o seguinte no URL da solicitação:
api_secret
: a chave secreta da API gerada na interface do Google Analytics.Para criar uma nova chave secreta, navegue até Administrador > Fluxos de dados > escolha seu fluxo > Measurement Protocol > Criar.
measurement_id
: o ID de métricas associado a um fluxo, que fica na interface do Google Analytics, em Administrador > Fluxos de dados > escolha seu fluxo > ID de métricas.O
measurement_id
não é o ID do fluxo.
Confira a referência completa nos parâmetros de consulta.
É necessário informar o seguinte no corpo da solicitação:
client_id
: identificador exclusivo de um cliente. Ele é diferente de umapp_instance_id
do Firebase. Use gtag.js('get').
user_id
: opcional. Identificador exclusivo de um usuário. Pode conter somente UTF-8 caracteres. Para mais informações sobre esse identificador, consulte User-ID para análise multiplataforma.consent
: opcional. Saiba como definir as configurações de consentimento.timestamp_micros
: opcional. É a hora da época Unix, em microssegundos, para o eventos e propriedades do usuário na solicitação. Se não for especificado, o padrão será momento da solicitação.events
: matriz de itens de evento. Você pode incluir vários eventos em um solicitação.Para que a atividade do usuário seja mostrada em relatórios como o Relatório de tempo real, é necessário enviar
engagement_time_msec
esession_id
como parte dosparams
para umevent
. O parâmetroengagement_time_msec
precisa refletir o tempo de engajamento do evento em milissegundos.Veja um exemplo:
{
"client_id": "123456.7654321",
"events": [
{
"name": "campaign_details",
"params": {
"campaign_id": "google_1234",
"campaign": "Summer_fun",
"source": "google",
"medium": "cpc",
"term": "summer+travel",
"content": "logolink",
"session_id": "123",
"engagement_time_msec": "100"
}
}
]
}
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 um evento tutorial_begin
ao servidor do Google Analytics:
const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;
fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
method: "POST",
body: JSON.stringify({
client_id: 'XXXXXXXXXX.YYYYYYYYYY',
events: [{
name: 'tutorial_begin',
params: {},
}]
})
});
Carimbo de data/hora da substituição
O Measurement Protocol usa o primeiro carimbo de data/hora que encontra nas seguintes para cada evento da solicitação:
- O
timestamp_micros
do evento. - O
timestamp_micros
da solicitação. - A hora 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 todas
os eventos na solicitação. Como resultado, o Measurement Protocol atribui
eventos tutorial_begin
e join_group
com um carimbo de data/hora de
requestUnixEpochTimeInMicros
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin"
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
]
}
O exemplo a seguir envia um carimbo de data/hora no nível da solicitação e do evento
carimbo de data/hora. Como resultado, o Measurement Protocol atribui o tutorial_begin
um carimbo de data/hora de tutorialBeginUnixEpochTimeInMicros
, e o evento join_group
com um carimbo de data/hora de requestUnixEpochTimeInMicros
.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin",
"timestamp_micros": tutorialBeginUnixEpochTimeInMicros
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
]
}
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 valores de parâmetros de itens, precisam ter 100 caracteres ou para uma propriedade padrão do Google Analytics 4 e 500 caracteres ou menos para uma propriedade do Google Analytics 360.
- 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 4 não adicionam usuários de apps para preencher os públicos-alvo de pesquisa no Google Ads.
Para conferir os requisitos adicionais de cada caso de uso, consulte os casos de uso comuns.