Authentication

Assim como outras APIs do Google, a API Google Ads usa o protocolo OAuth 2.0 para autenticação e autorização. O OAuth 2.0 permite que seu aplicativo cliente da API Google Ads acesse a conta de um usuário sem precisar processar ou armazenar as informações de login dele.

Entender o modelo de acesso do Google Ads

Para trabalhar de forma eficaz com a API Google Ads, entenda como funciona o modelo de acesso do Google Ads. Consulte o guia do modelo de acesso do Google Ads.

Fluxos de trabalho do OAuth

Existem três fluxos de trabalho comuns usados ao trabalhar com a API Google Ads.

Fluxo da conta de serviço

Esse é o fluxo de trabalho recomendado se o seu não exigir interação humana. Esse fluxo de trabalho exige uma etapa de configuração em que o usuário adiciona uma conta de serviço à conta do Google Ads. Em seguida, o app pode usar as credenciais da conta de serviço para gerenciar a conta do Google Ads do usuário.

A biblioteca PHP pode ser configurada da seguinte maneira:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Consulte o guia de fluxo de trabalho da conta de serviço para saber mais.

Fluxo de autenticação de usuário único

Esse fluxo de trabalho pode ser usado se você não puder usar contas de serviço. Esse fluxo de trabalho exige duas etapas de configuração:

1. Dê a um único usuário acesso a todas as contas que serão gerenciadas usando a API Google Ads. Uma abordagem comum é dar ao usuário acesso a uma conta de administrador da API Google Ads e vincular todas as contas do Google Ads a ela.
2. Em seguida, esse usuário executa uma ferramenta de linha de comando, como GenerateUserCredentials, para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

A biblioteca pode ser inicializada usando as credenciais OAuth 2.0 do usuário da seguinte forma:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

Consulte o guia do fluxo de trabalho de autenticação de usuário único para saber mais.

Fluxo de autenticação multiusuário

Esse é o fluxo de trabalho recomendado se o app permitir que os usuários façam login e autorizem o app a gerenciar as contas do Google Ads em nome deles. Seu app cria e gerencia dinamicamente as credenciais de usuário do OAuth 2.0 para cada sessão de usuário autenticado. A biblioteca pode ser inicializada usando as credenciais do usuário conectado da seguinte maneira:

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId($userLoginCustomerId)
    ->build();

Consulte o guia do fluxo de trabalho de autenticação multiusuário para saber mais.

Application Default Credentials

A biblioteca de cliente PHP também oferece suporte à autenticação com Application Default Credentials (ADC). Quando as credenciais do modo de aplicativo (clientId, clientSecret, refreshToken) e do modo de conta de serviço (jsonKeyFilePath) não estão definidas em OAuth2TokenBuilder, a chamada build() volta automaticamente para o Application Default Credentials:

$oAuth2Credential = (new OAuth2TokenBuilder())->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

Gerenciar várias contas

É comum um usuário gerenciar mais de uma conta do Google Ads, seja por acesso direto a elas ou por uma conta de administrador do Google Ads. A biblioteca de cliente PHP fornece os exemplos de código a seguir que ilustram como lidar com esses casos:

1. O exemplo de código GetAccountHierarchy mostra como recuperar a lista de todas as contas em uma conta de administrador do Google Ads.
2. O exemplo de código ListAccessibleCustomers mostra como recuperar a lista de todas as contas a que um usuário tem acesso direto. Essas contas podem ser usadas como valores válidos para a configuração loginCustomerId.