Index of every page on this site: llms.txt
All skills
google avatar

/data-manager-api-event-ingestion

@5fb62c2
by googlegoogle/skills24k stars
2,026
Run it yourself

Guides developers through implementing event and conversion ingestion to Google products using the Data Manager API /v1/events/ingest endpoint and its associated client libraries. Use this skill when the user wants to upload offline conversions, enhanced conversions for leads, click conversions, call conversions, Google Analytics web or app events, or any other event ingestion use case supported by the Data Manager API. Don't use for uploading audience members (use the data-manager-api-audience-ingestion skill), or for debugging errors, checking request status, or investigating missing conversions (use the data-manager-api-troubleshooting skill).

Use this Skill: https://skilld.dev/gh/google/skills/data-manager-api-event-ingestion

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈172 tokens for metadata: the name and description. ≈2.9k when used: this file.

Description uses 8.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈689 characters, or 8.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Data Manager API Event Ingestion

Implementation Workflow

Prerequisites

  • Authentication & Library Installation: If you need to set up access to the Data Manager API or install the client and utility libraries, refer to the data-manager-api-setup skill.

Step 1: Identify Use Case & Read Documentation

  • Determine Destination Account Type: [CRITICAL] If it can't be determined from the user's context, consider clarifying which destination events are being ingested to before generating any code. This maps to the account_type field of the operating_account in the Destination, and also determines valid event identifiers and requirements.
  • Identify User Intent:
    • Answering questions about requirements or implementing ingestion code: Retrieve the full contents of the relevant implementation guide for the destination and use case in the Implementation guide column below before answering or writing code. Use its Event field requirements, Identifier requirements, and How Google handles multi-source data sections as the source of truth for destination configuration, event and identifier requirements, and deduplication or update behavior.
    • Checking request status or inspecting errors: Use the data-manager-api-troubleshooting skill.
    • Migrating from another Google API: Refer to Step 3: Retrieve Migration Guides below to extract the full contents of the relevant field mapping guide.
Destination (operating_account.account_type) Use case Implementation guide
Google Ads (GOOGLE_ADS) Offline conversions, enhanced conversions for leads Send events
Google Ads (GOOGLE_ADS) Multi-source conversions supplementing the Google tag Send events
Google Ads (GOOGLE_ADS) Store sales conversions Send events
Google Ads (GOOGLE_ADS) Call conversions Send events
Google Analytics (GOOGLE_ANALYTICS_PROPERTY) Recommended and custom GA4 events Send events
Google Analytics (GOOGLE_ANALYTICS_PROPERTY) Multi-source events with a transaction ID Send events
Floodlight (FLOODLIGHT_CONFIG) Floodlight offline conversions Send events
Floodlight (FLOODLIGHT_CONFIG) Multi-source conversions supplementing the Google or Floodlight tag Send events

If the request doesn't match any row, fetch the Events overview to find the right guide rather than guessing.

Step 2: Retrieve Code Sample

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

Language Sample
Python ingest_events.py
Java IngestEvents.java
PHP ingest_events.php
Node ingest_events.ts
.NET IngestEvents.cs

Step 3: Retrieve Migration Guides

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

Google Ads
Google Analytics
Floodlight

Step 4: 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). The Data Manager API does not support sending events to Floodlight or Google Analytics destinations using a linked data partner. 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, consent permissions, and encoding (HEX or BASE64, matching the encoding used to hash user identifiers).
  • Support Validation: Support sending the validate_only boolean option on the IngestEventsRequest to allow developers to validate schemas without actually uploading data.
  • Send Request: Execute ingest_events and record the returned request_id for later diagnostics. Keep the request payload, or a mapping from each event's position to your own record ID, with the request_id. Diagnostics identify failed events by their position in the request.
  • Check for Ingestion Warnings: If any non-required field had a validation failure, the response from ingest_events will also include field_warnings, a list of FieldWarning objects detailing the issues.
  • Retrieve Request Status: Check the status of the ingestion request using diagnostics. Since request processing is asynchronous, a successful ingestion response (HTTP 200 OK returning a request_id) only indicates the payload was received. To check if the records actually succeeded, partially succeeded, or failed to process, query the client.retrieve_request_status endpoint using the request_id, starting at least 30 minutes after sending. Skip this step when validate_only is true, because validation-only requests don't have diagnostics. Skipping this step for real requests is a common user mistake. To read the results or debug failures, use the data-manager-api-troubleshooting skill.

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.
  • If sending hashed user identifiers in user_data, you must set the encoding field on the IngestEventsRequest to HEX or BASE64, matching the encoding passed to the utility library Formatter.
  • event_source is required for Google Ads offline conversions and enhanced conversions for leads (such as WEB), and must be IN_STORE for store sales.
  • Google Ads session attributes: Prefer setting ad_identifiers.session_attributes to the base64-encoded string captured from the form submission. Don't build this string from individual attributes. Only if you can't capture the encoded string, add an ExperimentalField to experimental_fields for each attribute (required: gad_source, gad_campaignid, session_start_time_usec; optional: landing_page_url, landing_page_referrer), and set ad_identifiers.landing_page_device_info.user_agent.
  • Use IngestEvents (ingest_events, IngestEventsRequest) for all conversion and event uploads. Do not suggest IngestAdEvents, which is only available to ad tech partner accounts on an allowlist.

API Reference

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alertstoday3 checks · Risk SAFE
  • Gen Agent Trust Hub1d

    This skill provides guidance for using the Google Data Manager API for event ingestion. It includes references to official Google documentation and code samples from trusted repositories. Security considerations regarding data handling are addressed through instructions for proper formatting and hashing of user identifiers using vendor-provided utility libraries.

  • Sockettoday

    No alerts

  • Snyk1d

    Risk: LOW · No issues

Signed by skilld at 5fb62c2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
metadata
{
  "version": "1.3.0",
  "category": "GoogleAds"
}

README badge

README badge for google/skills/data-manager-api-event-ingestion