Práticas recomendadas

Lembre-se das práticas recomendadas a seguir ao usar a API Data Manager.

Enviar todos os identificadores de usuário

Ao enviar membros do público-alvo ou eventos com UserData, inclua o máximo de user_identifiers possível, incluindo vários identificadores do mesmo tipo.

Por exemplo, se você tiver vários endereços de e-mail para um usuário, inclua um UserIdentifier separado para cada endereço de e-mail. Da mesma forma, se você tiver identificadores de tipos diferentes para um usuário, como endereços de e-mail, números de telefone e endereços, adicione um UserIdentifier separado para cada identificador, até o limite de identificadores.

Otimizar solicitações

Para reduzir a probabilidade de exceder os limites diários de solicitações, agrupe o máximo de itens possível em cada solicitação, até os limites por solicitação.

Por exemplo, se você quiser adicionar 10.000 membros do público-alvo a um público-alvo, adicione todos os 10.000 membros do público-alvo na lista audience_members em um IngestAudienceMembersRequest. Agrupar todos os 10.000 membros em uma única solicitação é mais eficiente do que enviar uma solicitação separada para adicionar cada membro do público-alvo.

Enviar solicitações simultâneas

Para reduzir o tempo total necessário para ingerir dados, envie solicitações simultâneas para o IngestionService. Recomendamos enviar até 10 solicitações simultaneamente para reduzir a probabilidade de exceder o limite de solicitações por minuto.

É possível enviar solicitações simultâneas, mesmo que elas tenham o mesmo destinations.

Validar dados no lado do cliente

A API Data Manager usa um modelo de falha rápida. Se algum registro em uma solicitação falhar na validação síncrona, toda a solicitação falhará e nenhum dos registros será processado. Além disso, a API valida as solicitações em camadas sequenciais. Portanto, corrigir um erro pode revelar um erro de uma camada de validação subsequente.

Para evitar idas e voltas repetidas e solicitações rejeitadas, valide e limpe seus dados antes de enviá-los:

• Remova valores vazios antes de gerar o hash: verifique se campos como email_address e phone_number têm strings vazias ou apenas com espaços em branco antes de calcular hashes SHA-256. A geração de hash de uma string vazia produz um hash válido que passa nas verificações de sintaxe, mas prejudica as taxas de correspondência.

• Descartar objetos compostos incompletos: verifique se os objetos compostos têm todos os campos obrigatórios antes de adicioná-los a um registro. Por exemplo, se um objeto AddressInfo não tiver um dos quatro campos obrigatórios (given_name, family_name, region_code ou postal_code), remova todo o identificador address para evitar erros REQUIRED_FIELD_MISSING.

• Valide os campos de codificação e texto simples: verifique se os campos com hash correspondem ao encoding declarado em vez de enviar texto simples bruto e garanta que os campos que precisam permanecer em texto simples (como mobile_ids) não tenham hash.

• Filtrar carimbos de data/hora fora dos limites: verifique se os carimbos de data/hora não estão no futuro ou se não são mais antigos do que a janela de lookback de conversão do destino.

  Se você enviar solicitações usando JSON, verifique se as strings de carimbo de data/hora usam o formato RFC 3339 com um deslocamento de fuso horário.

• Limpar números de telefone: verifique se os números de telefone incluem um código de país e usam o formato E.164 antes de gerar o hash.

• Remover registros vazios ou muito grandes: limite user_identifiers ao limite por registro (10 identificadores), remova parâmetros personalizados vazios e omita qualquer registro que não contenha identificadores válidos.

• Verifique os requisitos do caso de uso: confira se cada evento inclui todos os campos obrigatórios para o destino e o caso de uso (como transaction_id para conversões on-line do Google Ads). Para uma lista completa de campos obrigatórios por caso de uso, consulte o guia de envio de eventos para seu destino na Visão geral de eventos.

• Use validateOnly para testar solicitações: envie solicitações com validateOnly definido como true para detectar erros de falha rápida sem ingerir ou remover dados. Uma solicitação de validação bem-sucedida não garante que não haverá erros durante o processamento assíncrono. Portanto, continue verificando o status e os diagnósticos da solicitação depois de enviar uma solicitação normal.

Para regras detalhadas de normalização e hash, consulte Formatar dados do usuário.

Verificar o status e os diagnósticos da solicitação

Capture e colete o request_id de cada IngestAudienceMembersResponse ou IngestEventsResponse e use os IDs de solicitação para verificar o status e o diagnóstico da solicitação.

Monitorar e alertar sobre cotas

Para evitar rejeições inesperadas de solicitações, configure alertas de cota e monitoramento no console do Google Cloud. O monitoramento do uso de cotas ajuda a acompanhar os padrões de consumo e otimizar o lote de solicitações antes que o aplicativo atinja os limites diários ou por minuto.

Implantar para a produção

Ao migrar de testes locais para cargas de trabalho de produção, use o Application Default Credentials com uma conta de serviço anexada ou a federação de identidade da carga de trabalho para autenticar de forma não interativa e segura.

Para detalhes sobre como configurar a autenticação para diferentes ambientes de produção, consulte Implantar na produção.