gads_auth: Authorization in Google Ads API

Description

Authorize rgoogleads to view and manage your Google Ads Account. This function is a wrapper around gargle::token_fetch().

By default, you are directed to a web browser, asked to sign in to your Google account, and to grant rgoogleads permission to operate on your behalf with Google Ads. By default, with your permission, these user credentials are cached in a folder below your home directory, from where they can be automatically refreshed, as necessary. Storage at the user level means the same token can be used across multiple projects and tokens are less likely to be synced to the cloud by accident.

Usage

gads_auth(
  email = gargle::gargle_oauth_email(),
  path = NULL,
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  developer_token = getOption("gads.developer.token"),
  token = NULL
)

Value

Token2.0

Arguments

email: Optional. Allows user to target a specific Google identity.
path: Path to JSON file with identifying the service account
cache: Specifies the OAuth token cache.
use_oob: Whether to prefer "out of band" authentication.
developer_token: Your Google Ads Developer Token.
token: A token with class Token2.0 or an object of

Details

Most users, most of the time, do not need to call gads_auth() explicitly -- it is triggered by the first action that requires authorization. Even when called, the default arguments often suffice.

However, when necessary, gads_auth() allows the user to explicitly:

Declare which Google identity to use, via an email specification.
Use a service account token or workload identity federation via path.
Bring your own token.
Customize scopes.
Use a non-default cache folder or turn caching off.
Explicitly request out-of-band (OOB) auth via use_oob.

If you are interacting with R within a browser (applies to RStudio Server, Posit Workbench, Posit Cloud, and Google Colaboratory), you need OOB auth or the pseudo-OOB variant. If this does not happen automatically, you can request it explicitly with use_oob = TRUE or, more persistently, by setting an option via options(gargle_oob_default = TRUE).

The choice between conventional OOB or pseudo-OOB auth is determined by the type of OAuth client. If the client is of the "installed" type, use_oob = TRUE results in conventional OOB auth. If the client is of the "web" type, use_oob = TRUE results in pseudo-OOB auth. Packages that provide a built-in OAuth client can usually detect which type of client to use. But if you need to set this explicitly, use the "gargle_oauth_client_type" option:

options(gargle_oauth_client_type = "web")       # pseudo-OOB
# or, alternatively
options(gargle_oauth_client_type = "installed") # conventional OOB

For details on the many ways to find a token, see gargle::token_fetch(). For deeper control over auth, use gads_auth_configure() to bring your own OAuth client or API key. To learn more about gargle options, see gargle::gargle_options.

Examples

Run this code

if (FALSE) {
## load/refresh existing credentials, if available
## otherwise, go to browser for authentication and authorization
gads_auth()

## force use of a token associated with a specific email
gads_auth(email = "yourname@example.com")

## force a menu where you can choose from existing tokens or
## choose to get a new one
gads_auth(email = NA)

## -----------------------
## use own developer token
gads_auth(
    email = "yourname@example.com",
    developer_token = "your developer token"
)

## -----------------------
## use own OAuth client app
gads_auth_configure(
    path = "path/to/your/oauth_client.json"
)

gads_auth(email = "yourname@example.com")
}