();
}
}
}
```
### Java
```java
// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.ads.datamanager.samples;
import com.beust.jcommander.Parameter;
import com.google.ads.datamanager.samples.common.BaseParamsConfig;
import com.google.ads.datamanager.util.UserDataFormatter;
import com.google.ads.datamanager.util.UserDataFormatter.Encoding;
import com.google.ads.datamanager.v1.AdIdentifiers;
import com.google.ads.datamanager.v1.Consent;
import com.google.ads.datamanager.v1.ConsentStatus;
import com.google.ads.datamanager.v1.Destination;
import com.google.ads.datamanager.v1.Event;
import com.google.ads.datamanager.v1.EventSource;
import com.google.ads.datamanager.v1.IngestEventsRequest;
import com.google.ads.datamanager.v1.IngestEventsResponse;
import com.google.ads.datamanager.v1.IngestionServiceClient;
import com.google.ads.datamanager.v1.ProductAccount;
import com.google.ads.datamanager.v1.ProductAccount.AccountType;
import com.google.ads.datamanager.v1.UserData;
import com.google.ads.datamanager.v1.UserIdentifier;
import com.google.common.base.Strings;
import com.google.common.collect.Lists;
import com.google.common.reflect.TypeToken;
import com.google.gson.GsonBuilder;
import com.google.protobuf.util.Timestamps;
import java.io.BufferedReader;
import java.io.IOException;
import java.lang.reflect.Type;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.text.ParseException;
import java.util.ArrayList;
import java.util.List;
import java.util.logging.Logger;
/**
* Sends an {@link IngestEventsRequest} without using encryption.
*
* Event data is read from a data file. See the {@code events_1.json} file in the {@code
* resources/sampledata} directory for a sample file.
*/
public class IngestEvents {
private static final Logger LOGGER = Logger.getLogger(IngestEvents.class.getName());
/** The maximum number of events allowed per request. */
private static final int MAX_EVENTS_PER_REQUEST = 2_000;
private static final class ParamsConfig extends BaseParamsConfig {
@Parameter(
names = "--operatingAccountType",
required = true,
description = "Account type of the operating account")
AccountType operatingAccountType;
@Parameter(
names = "--operatingAccountId",
required = true,
description = "ID of the operating account")
String operatingAccountId;
@Parameter(
names = "--loginAccountType",
required = false,
description = "Account type of the login account")
AccountType loginAccountType;
@Parameter(
names = "--loginAccountId",
required = false,
description = "ID of the login account")
String loginAccountId;
@Parameter(
names = "--linkedAccountType",
required = false,
description = "Account type of the linked account")
AccountType linkedAccountType;
@Parameter(
names = "--linkedAccountId",
required = false,
description = "ID of the linked account")
String linkedAccountId;
@Parameter(
names = "--conversionActionId",
required = true,
description = "ID of the conversion action")
String conversionActionId;
@Parameter(
names = "--jsonFile",
required = true,
description = "JSON file containing user data to ingest")
String jsonFile;
@Parameter(
names = "--validateOnly",
required = false,
arity = 1,
description = "Whether to enable validateOnly on the request")
boolean validateOnly = true;
}
public static void main(String[] args) throws IOException {
ParamsConfig paramsConfig = new ParamsConfig().parseOrExit(args);
if ((paramsConfig.loginAccountId == null) != (paramsConfig.loginAccountType == null)) {
throw new IllegalArgumentException(
"Must specify either both or neither of login account ID and login account type");
}
if ((paramsConfig.linkedAccountId == null) != (paramsConfig.linkedAccountType == null)) {
throw new IllegalArgumentException(
"Must specify either both or neither of linked account ID and linked account type");
}
new IngestEvents().runExample(paramsConfig);
}
/**
* Runs the example. This sample assumes that the login and operating account are the same.
*
* @param params the parameters for the example
*/
private void runExample(ParamsConfig params) throws IOException {
// Reads event data from the JSON file.
List eventRecords = readEventData(params.jsonFile);
// Gets an instance of the UserDataFormatter for normalizing and formatting the data.
UserDataFormatter userDataFormatter = UserDataFormatter.create();
// Builds the events collection for the request.
List events = new ArrayList<>();
for (EventRecord eventRecord : eventRecords) {
Event.Builder eventBuilder = Event.newBuilder();
try {
eventBuilder.setEventTimestamp(Timestamps.parse(eventRecord.timestamp));
} catch (ParseException pe) {
LOGGER.warning(
() ->
String.format("Skipping event with invalid timestamp: %s", eventRecord.timestamp));
continue;
}
if (Strings.isNullOrEmpty(eventRecord.transactionId)) {
LOGGER.warning("Skipping event with no transaction ID");
continue;
}
eventBuilder.setTransactionId(eventRecord.transactionId);
if (!Strings.isNullOrEmpty(eventRecord.eventSource)) {
try {
eventBuilder.setEventSource(EventSource.valueOf(eventRecord.eventSource));
} catch (IllegalArgumentException iae) {
LOGGER.warning("Skipping event with invalid event source: " + eventRecord.eventSource);
continue;
}
}
if (!Strings.isNullOrEmpty(eventRecord.gclid)) {
eventBuilder.setAdIdentifiers(AdIdentifiers.newBuilder().setGclid(eventRecord.gclid));
}
if (!Strings.isNullOrEmpty(eventRecord.currency)) {
eventBuilder.setCurrency(eventRecord.currency);
}
if (eventRecord.value != null) {
eventBuilder.setConversionValue(eventRecord.value);
}
UserData.Builder userDataBuilder = UserData.newBuilder();
// Adds a UserIdentifier for each valid email address for the eventRecord.
if (eventRecord.emails != null) {
for (String email : eventRecord.emails) {
String preparedEmail;
try {
preparedEmail = userDataFormatter.processEmailAddress(email, Encoding.HEX);
} catch (IllegalArgumentException iae) {
// Skips invalid input.
continue;
}
// Sets the email address identifier to the encoded email hash.
userDataBuilder.addUserIdentifiers(
UserIdentifier.newBuilder().setEmailAddress(preparedEmail));
}
}
// Adds a UserIdentifier for each valid phone number for the eventRecord.
if (eventRecord.phoneNumbers != null) {
for (String phoneNumber : eventRecord.phoneNumbers) {
String preparedPhoneNumber;
try {
preparedPhoneNumber = userDataFormatter.processPhoneNumber(phoneNumber, Encoding.HEX);
} catch (IllegalArgumentException iae) {
// Skips invalid input.
continue;
}
// Sets the phone number identifier to the encoded phone number hash.
userDataBuilder.addUserIdentifiers(
UserIdentifier.newBuilder().setPhoneNumber(preparedPhoneNumber));
}
}
if (userDataBuilder.getUserIdentifiersCount() > 0) {
eventBuilder.setUserData(userDataBuilder);
}
events.add(eventBuilder.build());
}
// Builds the Destination for the request.
Destination.Builder destinationBuilder =
Destination.newBuilder()
.setOperatingAccount(
ProductAccount.newBuilder()
.setAccountType(params.operatingAccountType)
.setAccountId(params.operatingAccountId))
.setProductDestinationId(params.conversionActionId);
if (params.loginAccountType != null && params.loginAccountId != null) {
destinationBuilder.setLoginAccount(
ProductAccount.newBuilder()
.setAccountType(params.loginAccountType)
.setAccountId(params.loginAccountId));
}
if (params.linkedAccountType != null && params.linkedAccountId != null) {
destinationBuilder.setLinkedAccount(
ProductAccount.newBuilder()
.setAccountType(params.linkedAccountType)
.setAccountId(params.linkedAccountId));
}
try (IngestionServiceClient ingestionServiceClient = IngestionServiceClient.create()) {
int requestCount = 0;
// Batches requests to send up to the maximum number of events per request.
for (List eventsBatch : Lists.partition(events, MAX_EVENTS_PER_REQUEST)) {
requestCount++;
// Builds the request.
IngestEventsRequest request =
IngestEventsRequest.newBuilder()
.addDestinations(destinationBuilder)
// Adds events from the current batch.
.addAllEvents(eventsBatch)
.setConsent(
Consent.newBuilder()
.setAdPersonalization(ConsentStatus.CONSENT_GRANTED)
.setAdUserData(ConsentStatus.CONSENT_GRANTED))
// Sets validate_only. If true, then the Data Manager API only validates the request
// but doesn't apply changes.
.setValidateOnly(params.validateOnly)
// Sets encoding to match the encoding used.
.setEncoding(com.google.ads.datamanager.v1.Encoding.HEX)
.build();
LOGGER.info(() -> String.format("Request:%n%s", request));
IngestEventsResponse response = ingestionServiceClient.ingestEvents(request);
LOGGER.info(String.format("Response for request #:%n%s", requestCount, response));
}
LOGGER.info("# of requests sent: " + requestCount);
}
}
/** Data object for a single row of input data. */
@SuppressWarnings("unused")
private static class EventRecord {
private List emails;
private List phoneNumbers;
private String timestamp;
private String transactionId;
private String eventSource;
private Double value;
private String currency;
private String gclid;
}
/** Reads the data file and parses each line into a {@link EventRecord} object. */
private List readEventData(String jsonFile) throws IOException {
try (BufferedReader jsonReader =
Files.newBufferedReader(Paths.get(jsonFile), StandardCharsets.UTF_8)) {
// Define the type for Gson to deserialize into (List of EventRecord objects)
Type recordListType = new TypeToken>() {}.getType();
// Parse the JSON string from the file into a List of EventRecord objects
return new GsonBuilder().create().fromJson(jsonReader, recordListType);
}
}
}
```
### Node
```javascript
#!/usr/bin/env node
// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
'use strict';
import {IngestionServiceClient} from '@google-ads/datamanager';
import {protos} from '@google-ads/datamanager';
const {
Event: DataManagerEvent,
Destination,
Encoding: DataManagerEncoding,
EventSource,
Consent,
ConsentStatus,
IngestEventsRequest,
ProductAccount,
UserData,
UserIdentifier,
} = protos.google.ads.datamanager.v1;
import {UserDataFormatter, Encoding} from '@google-ads/datamanager-util';
import * as fs from 'fs';
import * as yargs from 'yargs';
const MAX_EVENTS_PER_REQUEST = 10000;
interface Arguments {
operating_account_type: string;
operating_account_id: string;
conversion_action_id: string;
json_file: string;
validate_only: boolean;
login_account_type?: string;
login_account_id?: string;
linked_account_type?: string;
linked_account_id?: string;
[x: string]: unknown;
}
interface EventRow {
timestamp: string;
transactionId: string;
eventSource?: string;
gclid?: string;
currency?: string;
value?: number;
emails?: string[];
phoneNumbers?: string[];
}
/**
* The main function for the IngestEvents sample.
*/
async function main() {
const argv: Arguments = yargs
.option('operating_account_type', {
describe: 'The account type of the operating account.',
type: 'string',
required: true,
})
.option('operating_account_id', {
describe: 'The ID of the operating account.',
type: 'string',
required: true,
})
.option('conversion_action_id', {
describe: 'The ID of the conversion action.',
type: 'string',
required: true,
})
.option('json_file', {
describe: 'JSON file containing user data to ingest.',
type: 'string',
required: true,
})
.option('validate_only', {
describe: 'Whether to enable validate_only on the request.',
type: 'boolean',
default: true,
})
.option('login_account_type', {
describe: 'The account type of the login account.',
type: 'string',
})
.option('login_account_id', {
describe: 'The ID of the login account.',
type: 'string',
})
.option('linked_account_type', {
describe: 'The account type of the linked account.',
type: 'string',
})
.option('linked_account_id', {
describe: 'The ID of the linked account.',
type: 'string',
})
.option('config', {
describe: 'Path to a JSON file with arguments.',
type: 'string',
})
.config('config')
.check((args: Arguments) => {
if (
(args.login_account_type && !args.login_account_id) ||
(!args.login_account_type && args.login_account_id)
) {
throw new Error(
'Must specify either both or neither of login account type ' +
'and login account ID',
);
}
if (
(args.linked_account_type && !args.linked_account_id) ||
(!args.linked_account_type && args.linked_account_id)
) {
throw new Error(
'Must specify either both or neither of linked account type ' +
'and linked account ID',
);
}
return true;
})
.parseSync();
// Reads event data from the JSON file.
const eventRows: EventRow[] = readEventDataFile(argv.json_file);
// Builds the events collection for the request.
const events = [];
const formatter = new UserDataFormatter();
for (const eventRow of eventRows) {
const event = DataManagerEvent.create();
try {
const date = new Date(eventRow.timestamp);
event.eventTimestamp = {
seconds: Math.floor(date.getTime() / 1000),
nanos: (date.getTime() % 1000) * 1e6,
};
} catch (e) {
console.warn(
`Invalid timestamp format: ${eventRow.timestamp}. Skipping row.`,
);
continue;
}
if (!eventRow.transactionId) {
console.warn('Skipping event with no transaction ID');
continue;
}
event.transactionId = eventRow.transactionId;
if (eventRow.eventSource) {
const eventSourceEnumValue: number | undefined =
EventSource[eventRow.eventSource as keyof typeof EventSource];
if (eventSourceEnumValue === undefined) {
console.warn(
`Skipping event with invalid event_source: ${eventRow.eventSource}`,
);
continue;
}
event.eventSource = eventSourceEnumValue;
}
if (eventRow.gclid) {
event.adIdentifiers = {gclid: eventRow.gclid};
}
if (eventRow.currency) {
event.currency = eventRow.currency;
}
if (eventRow.value) {
event.conversionValue = eventRow.value;
}
const userData = UserData.create();
// Adds a UserIdentifier for each valid email address for the eventRecord.
if (eventRow.emails) {
for (const email of eventRow.emails) {
try {
const processedEmail = formatter.processEmailAddress(
email,
Encoding.HEX,
);
userData.userIdentifiers.push(
UserIdentifier.create({emailAddress: processedEmail}),
);
} catch (e) {
console.warn(`Invalid email address: ${email}. Skipping.`);
}
}
}
// Adds a UserIdentifier for each valid phone number for the eventRecord.
if (eventRow.phoneNumbers) {
for (const phoneNumber of eventRow.phoneNumbers) {
try {
const processedPhone = formatter.processPhoneNumber(
phoneNumber,
Encoding.HEX,
);
userData.userIdentifiers.push(
UserIdentifier.create({phoneNumber: processedPhone}),
);
} catch (e) {
console.warn(`Invalid phone: ${phoneNumber}. Skipping.`);
}
}
}
if (userData.userIdentifiers.length > 0) {
event.userData = userData;
}
events.push(event);
}
// Sets up the Destination.
const operatingAccountType = convertToAccountType(
argv.operating_account_type,
'operating_account_type',
);
const destination = Destination.create({
operatingAccount: ProductAccount.create({
accountType: operatingAccountType,
accountId: argv.operating_account_id,
}),
productDestinationId: argv.conversion_action_id,
});
// The login account is optional.
if (argv.login_account_type) {
const loginAccountType = convertToAccountType(
argv.login_account_type,
'login_account_type',
);
destination.loginAccount = ProductAccount.create({
accountType: loginAccountType,
accountId: argv.login_account_id,
});
}
// The linked account is optional.
if (argv.linked_account_type) {
const linkedAccountType = convertToAccountType(
argv.linked_account_type,
'linked_account_type',
);
destination.linkedAccount = ProductAccount.create({
accountType: linkedAccountType,
accountId: argv.linked_account_id,
});
}
const client = new IngestionServiceClient();
let requestCount = 0;
// Batches requests to send up to the maximum number of events per request.
for (let i = 0; i < events.length; i += MAX_EVENTS_PER_REQUEST) {
requestCount++;
const eventsBatch = events.slice(i, i + MAX_EVENTS_PER_REQUEST);
// Builds the request.
const request = IngestEventsRequest.create({
destinations: [destination],
// Adds events from the current batch.
events: eventsBatch,
consent: Consent.create({
adUserData: ConsentStatus.CONSENT_GRANTED,
adPersonalization: ConsentStatus.CONSENT_GRANTED,
}),
// Sets encoding to match the encoding used.
encoding: DataManagerEncoding.HEX,
// Sets validate_only. If true, then the Data Manager API only validates the request
validateOnly: argv.validate_only,
});
const [response] = await client.ingestEvents(request);
console.log(`Response for request #${requestCount}:\n`, response);
if (response.fieldWarnings && response.fieldWarnings.length > 0) {
console.warn(
'Request ingested successfully, but field warnings were returned. ' +
'Review warning details and update your implementation as needed.',
);
}
}
console.log(`# of requests sent: ${requestCount}`);
}
/**
* Reads the event data from the given JSON file.
* @param {string} jsonFile The path to the JSON file.
* @return {EventRow[]} An array of event data.
*/
function readEventDataFile(jsonFile: string): EventRow[] {
const fileContent = fs.readFileSync(jsonFile, 'utf8');
return JSON.parse(fileContent);
}
/**
* Validates that a given string is an enum value for the AccountType enum, and
* if validation passes, returns the AccountType enum value.
* @param proposedValue the name of an AccountType enum value
* @param paramName the name of the parameter to use in the error message if validation fails
* @returns {protos.google.ads.datamanager.v1.ProductAccount.AccountType} The corresponding enum value.
* @throws {Error} If the string is not an AccountType enum value.
*/
function convertToAccountType(
proposedValue: string,
paramName: string,
): protos.google.ads.datamanager.v1.ProductAccount.AccountType {
const AccountType = ProductAccount.AccountType;
const accountTypeEnumNames = Object.keys(AccountType).filter(key =>
isNaN(Number(key)),
);
if (!accountTypeEnumNames.includes(proposedValue)) {
throw new Error(`Invalid ${paramName}: ${proposedValue}`);
}
return AccountType[proposedValue as keyof typeof AccountType];
}
if (require.main === module) {
main().catch(console.error);
}
```
### PHP
```php
fromDateTime($dateTime);
$event->setEventTimestamp($timestamp);
} catch (\Exception $e) {
error_log(sprintf('Skipping event with invalid timestamp: %s', $eventRecord['timestamp']));
continue;
}
if (empty($eventRecord['transactionId'])) {
error_log('Skipping event with no transaction ID');
continue;
}
$event->setTransactionId($eventRecord['transactionId']);
if (!empty($eventRecord['eventSource'])) {
try {
$event->setEventSource(EventSource::value($eventRecord['eventSource']));
} catch (\UnexpectedValueException $e) {
error_log('Skipping event with invalid event source: ' . $eventRecord['eventSource']);
continue;
}
}
if (!empty($eventRecord['gclid'])) {
$event->setAdIdentifiers((new AdIdentifiers())->setGclid($eventRecord['gclid']));
}
if (!empty($eventRecord['currency'])) {
$event->setCurrency($eventRecord['currency']);
}
if (isset($eventRecord['value'])) {
$event->setConversionValue($eventRecord['value']);
}
$userData = new UserData();
$identifiers = [];
if (!empty($eventRecord['emails'])) {
foreach ($eventRecord['emails'] as $email) {
try {
$preparedEmail = $formatter->processEmailAddress($email, Encoding::Hex);
$identifiers[] = (new UserIdentifier())->setEmailAddress($preparedEmail);
} catch (\InvalidArgumentException $e) {
// Skips invalid input.
error_log(sprintf('Skipping invalid email: %s', $e->getMessage()));
continue;
}
}
}
if (!empty($eventRecord['phoneNumbers'])) {
foreach ($eventRecord['phoneNumbers'] as $phoneNumber) {
try {
$preparedPhoneNumber = $formatter->processPhoneNumber($phoneNumber, Encoding::Hex);
$identifiers[] = (new UserIdentifier())->setPhoneNumber($preparedPhoneNumber);
} catch (\InvalidArgumentException $e) {
// Skips invalid input.
error_log(sprintf('Skipping invalid phone number: %s', $e->getMessage()));
continue;
}
}
}
if (!empty($identifiers)) {
$userData->setUserIdentifiers($identifiers);
$event->setUserData($userData);
}
$events[] = $event;
}
// Builds the destination for the request.
$destination = (new Destination())
->setOperatingAccount((new ProductAccount())
->setAccountType($operatingAccountType)
->setAccountId($operatingAccountId))
->setProductDestinationId($conversionActionId);
if ($loginAccountType !== null && $loginAccountId !== null) {
$destination->setLoginAccount((new ProductAccount())
->setAccountType($loginAccountType)
->setAccountId($loginAccountId));
}
if ($linkedAccountType !== null && $linkedAccountId !== null) {
$destination->setLinkedAccount((new ProductAccount())
->setAccountType($linkedAccountType)
->setAccountId($linkedAccountId));
}
$client = new IngestionServiceClient();
try {
$requestCount = 0;
// Batches requests to send up to the maximum number of events per request.
foreach (array_chunk($events, MAX_EVENTS_PER_REQUEST) as $eventsBatch) {
$requestCount++;
// Builds the request.
$request = (new IngestEventsRequest())
->setDestinations([$destination])
->setEvents($eventsBatch)
->setConsent((new Consent())
->setAdUserData(ConsentStatus::CONSENT_GRANTED)
->setAdPersonalization(ConsentStatus::CONSENT_GRANTED)
)
->setValidateOnly($validateOnly)
->setEncoding(DataManagerEncoding::HEX);
echo "Request:\n" . json_encode(json_decode($request->serializeToJsonString()), JSON_PRETTY_PRINT) . "\n";
$response = $client->ingestEvents($request);
echo "Response for request #{$requestCount}:\n" . json_encode(json_decode($response->serializeToJsonString()), JSON_PRETTY_PRINT) . "\n";
if (count($response->getFieldWarnings()) > 0) {
echo 'Request ingested successfully, but field warnings were returned. '
. "Review warning details and update your implementation as needed.\n";
}
}
echo "# of requests sent: {$requestCount}\n";
} catch (ApiException $e) {
echo 'Error sending request: ' . $e->getMessage() . "\n";
} finally {
$client->close();
}
}
// Command-line argument parsing
$options = getopt(
'',
[
'operating_account_type:',
'operating_account_id:',
'login_account_type::',
'login_account_id::',
'linked_account_type::',
'linked_account_id::',
'conversion_action_id:',
'json_file:',
'validate_only::'
]
);
$operatingAccountType = $options['operating_account_type'] ?? null;
$operatingAccountId = $options['operating_account_id'] ?? null;
$conversionActionId = $options['conversion_action_id'] ?? null;
$jsonFile = $options['json_file'] ?? null;
// Only validates requests by default.
$validateOnly = true;
if (array_key_exists('validate_only', $options)) {
$value = $options['validate_only'];
// `getopt` with `::` returns boolean `false` if the option is passed without a value.
if ($value === false || !in_array($value, ['true', 'false'], true)) {
echo "Error: --validate_only requires a value of 'true' or 'false'.\n";
exit(1);
}
$validateOnly = ($value === 'true');
}
if (empty($operatingAccountType) || empty($operatingAccountId) || empty($conversionActionId) || empty($jsonFile)) {
echo 'Usage: php ingest_events.php ' .
'--operating_account_type= ' .
'--operating_account_id= ' .
'--conversion_action_id= ' .
"--json_file=\n" .
'Optional: --login_account_type= --login_account_id= ' .
'--linked_account_type= --linked_account_id= ' .
"--validate_only=\n";
exit(1);
}
// Converts the operating account type string to an AccountType enum.
$parsedOperatingAccountType = AccountType::value($operatingAccountType);
if (isset($options['login_account_type']) != isset($options['login_account_id'])) {
throw new \InvalidArgumentException(
'Must specify either both or neither of login account type and login account ID'
);
}
$parsedLoginAccountType = null;
if (isset($options['login_account_type'])) {
// Converts the login account type string to an AccountType enum.
$parsedLoginAccountType = AccountType::value($options['login_account_type']);
}
if (isset($options['linked_account_type']) != isset($options['linked_account_id'])) {
throw new \InvalidArgumentException(
'Must specify either both or neither of linked account type and linked account ID'
);
}
$parsedLinkedAccountType = null;
if (isset($options['linked_account_type'])) {
// Converts the linked account type string to an AccountType enum.
$parsedLinkedAccountType = AccountType::value($options['linked_account_type']);
}
main(
$parsedOperatingAccountType,
$operatingAccountId,
$conversionActionId,
$jsonFile,
$validateOnly,
$parsedLoginAccountType,
$options['login_account_id'] ?? null,
$parsedLinkedAccountType,
$options['linked_account_id'] ?? null
);
```
### Python
```python
#!/usr/bin/env python
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Sample of sending an IngestEventsRequest without encryption."""
import argparse
import json
import logging
from typing import Any, Dict, List, Optional
from google.ads import datamanager_v1
from google.ads.datamanager_util import Formatter
from google.ads.datamanager_util.format import Encoding
from google.protobuf.timestamp_pb2 import Timestamp
_logger = logging.getLogger(__name__)
# The maximum number of events allowed per request.
_MAX_EVENTS_PER_REQUEST = 10_000
def main(
operating_account_type: datamanager_v1.ProductAccount.AccountType,
operating_account_id: str,
conversion_action_id: str,
json_file: str,
validate_only: bool,
login_account_type: Optional[
datamanager_v1.ProductAccount.AccountType
] = None,
login_account_id: Optional[str] = None,
linked_account_type: Optional[
datamanager_v1.ProductAccount.AccountType
] = None,
linked_account_id: Optional[str] = None,
) -> None:
"""Runs the sample.
Args:
operating_account_type: the account type of the operating account.
operating_account_id: the ID of the operating account.
json_file: the JSON file containing event data.
validate_only: whether to enable validate_only on the request.
login_account_type: the account type of the login account.
login_account_id: the ID of the login account.
linked_account_type: the account type of the linked account.
linked_account_id: the ID of the linked account.
"""
# Gets an instance of the formatter.
formatter: Formatter = Formatter()
# Reads the input file.
event_rows: List[Dict[str, Any]] = read_event_data_file(json_file)
events: List[datamanager_v1.Event] = []
for event_row in event_rows:
event = datamanager_v1.Event()
try:
event_timestamp = Timestamp()
event_timestamp.FromJsonString(str(event_row["timestamp"]))
event.event_timestamp = event_timestamp
except ValueError:
_logger.warning(
"Invalid timestamp format: %s. Skipping row.",
event_row["timestamp"],
)
continue
if "transactionId" not in event_row:
_logger.warning("Skipping event with no transaction ID")
continue
event.transaction_id = event_row["transactionId"]
if "eventSource" in event_row:
event.event_source = event_row["eventSource"]
if "gclid" in event_row:
event.ad_identifiers = datamanager_v1.AdIdentifiers(
gclid=event_row["gclid"]
)
if "currency" in event_row:
event.currency = event_row["currency"]
if "value" in event_row:
event.conversion_value = event_row["value"]
user_data = datamanager_v1.UserData()
# Adds a UserIdentifier for each valid email address for the event row.
if "emails" in event_row:
for email in event_row["emails"]:
try:
processed_email: str = formatter.process_email_address(
email, Encoding.HEX
)
user_data.user_identifiers.append(
datamanager_v1.UserIdentifier(
email_address=processed_email
)
)
except ValueError:
# Skips invalid input.
_logger.warning(
"Invalid email address: %s. Skipping.",
event_row["email_address"],
)
# Adds a UserIdentifier for each valid phone number for the event row.
if "phoneNumbers" in event_row:
for phone_number in event_row["phoneNumbers"]:
try:
processed_phone: str = formatter.process_phone_number(
phone_number, Encoding.HEX
)
user_data.user_identifiers.append(
datamanager_v1.UserIdentifier(
phone_number=processed_phone
)
)
except ValueError:
# Skips invalid input.
_logger.warning(
"Invalid phone: %s. Skipping.",
event_row["phone_number"],
)
if user_data.user_identifiers:
event.user_data = user_data
# Adds the event to the list of events to send in the request.
events.append(event)
# Configures the destination.
destination: datamanager_v1.Destination = datamanager_v1.Destination()
destination.operating_account.account_type = operating_account_type
destination.operating_account.account_id = operating_account_id
destination.product_destination_id = str(conversion_action_id)
if login_account_type or login_account_id:
if bool(login_account_type) != bool(login_account_id):
raise ValueError(
"Must specify either both or neither of login "
+ "account type and login account ID"
)
destination.login_account.account_type = login_account_type
destination.login_account.account_id = login_account_id
if linked_account_type or linked_account_id:
if bool(linked_account_type) != bool(linked_account_id):
raise ValueError(
"Must specify either both or neither of linked account "
+ "type and linked account ID"
)
destination.linked_account.account_type = linked_account_type
destination.linked_account.account_id = linked_account_id
# Creates a client for the ingestion service.
client: datamanager_v1.IngestionServiceClient = (
datamanager_v1.IngestionServiceClient()
)
# Batches requests to send up to the maximum number of events per
# request.
request_count = 0
for i in range(0, len(events), _MAX_EVENTS_PER_REQUEST):
request_count += 1
events_batch = events[i : i + _MAX_EVENTS_PER_REQUEST]
# Sends the request.
request: datamanager_v1.IngestEventsRequest = (
datamanager_v1.IngestEventsRequest(
destinations=[destination],
# Adds events from the current batch.
events=events_batch,
consent=datamanager_v1.Consent(
ad_user_data=datamanager_v1.ConsentStatus.CONSENT_GRANTED,
ad_personalization=datamanager_v1.ConsentStatus.CONSENT_GRANTED,
),
# Sets encoding to match the encoding used.
encoding=datamanager_v1.Encoding.HEX,
# Sets validate_only. If true, then the Data Manager API only
# validates the request but doesn't apply changes.
validate_only=validate_only,
)
)
# Sends the request.
response: datamanager_v1.IngestEventsResponse = client.ingest_events(
request=request
)
# Logs the response.
_logger.info("Response for request #%d:\n%s", request_count, response)
if response.field_warnings:
_logger.warning(
"Request ingested successfully, but field warnings were returned. "
"Review warning details and update your implementation as needed."
)
_logger.info("# of requests sent: %d", request_count)
def read_event_data_file(json_file: str) -> List[Dict[str, Any]]:
"""Reads the JSON-formatted event data file.
Args:
json_file: the event data file.
"""
with open(json_file, "r") as f:
return json.load(f)
if __name__ == "__main__":
# Configures logging.
logging.basicConfig(level=logging.INFO)
parser = argparse.ArgumentParser(
description=("Sends events from a JSON file to a destination."),
fromfile_prefix_chars="@",
)
# The following argument(s) should be provided to run the example.
parser.add_argument(
"--operating_account_type",
type=str,
required=True,
help="The account type of the operating account.",
)
parser.add_argument(
"--operating_account_id",
type=str,
required=True,
help="The ID of the operating account.",
)
parser.add_argument(
"--conversion_action_id",
type=int,
required=True,
help="The ID of the conversion action",
)
parser.add_argument(
"--login_account_type",
type=str,
required=False,
help="The account type of the login account.",
)
parser.add_argument(
"--login_account_id",
type=str,
required=False,
help="The ID of the login account.",
)
parser.add_argument(
"--linked_account_type",
type=str,
required=False,
help="The account type of the linked account.",
)
parser.add_argument(
"--linked_account_id",
type=str,
required=False,
help="The ID of the linked account.",
)
parser.add_argument(
"--json_file",
type=str,
required=True,
help="JSON file containing user data to ingest.",
)
parser.add_argument(
"--validate_only",
choices=["true", "false"],
default="true",
help="""Whether to enable validate_only on the request. Must be
'true' or 'false'. Defaults to 'true'.""",
)
args = parser.parse_args()
main(
args.operating_account_type,
args.operating_account_id,
args.conversion_action_id,
args.json_file,
args.validate_only == "true",
args.login_account_type,
args.login_account_id,
args.linked_account_type,
args.linked_account_id,
)
```
## Success responses
A successful request returns a response with an object containing a `requestId`.
If any optional fields failed validation, the response also includes a
[`fieldWarnings`](https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest#body.IngestEventsResponse.FIELDS.field_warnings)
list.
### Standard response
Here is a sample response for a successful ingestion request with no warnings:
{
"requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}
### Response with warnings
Here is a sample response for a successful ingestion request that contains a
warning:
{
"requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
"fieldWarnings": [
{
"field": "events.events[0].cart_data.items[0].merchant_product_id",
"description": "The merchant product ID is missing in the cart item.",
"reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
}
]
}
Record the `requestId` returned so you can retrieve
[diagnostics](https://developers.google.com/data-manager/api/devguides/diagnostics) as each destination in the request is
processed. You should also check for any
[`fieldWarnings`](https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest#body.IngestEventsResponse.FIELDS.field_warnings)
to ensure any optional fields you sent were accepted. See [Ingestion
warnings](https://developers.google.com/data-manager/api/devguides/concepts/understand-errors#ingestion-warnings) for more
details.
> [!NOTE]
> **Note:** You can only retrieve diagnostics for requests that succeed and don't have `validateOnly` set to `true`.
## Failure responses
A failed request results in an error response status code such as `400 Bad
Request`, and a response with error details.
For example, an `emailAddress` containing a plain text string instead of a hex
encoded value produces the following response:
{
"error": {
"code": 400,
"message": "There was a problem with the request.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INVALID_ARGUMENT",
"domain": "datamanager.googleapis.com"
},
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "events.events[0].user_data.user_identifiers",
"description": "Email is not hex encoded.",
"reason": "INVALID_HEX_ENCODING"
}
]
}
]
}
}
An `emailAddress` that isn't hashed and is only hex encoded produces the
following response:
{
"error": {
"code": 400,
"message": "There was a problem with the request.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INVALID_ARGUMENT",
"domain": "datamanager.googleapis.com"
},
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "events.events[0]",
"reason": "INVALID_SHA256_FORMAT"
}
]
}
]
}
}
## Send events for multiple destinations
If your data contains events for different destinations, you can send them in
the same request by using destination references. See [Limits and
quotas](https://developers.google.com/data-manager/api/devguides/limits#request_limits) for the maximum
number of destinations per request.
For example, if you have an event for conversion action ID `123456789` and
another event for conversion action ID `777111122`, send both events in a single
request by setting the `reference` of each
[`Destination`](https://developers.google.com/data-manager/api/reference/rest/v1/Destination). The `reference` is
user-defined. The only requirement is that each `Destination` has a unique
`reference`. Here's the modified `destinations` list for the request:
"destinations": [
{
"operatingAccount": {
"accountType": "OPERATING_ACCOUNT_TYPE",
"accountId": "OPERATING_ACCOUNT_ID"
},
"loginAccount": {
"accountType": "LOGIN_ACCOUNT_TYPE",
"accountId": "LOGIN_ACCOUNT_ID"
},
"productDestinationId": "123456789",
"reference": "destination_a"
},
{
"operatingAccount": {
"accountType": "OPERATING_ACCOUNT_2_TYPE",
"accountId": "OPERATING_ACCOUNT_2_ID"
},
"loginAccount": {
"accountType": "LOGIN_ACCOUNT_2_TYPE",
"accountId": "LOGIN_ACCOUNT_2_ID"
},
"productDestinationId": "777111122",
"reference": "destination_b"
}
]
Set the `destinationReferences` of each
[`Event`](https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest#event) to send it to one or more
specific destinations. For example, here's an `Event` that's only for the first
`Destination`, so its `destinationReferences` list only contains the
`reference` of the first `Destination`:
{
"adIdentifiers": {
"gclid": "GCLID_1"
},
"conversionValue": 1.99,
"currency": "USD",
"eventTimestamp": "2025-06-10T20:07:01Z",
"transactionId": "ABC798654321",
"eventSource": "WEB",
"destinationReferences": [
"destination_a"
]
}
The `destinationReferences` field is a list, so you can specify multiple
destinations for an event. If you don't set the `destinationReferences` of an
`Event`, the Data Manager API sends the event to all of the destinations in the
request.
If an event has multiple destinations, the Data Manager API sends relevant fields to
each destination. For example, if an event has a Google Ads destination and a
Google Analytics destination, the API includes Google Analytics fields such as `clientId`,
`appInstanceId`, or `eventName` when sending the event to the Google Analytics
destination, and includes Google Ads fields such as `customVariables` when sending
the event to the Google Ads destination.
## Next steps
- [Configure](https://developers.google.com/data-manager/api/devguides/quickstart/set-up-access) authentication and setup your environment with a client library.
- Learn about the [formatting, hashing, and encoding requirements](https://developers.google.com/data-manager/api/devguides/concepts/formatting) for each type of data.
- Learn how to [encrypt user data](https://developers.google.com/data-manager/api/devguides/concepts/encryption).
- Learn how to [retrieve diagnostics](https://developers.google.com/data-manager/api/devguides/diagnostics) for your requests.
- Learn about [best practices](https://developers.google.com/data-manager/api/devguides/concepts/best-practices).
- Learn about [limits and quotas](https://developers.google.com/data-manager/api/devguides/limits).