Data Manager API Event Ingestion

Data Manager API Event Ingestion

Core Directives

• [IMPORTANT] When reading API documentation from developers.google.com, read the Markdown equivalent of the page by appending .md.txt to the URL.

Sequential Implementation Workflow

For simple informational, configuration, or setup questions, skip any irrelevant steps and answer using only the relevant guidelines or documentation provided below.

Step 1: Identify Use Case & Read Documentation

• Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Floodlight, Google Analytics) BEFORE generating any code. Do NOT assume Google Ads by default. This maps to the account_type field of the operating_account in the Destination, and also determines valid event identifiers and requirements.
• Read Documentation: [CRITICAL] You MUST follow the the Send events guide to understand implementation steps, user/event identifier requirements, and how to configure the destination object.

Step 2: Setup Auth

1. Enable API (Prerequisite): Check that the user has enabled the Data Manager API in their Google Cloud project.
2. Generate ADC: Authenticate the local workspace using Application Default Credentials (ADC) via gcloud auth application-default login.
   • Required Scopes: Include scopes https://www.googleapis.com/auth/datamanager and https://www.googleapis.com/auth/cloud-platform.
   • Multi-API Scopes: If using the same credentials for other APIs, append their scopes (e.g., https://www.googleapis.com/auth/adwords).
   • Service Accounts: Ensure the Service Account has the Service Usage Consumer IAM role, and the user executing gcloud has the Token Creator role (roles/iam.serviceAccountTokenCreator) on that Service Account for impersonation.
3. Reference: Refer to Set up API access for a walkthrough of the gcloud CLI auth setup.

Step 3: Install Client Library and Utilities

Refer to Install a client library for detailed installation instructions.

[IMPORTANT] The utility library is NOT available on public package managers (such as PyPI or Maven). Follow the below instructions to install:

1. Clone the repository from GitHub using the commands from the table below.
2. Always use the latest available version of the library. Determine the actual version identifier (VERSION) from the cloned repository metadata.
   • Python: Find the version in pyproject.toml.
   • Java: Find the version in data-manager-util/build.gradle.
   • Node: Find the version in util/package.json (as the version field).
3. Follow the language-specific instructions in the next section to build and install the utility dependency, replacing VERSION with the version identifier you found.

Install Utility Library

Python

1. Navigate to the data-manager-python directory and install the utility library:

   pip install .
   

2. Declare a dependency in your project's requirements.txt file (replacing VERSION with the identified version):

google-ads-datamanager-util==VERSION ```

Java

1. Navigate to the data-manager-java directory.
2. Build and publish the utility library to your local Maven repository:

./gradlew data-manager-util:install

3. Declare a dependency on the utility library in your project (replacing VERSION with the identified version):

   • Gradle:

   implementation 'com.google.api-ads:data-manager-util:VERSION'
   

   • Maven:

   <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>data-manager-util</artifactId>
      <version>VERSION</version>
   </dependency>
   

Node

1. Navigate to the data-manager-node directory and install dependencies:

npm install

2. Navigate to the util directory:

cd util

3. Pack the utility library into a .tgz archive:

npm pack

4. Declare a dependency in your Node.js project's package.json pointing to the path of the generated .tgz archive (replacing VERSION with the identified version):

{
   "dependencies": {
      "@google-ads/data-manager-util": "file:/path/to/google-ads-datamanager-util-VERSION.tgz"
   }
}

PHP

1. Navigate to the data-manager-php directory.
2. Resolve dependencies for the library:

composer update --prefer-dist

3. Update your project's composer.json to declare a dependency on the utility library using a path repository:

 {
     "repositories": [
         {
             "type": "path",
             "url": "/path/to/cloned/data-manager-php"
         }
     ],
     "require": {
         "googleads/data-manager-util": "@dev"
     }
 }

.NET

In your .NET project, declare a ProjectReference dependency pointing to the cloned library's .csproj path:

<ProjectReference Include="\path\to\cloned\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

Step 4: Retrieve Code Sample

[IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Step 5: Retrieve migration guides

[CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

Google Ads

• Google Ads API Offline Conversions: Google Ads Offline Conversions Migration Field Mappings
• Google Ads API Store Sales: Google Ads Store Sales Migration Field Mappings

Google Analytics

• Measurement Protocol (Google Analytics): Google Analytics Measurement Protocol Migration Field Mappings

Campaign Manager 360 (CM360)

• Campaign Manager 360 API Offline Conversions: Campaign Manager 360 Offline Conversions Migration Field Mappings

Step 6: Implementation

Implement the ingestion logic using the following checkpoints:

• Initialize Client: Instantiate the Data Manager client (IngestionServiceClient).
• Define Destinations: Build the Destination object using the product_destination_id and the appropriate account configurations: operating_account (target account receiving data), login_account (if authenticating using a manager account or a data partner account), and linked_account (if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
• Prepare Event Data: Use the utility library helpers to format and normalize user identifiers correctly.
• Construct Payload: Build the request payload (IngestEventsRequest) containing the destinations, event records, and consent permissions.
• Send Request: Execute ingest_events and record the returned request ID for logging/troubleshooting.

Formatting

• Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

• Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

  Python Example:

  from google.ads.datamanager_util import Formatter
  from google.ads.datamanager_util.format import Encoding
  
  formatter: Formatter = Formatter()
  
  processed_email: str = formatter.process_email_address(
      email, Encoding.HEX
  )
  

Critical Gotchas

• Format product_destination_id as a numeric string. It is NOT a resource name path.
• Format event_timestamp strictly in RFC 3339 format. Use the SDK's typed timestamp object instead of a raw string where available.
• Nest click identifiers (gclid, gbraid, wbraid) inside the ad_identifiers block, not directly on the base event payload.
• The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
• Note that consent can be set globally on the IngestEventsRequest or on individual Events.
• Verify that UserIdentifier uses email_address and phone_number. Do NOT use the Google Ads API fields hashed_email and hashed_phone_number.
• Ensure the currency field on the event is named currency, not currency_code.

Error Handling & Troubleshooting

Inspecting Error Payloads

[IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

API Reference

When implementing or debugging API integrations, use the API reference to lookup field names, types, and acceptable values. DO NOT guess values.

• REST API Reference: https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest