Documentation

Google Data Manager - Audiences

📘

This integration is currently in beta. Contact your MetaRouter support team to get started.

What Is Google Data Manager - Audiences?

Google Data Manager is Google's unified data ingestion service for advertising and measurement. Its Audience Members service (audienceMembers:ingest and audienceMembers:remove) accepts Customer Match audience data and fans it out to multiple Google products — Google Ads, and Display & Video 360— from a single API call. This MetaRouter Starter Kit, "Google Data Manager - Audiences," sends SHA-256 hashed user identifiers, mobile advertising IDs, or user IDs to the audience membership endpoint to add or remove members across destinations.

Product Type: Advertising
Integration Type: Starter Kit
Event Source Type: Web, Mobile Browser, Mobile App
Event Scope: Identify

Capabilities

  • Adds or removes Customer Match audience members through the Google Data Manager audienceMembers:ingest and audienceMembers:remove endpoints using an HTTP POST with an OAuth2 JWT bearer token.
  • Fans out a single audience to multiple Google destinations — Google Ads, and Display & Video 360 — in one request via the destinations[] array.
  • Sends consent signals and Customer Match terms-of-service acceptance for ingest operations.
  • Ships with HEX encoding for hashed identifiers.

Considerations

  • The integration only forwards events that carry at least one usable identifier — traits.email, traits.phone, userId, context.device.advertisingId, or context.ip. Events with none of these are filtered out before delivery, since they cannot be matched to an audience member.
  • validateOnly is set to false in the global enrichments, so the kit ships ready to apply live audience changes. Set it to true to validate requests without executing them — the API checks each request and returns only errors, not results. Useful for schema and configuration testing.
  • The OPERATION_TYPE connection parameter controls the endpoint action: ingest adds members and remove removes them. Consent and terms-of-service values are only sent on ingest.
  • The kit sends a single audience to several Google platforms at once. You configure one entry per target platform in the destinations array in the global Lua, and each destination is addressed by its operatingAccount.accountType, accountId, and productDestinationId. If you do not use a given platform, remove that entry from the destinations Lua.
  • By default, each member is delivered with destinationReferences matching its data-type block (a contact member points at ads_contact and dv_contact, and so on). These reference names are internal labels, not API values, and are managed automatically — you do not edit destinationReferences by hand. Removing a destination line from the Lua is sufficient; the references update accordingly.
    • Alternatively, to send every member to all listed destinations rather than targeting by reference, remove the reference parameter from the destination(...) function definition and from each destination(...) call — for example, destination("GOOGLE_ADS", "ADD_GOOGLE_ADS_ACCOUNT_ID_HERE", "ADD_CONTACT_LIST_ID_HERE"). With no references set, each member is sent to all destinations.
  • Multiple destinations of the same data type are supported. Add an additional destination(...) line within the applicable data-type block, using a unique reference name.
  • Each request supports a single data type. Retain the data-type block required for your use case (contact, mobile ID, or user ID) and remove the other two, along with their corresponding mappings and filter conditions, as indicated by the "PICK ONE" comment in the playbook. Requests containing multiple data types are rejected with MULTIPLE_DATA_TYPES_NOT_ALLOWED.
  • Audience members are built from whichever identifiers are present: hashed user identifiers and/or IP address (in compositeData), a mobile advertising ID (mobileData), or a user ID (userIdData). The destination list is selected to match the identifier type available.
  • encoding is required when the request includes compositeData uploads; this kit sets it to HEX. Email, phone, and name fields are SHA-256 hashed before sending.
  • The kit sets consent (adUserData and adPersonalization) to CONSENT_GRANTED and Customer Match terms of service to ACCEPTED for ingest operations; confirm this matches the pipeline's consent enforcement.
  • Event-specific mappings do not apply to this integration; the global mappings transform all incoming events regardless of type.
  • This kit uses a batch size of 500.

Limitations

  • Diagnostics cannot be retrieved for requests that have validateOnly set to true; the kit must be switched out of validate-only mode before request status can be polled.
  • Each Google Cloud project is limited to 100,000 IngestionService requests per day and 300 requests per minute; exceeding the limits returns RESOURCE_EXHAUSTED with HTTP status 429 Too Many Requests.
  • An audience must have at least 100 members before it is eligible for targeting.
    • Audience member requests must comply with the EU Political Ads Regulation (EU PAR); an operation on an account without the required declaration returns EU_POLITICAL_ADVERTISING_DECLARATION_REQUIRED.
    • Mixed-data-type requests are rejected with MULTIPLE_DATA_TYPES_NOT_ALLOWED; each request must contain a single data type.

Starter Kit Setup Guide

1. Gather Credentials

  • Create a Google Cloud project, enable the Data Manager API, and create a service account with the datamanager scope. Grant the service account's email access to each destination. Then collect:
    • Service account email
    • RSA private key (PEM)
    • Each destination's account ID and audience list ID (productDestinationId)
  • For how to create a service account, configure the datamanager scope, and grant destination access, see Set up API Access.
  • For details on accountType, accountId, and productDestinationId, see Configure Destinations and the Destination Resource reference.

2. Add a Google Data Manager - Audiences Integration

  • From the integration library, add a Google Data Manager - Audiences integration. Then, fill out the Connection Parameters:
Connection ParameterDescription
API_VERSIONAPI version segment in the endpoint URL. Defaults to v1.
SERVICE_ACCOUNT_EMAILService account email used as the JWT issuer (iss) for OAuth2 authentication.
PRIVATE_KEYRSA private key (PEM) used to sign the OAuth2 JWT assertion. Include the full key, from `-----BEGIN PRIVATE KEY-----` through `-----END PRIVATE KEY-----`.
OPERATION_TYPEEndpoint action: ingest to add members or remove to remove them. Defaults to ingest.

3. Configure Event Mapping

  • MetaRouter provides all of the event mappings that Google Data Manager - Audiences integrations typically require. You may add custom events, parameters, or mappings in accordance with Google's API documentation.

4. Deploy to Pipeline

  • In the Pipelines tab, add your Google Data Manager - Audiences integration.
  • Select the correct integration revision.
  • Click Add Integration to finalize deployment.

Event Mappings

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Destinations Lua

The destinations Lua contains three conditional blocks, one per data type — contact (hashed email, phone, or address, or IP), mobile advertising ID, and user ID. Each block returns the destination(s) that a member of that type should be sent to. The kit ships with all three so you can see the options, but a single integration sends one data type only.

Configure it as follows:

  1. Keep the block matching the data type you are sending, and delete the other two blocks.
  2. In the block you keep, replace the account ID and list ID placeholders (for example, destination("ads_contact", "GOOGLE_ADS", "ADD_GOOGLE_ADS_ACCOUNT_ID_HERE", "ADD_CONTACT_LIST_ID_HERE")) with your Google Ads account ID and the audience list ID for that data type.
  3. Remove the mappings that correspond to the deleted data types, and remove their matching conditions from global.filters.

Each destination(...) line takes the form destination(reference, accountType, accountId, productDestinationId), where accountId is your platform account ID and productDestinationId is the audience list ID for that data type.

Output KeyDescriptionExpected Input
encoding RequiredString: Encoding of hashed user identifiers; required for compositeData uploads.Enrichment – HEX
destinations RequiredArray: Destination objects that receive the audience members.Expression – builds destination(reference, accountType, accountId, productDestinationId) entries for GOOGLE_ADS and DISPLAY_VIDEO_ADVERTISER. Replace ADD_GOOGLE_ADS_ACCOUNT_ID_HERE / ADD_DISPLAY_VIDEO_ADVERTISER_ID_HERE with each platform's account ID, and ADD_CONTACT_LIST_ID_HERE / ADD_MOBILE_LIST_ID_HERE / ADD_USERID_LIST_ID_HERE with the target audience list ID (productDestinationId) for that data type.
audienceMembers.compositeDataObject: Contains userData.userIdentifiers (SHA-256 hashed email, phone, or address) and/or ipData (IP address with observe-start time).Expression – hashes traits.email, traits.phone, and address (givenName from firstName, familyName from lastName, postalCode, regionCode via TO_ISO_COUNTRY(country)); adds ipData from context.ip with observeStartTime from timestamp
audienceMembers.mobileData.mobileIdsString: Advertiser-defined user ID; set only when the kit is configured for the user ID data type.Expression – returns context.device.advertisingId when present
audienceMembers.userIdData.userIdString: Advertiser-defined user ID; set only when the kit is configured for the user ID data type.userId
consentObject: Consent signals (adUserData, adPersonalization); sent only for ingest.Expression – CONSENT_GRANTED for both when $$OPERATION_TYPE$$ is ingest
termsOfService.customerMatchTermsOfServiceStatusString: Customer Match terms-of-service status; sent only for ingest.Expression – ACCEPTED when $$OPERATION_TYPE$$ is ingest
validateOnlyBoolean: When true, requests are validated but not executed; only errors are returned. Used for testing.Enrichment – false

Recommended Identifiers

These identifiers should be mapped to Google Data Manager in order for successful user matching to occur. Each audience member requires at least one identifier; the kit uses the identifiers present on the event (hashed user identifiers, IP address, mobile advertising ID, or user ID).

AttributeExampleSync Injector Required?
email_hash3e693cf7e5b67880bff33b2d2626dadb7bf1d4bc737192e47cf8baa89acf2250No
phone_hashd634b0526e6b...No
address{givenName, familyName, postalCode, regionCode}No
mobileDeviceId38400000-8cf0-11bd-b23e-10b96e40000dNo
userId111222No

Integration Validation

validateOnly is set to false in the global enrichments, so the kit applies live audience changes by default. To test without writing data, set validateOnly to true — the API validates each request and returns only errors, not results. Switch it back to false before going live.

After sending live (non-validate-only) requests, use the request_id from a successful ingestion response to poll RetrieveRequestStatus for per-destination processing status. Diagnostics are available only for successful requests that do not have validateOnly set to true. Google recommends waiting 30 minutes before the first check, then polling with exponential backoff (example: 1.3 multiplier, 60-minute cap) for up to 24 hours until each destination reaches SUCCESS, PARTIAL_SUCCESS, or FAILURE. For this integration, review the composite_data_ingestion_status per destination — record_count, data_type_counts, and upload_match_rate_range — to confirm members were received and matched.

Please see more information below:

Additional Google Data Manager Documentation

Updated 2 days ago