Accounts¶

Nova Play's Google Ads presence is organised as one manager account with ten client customer accounts, one per game. All reporting queries are run against a client customer; the manager account only appears in the login-customer-id header.

Manager account 9990001111 (Nova Play)
├── customer 5423891542  Dragon Merge Saga (Android)
│   ├── campaign DMS_GG_AND_SEA_VALUE_202512
│   │   ├── ad group SEA_Broad_ID-PH-VN
│   │   │   ├── ad VID_BossFight_v2
│   │   │   └── ad …
│   │   └── ad group …
│   └── campaign …
├── customer 8340496580  Idle Mining Empire (Android)
└── … (10 customers in total)

Discovering your customers¶

GET /v18/customers:listAccessibleCustomers returns the resource names of every customer your credentials may query. Always start from this call rather than hard-coding ids.

curl -s "https://googleads.huydata.com/v18/customers:listAccessibleCustomers" \
  -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  -H "developer-token: $GOOGLE_DEVELOPER_TOKEN" \
  -H "login-customer-id: 9990001111"

{
  "resourceNames": [
    "customers/5423891542",
    "customers/8340496580",
    "customers/2375371730",
    "customers/1163385796",
    "customers/3250885192",
    "customers/6919164314",
    "customers/2405781364",
    "customers/8230886562",
    "customers/2325394968",
    "customers/9516973558"
  ]
}

Response field	Type	Description
`resourceNames[]`	`string`	Resource names of the form `customers/{customerId}`. The id is the 10-digit number after the slash.

The manager account itself is not listed and cannot be queried. Querying any customer id that is not in this list returns HTTP 403 with authorizationError: USER_PERMISSION_DENIED (see Authentication).

The ten game accounts¶

Each customer corresponds to exactly one game and one app store. The customer resource gives you the descriptive name; the campaign resource gives you the store app id (campaign.app_campaign_setting.app_id).

Customer id	`customer.descriptive_name`	Game code	OS	`app_campaign_setting.app_id`	`app_campaign_setting.app_store`
`5423891542`	Dragon Merge Saga (Android)	`DMS`	Android	`com.novaplay.dragonmerge`	`GOOGLE_APP_STORE`
`8340496580`	Idle Mining Empire (Android)	`IME`	Android	`com.novaplay.idlemining`	`GOOGLE_APP_STORE`
`2375371730`	Zombie Siege Defense (Android)	`ZSD`	Android	`com.novaplay.zombiesiege`	`GOOGLE_APP_STORE`
`1163385796`	Puzzle Blast Mania (iOS)	`PBM`	iOS	`id1600000011`	`APPLE_APP_STORE`
`3250885192`	Castle Match Legends (iOS)	`CML`	iOS	`id1600000012`	`APPLE_APP_STORE`
`6919164314`	Car Park Master 3D (Android)	`CPM`	Android	`com.novaplay.carpark3d`	`GOOGLE_APP_STORE`
`2405781364`	Sushi Shop Tycoon (iOS)	`SST`	iOS	`id1600000013`	`APPLE_APP_STORE`
`8230886562`	Hero Tower Defense (Android)	`HTD`	Android	`com.novaplay.herotd`	`GOOGLE_APP_STORE`
`2325394968`	Word Garden Story (iOS)	`WGS`	iOS	`id1600000014`	`APPLE_APP_STORE`
`9516973558`	Pixel Survivors (Android)	`PSV`	Android	`com.novaplay.pixelsurvivors`	`GOOGLE_APP_STORE`

The ids above are the ones returned by the sandbox at the time of writing. Treat customers:listAccessibleCustomers as the source of truth.

All accounts share these settings:

Field	Value
`customer.currency_code`	`USD`
`customer.time_zone`	`Etc/UTC`
`customer.manager`	`false`
`customer.status`	`ENABLED`

Example — reading the customer resource:

curl -s -X POST "https://googleads.huydata.com/v18/customers/5423891542/googleAds:searchStream" \
  -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  -H "developer-token: $GOOGLE_DEVELOPER_TOKEN" \
  -H "login-customer-id: 9990001111" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT customer.id, customer.descriptive_name, customer.currency_code, customer.time_zone, customer.manager, customer.status FROM customer"}'

[
  {
    "results": [
      {
        "customer": {
          "id": "5423891542",
          "descriptiveName": "Dragon Merge Saga (Android)",
          "currencyCode": "USD",
          "timeZone": "Etc/UTC",
          "manager": false,
          "status": "ENABLED"
        }
      }
    ],
    "fieldMask": "customer.id,customer.descriptiveName,customer.currencyCode,customer.timeZone,customer.manager,customer.status",
    "requestId": "65c48971f61b46d88d85"
  }
]

Account hierarchy¶

Level	GAQL resource	Typical count per customer	Notes
Customer	`customer`	1	One per game
Campaign	`campaign`	2 – 4	Video action campaigns (`advertising_channel_type = VIDEO`, `advertising_channel_sub_type = VIDEO_ACTION`)
Ad group	`ad_group`	2 – 3 per campaign	Each ad group targets an audience in a subset of the campaign's countries
Ad	`ad_group_ad`	3 – 5 per ad group	One creative each (video, playable or image)

Across the 10 customers there are about 30 campaigns, 70 ad groups and 280 ads. Every entity has a numeric id returned as a string, and a resource_name:

Resource	`resource_name` pattern	Example
`customer`	`customers/{customerId}`	`customers/5423891542`
`campaign`	`customers/{customerId}/campaigns/{campaignId}`	`customers/5423891542/campaigns/22245080429`
`campaign_budget`	`customers/{customerId}/campaignBudgets/{budgetId}`	`customers/5423891542/campaignBudgets/32245080429`
`ad_group`	`customers/{customerId}/adGroups/{adGroupId}`	`customers/5423891542/adGroups/22395831285`
`ad_group_ad`	`customers/{customerId}/adGroupAds/{adGroupId}~{adId}`	`customers/5423891542/adGroupAds/22395831285~20923328157`
ad (inside `ad_group_ad.ad`)	`customers/{customerId}/ads/{adId}`	`customers/5423891542/ads/20923328157`
`geo_target_constant`	`geoTargetConstants/{criterionId}`	`geoTargetConstants/2840`

Naming conventions¶

Nova Play names its entities so that the key dimensions can be parsed from the name.

Campaign names¶

{GAME}_{PLATFORM}_{OS}_{GEO}_{OBJECTIVE}_{YYYYMM}

Token	Values	Meaning
`GAME`	`DMS`, `IME`, `ZSD`, `PBM`, `CML`, `CPM`, `SST`, `HTD`, `WGS`, `PSV`	Three-letter game code (see the account table above)
`PLATFORM`	`GG`	Ad platform — always `GG` (Google) in this API
`OS`	`AND`, `IOS`	Operating system of the promoted app
`GEO`	`T1`, `SEA`, `LATAM`, `EA`	Country group the campaign targets (see Geo targets)
`OBJECTIVE`	`INSTALL`, `VALUE`	`INSTALL` optimises for installs (`bidding_strategy_type = TARGET_CPA`); `VALUE` optimises for purchase value (`MAXIMIZE_CONVERSION_VALUE`)
`YYYYMM`	e.g. `202512`	Year and month the campaign started

Examples: DMS_GG_AND_SEA_VALUE_202512, DMS_GG_AND_EA_INSTALL_202610. If two campaigns in the same account would get the same name, the second one carries a _B suffix.

Ad group names¶

{GEO}_{AUDIENCE}_{COUNTRY-COUNTRY-…}

AUDIENCE is one of Broad, Lookalike_Payers, Interest_Gaming; the trailing part lists the ISO country codes the ad group targets, sorted and joined with -. Example: SEA_Lookalike_Payers_ID-PH-TH-VN.

Ad names¶

{FORMAT}_{CONCEPT}_v{N}

FORMAT is VID (video), PLAY (playable) or IMG (image); CONCEPT is the creative concept (Gameplay15s, Gameplay30s, Tutorial, BossFight, FailCompilation, Satisfying, Meme, StoryIntro, UpgradeLoop, Challenge); N is the version. Example: VID_BossFight_v2.

Campaign status and lifecycle¶

Field	Values	Meaning
`campaign.status`	`ENABLED`, `PAUSED`	The advertiser's setting. A campaign that has reached its end date keeps `ENABLED`.
`campaign.serving_status`	`SERVING`, `ENDED`	`ENDED` once `campaign.end_date` is in the past.
`campaign.start_date`	`YYYY-MM-DD`	First day the campaign could serve.
`campaign.end_date`	`YYYY-MM-DD`	`2037-12-30` means "no end date" (the Google Ads convention).

Paused or ended campaigns, ad groups and ads still appear when you query attributes only. They disappear from metric queries for the dates they did not serve, because rows with zero activity are omitted (see Reporting).