canonical: https://jentic.com/apis/googleapis.com/playgrouping

# Google Play Grouping API

The Google Play Grouping API lets Android apps tag in-app users with custom attributes that Play Console can then use as audience filters in vitals reports, store listing experiments, and notifications. Two endpoints cover verifying that a token belongs to a Play user and creating or updating tags on that user, all keyed by an opaque app-issued token. The intended flow is server-side: an app's backend mints tags such as 'beta_cohort' or 'high_lifetime_value' so Play tooling can segment vitals and messaging on those attributes.

## For AI agents

Tag Android users with custom attributes server-side so Google Play Console can segment vitals, listings, and notifications by audience.

## Scope

Does not query or read tags, send notifications, or report vitals - use only to verify Play tokens and write server-side tags on Android users.

## Capabilities

- Verify that an app-issued user token corresponds to a valid Play user before tagging
- Create or update server-side tags on an Android user keyed by app package and token
- Build audience cohorts inside Play Console by combining multiple tag values
- Drive segmented vitals reporting and notification targeting from app backend events

## Use cases

### Audience-Based Vitals Segmentation

Server-side, an app backend tags signed-in Android users with attributes such as customer tier, beta cohort, or country pricing band. Once tags are in Play, the developer filters crash and ANR vitals by tag value to see whether a regression is concentrated in a specific cohort. Tag updates are eventually consistent and typically reflected in Play Console reports within hours.

Example prompt: POST /v1alpha1/{appPackage}/{token}/tags:createOrUpdate with body containing tags=[{key: 'tier', value: 'enterprise'}] for each signed-in user.

### Targeted Play Notifications

Marketing and lifecycle teams use Play Grouping to define audiences for Play Store listing experiments and Play notifications. The backend writes tag values such as 'lapsed_30d' or 'subscriber_active' to each user, and Play Console targets messaging to those tag values. The setup decouples user segmentation from in-app code and centralises it in the backend.

Example prompt: Iterate over a CRM segment of lapsed users and POST /v1alpha1/{appPackage}/{token}/tags:createOrUpdate with tags=[{key: 'lifecycle', value: 'lapsed_30d'}] for each user's Play token.

### Token Verification Before Tagging

Before applying tags from an untrusted client, a backend calls verify on the app-issued token to confirm it represents a real Play user for the given package. This avoids polluting Play tag stores with junk identifiers and produces audit-friendly logs of which tokens were honoured. The verify and tags:createOrUpdate endpoints together form a two-step write path.

Example prompt: POST /v1alpha1/{appPackage}/{token}:verify, and on a successful response immediately POST /v1alpha1/{appPackage}/{token}/tags:createOrUpdate with the intended tag set.

### AI Agent Tagging via Jentic

Lifecycle automation agents that decide which user is in which cohort can call the Grouping API through Jentic without managing app-package paths or token formats by hand. Jentic exposes the verify and tags:createOrUpdate operations as two search-load-execute calls, so the agent can verify a token then write tags in a single short flow.

Example prompt: Search Jentic for 'tag a Google Play user', load the tags.createOrUpdate schema, and execute it with the app package, user token, and the cohort tag values.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1alpha1/{appPackage}/{token}/tags:createOrUpdate | Create or update tags on a Play user identified by app token |
| POST | /v1alpha1/{appPackage}/{token}:verify | Verify that an app-issued token corresponds to a real Play user |

## Key resources

- **tags** — Create or update server-side tags on a Play user keyed by app package and token

## Why Jentic

- **Setup:** Wiring the Google Play Grouping API by hand means managing the Google Cloud project credential for the service, handling app-issued user tokens, and posting tag writes to the package and token path on playgrouping.googleapis.com yourself. Through Jentic you install once, import the Google Play Grouping API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The Google Play Grouping API puts the app package and user token in the URL path (/v1alpha1/{appPackage}/{token}/tags:createOrUpdate, /v1alpha1/{appPackage}/{token}:verify), so a rule can pin your agent to one app package: it can verify tokens and write tags there and nothing else. You choose the operations it may call, so you can allow verification alone and leave tag writes out of the allowed set.
- **Credential handling:** Your Google Cloud project credential for the Grouping API is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'tag a Google Play user' or 'verify a Play user token', and Jentic returns the matching Grouping operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Play Developer Reporting API** — Filter vitals reports by the audience cohorts created here
- **Google Play Integrity API** — Attest the device and app before trusting a token enough to tag the user
- **Google Play Android Publisher API** — Manage releases and listings whose audiences are defined by Grouping tags

## FAQ

### What authentication does the Google Play Grouping API use?

The OpenAPI spec for v1alpha1 declares no security schemes - calls are authenticated using the app-issued user token in the path plus standard Google project credentials negotiated out of band. Through Jentic any required project credentials are stored in your Jentic One instance and injected at call time.

### Can I write multiple tags on a user in one call?

Yes. POST /v1alpha1/{appPackage}/{token}/tags:createOrUpdate accepts a list of tag key-value pairs in a single request, so an entire cohort definition such as tier, lifecycle, and country can be written in one call. Existing keys with the same name are overwritten.

### What are the rate limits for this API?

Standard Google Cloud project quotas apply. Because tagging is typically driven from a backend reacting to user events, design the writer to batch updates and back off on 429 responses rather than calling per-event from a hot loop.

### How do I tag a user through Jentic?

Run jentic search 'tag a Google Play user', load the schema for POST /v1alpha1/{appPackage}/{token}/tags:createOrUpdate, and execute it with the app package, user token, and the desired tag list. Verify the token first by calling the {token}:verify operation if the token came from an untrusted client.

### Is the Google Play Grouping API free?

There is no per-call charge for this API. Standard Google Cloud quota and Play developer account requirements apply. The feature is in v1alpha1, so behaviour and quotas may change as it stabilises.

### Can I read the tags currently on a user?

No. The two endpoints in v1alpha1 are tags:createOrUpdate and the token verify operation; there is no read endpoint for inspecting a user's existing tags. Track tag state in the writer's own datastore if you need a read path.

### Can I limit what my agent is allowed to do with the Google Play Grouping API?

Yes. Because you run Jentic One self-hosted, your own rules decide which of this API's two operations the agent may call, so you can allow token verification (/v1alpha1/{appPackage}/{token}:verify) on its own and leave tag writes (/v1alpha1/{appPackage}/{token}/tags:createOrUpdate) out of the allowed set. Since the app package sits in the URL path, a rule can also pin the agent to a single app package, letting it verify tokens and write tags there and nowhere else. The Google Cloud project credential stays with your Jentic One instance and is injected at call time, never entering the agent's prompt or logs.