Best practice

Tieni presente le seguenti best practice quando utilizzi l'API Data Manager.

Invia tutti gli identificatori dell'utente

Che tu invii membri del segmento di pubblico o eventi con UserData, includi il maggior numero possibile di user_identifiers, anche inviando più identificatori dello stesso tipo.

Ad esempio, se hai più indirizzi email per un utente, includi un elemento UserIdentifier separato per ogni indirizzo email. Analogamente, se hai identificatori di tipi diversi per un utente, ad esempio indirizzi email, numeri di telefono e indirizzi, aggiungi un UserIdentifier separato per ogni identificatore, fino al numero massimo di identificatori.

Richieste di ottimizzazione

Per ridurre la probabilità di superare i limiti di richieste giornaliere, raggruppa il maggior numero possibile di elementi in ogni richiesta, fino ai limiti per richiesta.

Ad esempio, se vuoi aggiungere 10.000 membri del segmento di pubblico a un segmento di pubblico, aggiungi tutti i 10.000 membri del segmento di pubblico nell'elenco audience_members in un'unica IngestAudienceMembersRequest. L'invio in batch di tutti i 10.000 membri in un'unica richiesta è più efficiente dell'invio di una richiesta separata per aggiungere ogni membro del segmento di pubblico.

Invia richieste in parallelo

Per ridurre il tempo complessivo necessario per l'importazione dei dati, invia richieste in parallelo all'IngestionService. Ti consigliamo di inviare fino a 10 richieste contemporaneamente per ridurre la probabilità di superare il limite di richieste al minuto.

Puoi inviare richieste in parallelo anche se hanno lo stesso destinations.

Convalida i dati lato client

L'API Data Manager utilizza un modello di fail-fast. Se un record in una richiesta non supera la convalida sincrona, l'intera richiesta non va a buon fine e nessuno dei record viene elaborato. Inoltre, l'API convalida le richieste in livelli sequenziali, pertanto la correzione di un errore potrebbe rivelare un errore di un livello di convalida successivo.

Per evitare round trip ripetuti e richieste rifiutate, convalida e sanitizza i dati prima di inviarli:

• Rimuovi i valori vuoti prima dell'hashing: controlla i campi come email_address e phone_number per verificare la presenza di stringhe vuote o contenenti solo spazi vuoti prima di calcolare gli hash SHA-256. L'hashing di una stringa vuota produce un hash valido che supera i controlli di sintassi, ma danneggia i tassi di corrispondenza.

• Elimina gli oggetti composti incompleti: assicurati che gli oggetti composti abbiano tutti i campi obbligatori prima di aggiungerli a un record. Ad esempio, se in un oggetto AddressInfo manca uno dei quattro campi obbligatori (given_name, family_name, region_code o postal_code), elimina l'intero identificatore address per evitare errori REQUIRED_FIELD_MISSING.

• Convalida i campi di codifica e di testo non crittografato: verifica che i campi con hashing corrispondano all'algoritmo encoding dichiarato anziché inviare testo non crittografato non elaborato e assicurati che i campi che devono rimanere in testo non crittografato (come mobile_ids) non siano sottoposti ad hashing.

• Filtra i timestamp fuori intervallo: assicurati che i timestamp non siano nel futuro o più vecchi della finestra temporale di conversione della destinazione.

  Se invii richieste utilizzando JSON, assicurati che le stringhe di timestamp utilizzino il formato RFC 3339 con un offset del fuso orario.

• Pulisci i numeri di telefono: verifica che i numeri di telefono includano un codice paese e utilizzino il formato E.164 prima dell'hashing.

• Elimina i record vuoti o di dimensioni eccessive: limita user_identifiers al limite per record (10 identificatori), elimina i parametri personalizzati vuoti e ometti tutti i record che non contengono identificatori validi.

• Verifica i requisiti dei casi d'uso: assicurati che ogni evento includa tutti i campi obbligatori per la destinazione e il caso d'uso (ad esempio transaction_id per le conversioni online di Google Ads). Per un elenco completo dei campi obbligatori per caso d'uso, consulta la guida all'invio di eventi per la tua destinazione nella panoramica degli eventi.

• Utilizza validateOnly per testare le richieste: invia richieste con validateOnly impostato su true per rilevare errori di fail-fast senza importare o rimuovere dati. Una richiesta di sola convalida riuscita non garantisce che non si verifichino errori durante l'elaborazione asincrona, quindi continua a controllare lo stato della richiesta e la diagnostica dopo aver inviato una richiesta regolare.

Per regole dettagliate di normalizzazione e hashing, consulta Formattare i dati utente.

Controlla lo stato della richiesta e la diagnostica

Acquisisci e raccogli l'elemento request_id da ogni IngestAudienceMembersResponse o IngestEventsResponse e utilizza gli ID richiesta per controllare lo stato e la diagnostica della richiesta.

Monitora e genera avvisi sulle quote

Per evitare rifiuti imprevisti delle richieste, configura gli avvisi quota e il monitoraggio nella console Google Cloud. Il monitoraggio dell'utilizzo della quota ti aiuta a monitorare i pattern di consumo e a ottimizzare il raggruppamento delle richieste prima che l'applicazione raggiunga i limiti giornalieri o al minuto.

Distribuzione in produzione

Quando passi dai test locali ai workload di produzione, utilizza le Credenziali predefinite dell'applicazione con un service account collegato o la federazione delle identità per i workload per eseguire l'autenticazione in modo non interattivo e sicuro.

Per informazioni dettagliate sulla configurazione dell'autenticazione per diversi ambienti di produzione, consulta Esegui il deployment in produzione.