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

/data-manager-api-audience-ingestion

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

Guides developers through managing (adding, removing, and clearing) audience members for Google products using the Data Manager API and its associated client libraries. Use this skill when the user wants to upload audience members, remove specific users, or clear/replace an entire audience for Customer Match, mobile device ID audiences, or any other audience use case supported by the Data Manager API. Don't use for uploading events or conversions (use the data-manager-api-event-ingestion skill), or for debugging errors, checking request status, or investigating low match rates (use the data-manager-api-troubleshooting skill).

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

Nothing lands on disk. Nothing to clean up.

Fork this Skill

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

SKILL.md

≈168 tokens for metadata: the name and description. ≈2.1k when used: this file. ≈685 more on demand in 2 files.

Description uses 8.4% 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 ≈671 characters, or 8.4%.

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 Audience 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.
  • Audience Creation (if needed): If the user does not have an existing audience or needs to create a new one, use the Create an Audience reference. This step provides the product_destination_id needed for the ingestion or removal requests.

Step 1: Identify Use Case & Read Documentation

  • Determine Destination Account Type: [CRITICAL] If it's not clear where the data is being sent (e.g., Google Ads, Display & Video 360, etc.), STOP and CLARIFY with the user 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.
  • Read the implementation guide: Read the relevant guide for your destination and use case. Do this before answering questions or writing code because each destination has unique payload structures, consent rules, and required fields.
Destination Audience Type Accepted Data Types Upload Guide Remove All/Replace All Guide
Google Ads Customer Match composite_data.user_data (contact info), mobile_data (device IDs), user_id_data (user IDs) Upload Data Remove All/Replace All
Display & Video 360 (DV360) Customer Match composite_data.user_data (contact info), mobile_data (device IDs) Upload Data Remove All/Replace All

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_audience_members.py
Java IngestAudienceMembers.java
PHP ingest_audience_members.php
Node ingest_audience_members.ts
.NET IngestAudienceMembers.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
Display & Video 360

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). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
  • Format User Data: If sending an IngestAudienceMembersRequest or RemoveAudienceMembersRequest, refer to Formatting User Data to properly normalize and hash user identifiers using the utility library.
  • Construct Payload: Build the appropriate request payload based on the operation:
    • Add: IngestAudienceMembersRequest
    • Remove: RemoveAudienceMembersRequest
    • Remove All: RemoveAllAudienceMembersRequest
  • Support Validation: Support sending the validate_only boolean option on the payload to allow developers to validate schemas without actually applying changes.
  • Send Request: Execute the appropriate method and record the returned request_id for later diagnostics. Keep the request payload, or a mapping from each member's position to your own record ID, with the request_id. Diagnostics identify failed members by their position in the request.
    • Add: ingest_audience_members
    • Remove: remove_audience_members
    • Remove All: remove_all_audience_members
  • Check for Ingestion Warnings: If any non-required field had a validation failure, the response from ingest_audience_members 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 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 client.retrieve_request_status 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.

Critical Gotchas

  • If sending hashed user identifiers in user_data for ingest_audience_members or remove_audience_members, you must set the encoding field on the IngestAudienceMembersRequest to HEX or BASE64.
  • If uploading to a Customer Match audience, the terms_of_service field is required on the IngestAudienceMembersRequest to indicate the user has accepted the policies.
  • Only set the address field on UserIdentifier if all required fields (postal_code, family_name, given_name, region_code) are present; incomplete address fields will cause the API request to fail.
  • product_destination_id must be a numeric string. It is NOT a resource name.
  • The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
  • Field names on UserIdentifier are email_address and phone_number. Do not use the Google Ads API field names hashed_email and hashed_phone_number.

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 alerts1d3 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    This skill is safe and provides comprehensive guidance for developers using official Google Data Manager APIs. It correctly directs users to official documentation and libraries while emphasizing security best practices like data normalization and hashing.

  • Socket1d

    No alerts

  • Snyk2d

    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.2.0",
  "category": "GoogleAds"
}

README badge

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