Skip to main content

Google Ads

Fancified

Google Ads for fancy-flow — as four imported, versioned packages, one per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs change.

Runtime Package Install
Authoring surface (every host) @particle-academy/google-ads-ui npm install @particle-academy/google-ads-ui
Node @particle-academy/google-ads-js npm install @particle-academy/google-ads-js
PHP 8.4+ particle-academy/google-ads-php composer require particle-academy/google-ads-php
Python 3.11+ fancy-google-ads pip install fancy-google-ads

The ui package is the editor surface and is React on every host — a PHP or Python project installs it and its own runtime package, and never the js one.

What it costs you

One dependency: @particle-academy/fancy-connector-core (or particle-academy/fancy-connector-core on Composer), which the js and php packages pull in themselves. The Python package has zero runtime dependencies.

No Google Ads SDK. Plain HTTP, deliberately: a vendor SDK is third-party code subject to the kit's full approval bar, and one per provider is hundreds of dependencies nobody is tracking.

Setting it up

Everything below is generated from provider/manifest.json, so it cannot disagree with what the packages do.

Credentials

A Google Ads connection holds 6 values.

Two kinds of value, and mixing them up matters. A provider credential is ONE value for the whole installation — an OAuth app's client secret serves every connected account. An account credential is one per connected account. A host that stores the second where it stores the first lets one account's credentials reach another's.

Field Scope Secret Where it comes from
OAuth client ID per installation not secret The Google Cloud OAuth client shared by the installation.
OAuth client secret per installation secret The matching Google Cloud OAuth client secret.
Developer token per installation secret The 22-character Google Ads API developer token from the manager account's API Center. Google says to treat it like a password; one token identifies the installed application.
Access token per connected account secret The connected Google user's one-hour OAuth access token.
Refresh token per connected account secret The reusable offline token used to replace expired access tokens.
Manager customer ID (optional) per connected account not secret Optional. The manager account's 10-digit customer ID without hyphens. Required when the OAuth user reaches a client through that manager; omit it for direct access.

Every request carries developer-token and login-customer-id (when set) alongside the primary authorization, filled from the credentials above.

Authorising

Google Ads uses OAuth2 (authorization_code). The package DECLARES the exchange; the HOST performs it — a consent screen needs a browser, a redirect URI and somewhere to persist the result, and all three belong to the host.

One consent grant, shared (grant: "google"). Every connector declaring the same grant can run on ONE OAuth client, with one consent and one refresh token per person.

  • Authorize with access_type=offline, include_granted_scopes=true. Ask for a feature's scopes when it is first used; the new token covers every scope granted before. A refresh token comes back only on the FIRST exchange, so keep the stored one when an exchange returns none.
  • Revoke — POST https://oauth2.googleapis.com/revoke with token. It removes the WHOLE grant: every connector sharing it, not only this one. A per-feature disconnect stops using that feature's scopes locally; only a full disconnect revokes.
  • Identify the account by sub: request openid, then verify the token response's id_token (issuer https://accounts.google.com or accounts.google.com, keys at https://www.googleapis.com/oauth2/v3/certs, audience = clientId). Never key a connection by email.
  • No restricted scopes in this connector.

The refresh tokens do not rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.

The estate

Google Ads has a test estate on the same host, reached with credentials from a SEPARATE test account you register. Selecting sandbox mode uses those credentials.

Use a dedicated Google Ads test manager and test client account. Test and production hierarchies cannot interact; test ads never serve or incur cost, but some features such as billing, conversion uploads and serving reports cannot be exercised there.

What it can do

Actions

customer_list_accessible — Accessible Google Ads customers

List Google Ads customer resource names directly accessible to the authenticated user. Manager-linked client accounts are not included; query the account hierarchy after choosing a directly accessible manager.

GET /v25/customers:listAccessibleCustomers · reads only — safe to replay

Takes no input.

Run it before you have credentials

Every operation ships a faker, whether or not Google Ads has a sandbox. Set a node's mode to fake and it returns the shape Google Ads actually publishes — the same field names, deterministically — so you can wire the downstream nodes before touching an account, a key, or a network.

This repository is generated

provider/ is the source. Everything under packages/ is emitted from it and must not be hand-edited — CI regenerates and diffs on every push, and the next protocol sync destroys anything it finds. See AGENTS.md.

Two namespaces, which do not match on purpose

The repo is github.com/Fancy-Friends/google-ads; the packages publish under particle-academy. Nothing derives one from the other — the names come from weaver's friends.json and nowhere else.

Licence

MIT.

Metadata

Release files for fancy-google-ads 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fancy-google-ads 0.3.1
File Size Uploaded Provenance Actions
fancy_google_ads-0.3.1.tar.gz 21.3 kB Without provenance Details for fancy_google_ads-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fancy-google-ads 0.3.1
File Interpreter ABI Platform Actions
fancy_google_ads-0.3.1-py3-none-any.whl Python 3 none any Details for fancy_google_ads-0.3.1-py3-none-any.whl

Total release size: 42.6 kB

Release files / fancy_google_ads-0.3.1.tar.gz

Download URL fancy_google_ads-0.3.1.tar.gz
Size 21.3 kB
Tags Source
SHA-256 checksum
How to use checksums
8ba5c7776e4420105daf5828e9c6579021d79968c203e9c16c1364e2f6358151
BLAKE2b-256 checksum
How to use checksums
0f45700aec4bd2acd41e151a7548d336d461d23ba67ea9582abc3b5d97999912
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / fancy_google_ads-0.3.1-py3-none-any.whl

Download URL fancy_google_ads-0.3.1-py3-none-any.whl
Size 21.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cac9bc79f100d2fa83c89647d44315a30f7f9ed0b74900694b7a7ae6620952e5
BLAKE2b-256 checksum
How to use checksums
824d91c543d86a9a72ac069afd82966c35175c6d44efafbbae1b0f37db3edbfc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Security for fancy-google-ads 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page