Começar

É possível usar a API Google Ad Manager para criar apps que gerenciam inventário, criam pedidos, geram relatórios e muito mais.

A API Ad Manager usa o seguinte protocolo: Para ajudar você a começar, oferecemos bibliotecas de cliente para Java, .NET, Python, PHP e Ruby.

Para fazer sua primeira solicitação de API, siga estas etapas:

Acessar uma rede do Ad Manager

Se você ainda não tiver uma, inscreva-se para criar uma conta do Ad Manager. Também é possível criar uma rede de teste para testar a API em um ambiente separado. Você não precisa de uma conta do Google AdSense para fins de teste.

Anote seu código de rede. Você pode encontrá-lo no URL ao fazer login na sua rede. Por exemplo, no URL https://admanager.google.com/1234#home, 1234 é o código de rede.

Criar credenciais de autenticação

É preciso autenticar todas as solicitações da API Ad Manager usando o OAuth 2.0. As etapas abaixo abrangem o caso de uso de acesso aos seus próprios dados do Ad Manager. Para mais detalhes e outras opções, consulte Autenticação.

  1. Abra a página de credenciais do Console de APIs do Google

  2. No menu do projeto, escolha Criar projeto, insira um nome para ele e, se quiser, edite o ID fornecido. Clique em Criar.

  3. Na página "Credenciais", selecione Criar credenciais e, em seguida, Chave da conta de serviço.

  4. Selecione Nova conta de serviço e JSON como o tipo de chave.

  5. Clique em Criar para fazer o download de um arquivo que contém uma chave privada.

Configurar a rede do Ad Manager

  1. Faça login no Google Ad Manager.

  2. Na barra lateral, clique em Administrador > Configurações globais.

  3. Em Configurações gerais > Acesso à API, clique no controle deslizante para Ativado.

  4. Clique no botão Salvar na parte inferior da página.

Configurar seu cliente

Faça o download de uma das bibliotecas de cliente do Ad Manager. As bibliotecas oferecem funções e recursos de wrapper que facilitam e agilizam o desenvolvimento de apps.

As guias abaixo fornecem guias de início rápido para codificação em cada uma das linguagens para as quais existe uma biblioteca de cliente.

Java

Este é um exemplo básico que mostra como usar a biblioteca de cliente Java. Para informações de uso mais detalhadas, consulte o arquivo README na distribuição da biblioteca de cliente.

  1. Configurar suas credenciais

    Execute o seguinte comando em um shell:

    curl https://raw.githubusercontent.com/googleads/googleads-java-lib/main/examples/admanager_axis/src/main/resources/ads.properties -o ~/ads.properties
    Abra o arquivo ~/ads.properties e preencha os seguintes campos:
    [...]
    api.admanager.applicationName=INSERT_APPLICATION_NAME_HERE
    api.admanager.jsonKeyFilePath=INSERT_PATH_TO_JSON_KEY_FILE_HERE
    api.admanager.networkCode=INSERT_NETWORK_CODE_HERE
    [...]
  2. Especificar dependências

    Edite seu arquivo pom.xml e adicione o seguinte à tag dependencies. Confira o número da versão mais recente no GitHub (em inglês).

    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>ads-lib</artifactId>
      <version>RELEASE</version>
    </dependency>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>dfp-axis</artifactId>
      <version>RELEASE</version>
    </dependency>

  3. Escreva algum código e faça uma solicitação.

    import com.google.api.ads.common.lib.auth.OfflineCredentials;
    import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
    import com.google.api.ads.admanager.axis.factory.AdManagerServices;
    import com.google.api.ads.admanager.axis.v202402.Network;
    import com.google.api.ads.admanager.axis.v202402.NetworkServiceInterface;
    import com.google.api.ads.admanager.lib.client.AdManagerSession;
    import com.google.api.client.auth.oauth2.Credential;
    
    public class App {
      public static void main(String[] args) throws Exception {
        Credential oAuth2Credential = new OfflineCredentials.Builder()
            .forApi(Api.AD_MANAGER)
            .fromFile()
            .build()
            .generateCredential();
    
        // Construct an AdManagerSession.
        AdManagerSession session = new AdManagerSession.Builder()
            .fromFile()
            .withOAuth2Credential(oAuth2Credential)
            .build();
    
        // Construct a Google Ad Manager service factory, which can only be used once per
        // thread, but should be reused as much as possible.
        AdManagerServices adManagerServices = new AdManagerServices();
    
        // Retrieve the appropriate service
        NetworkServiceInterface networkService = adManagerServices.get(session,
            NetworkServiceInterface.class);
    
        // Make a request
        Network network = networkService.getCurrentNetwork();
    
        System.out.printf("Current network has network code '%s' and display" +
            " name '%s'.%n", network.getNetworkCode(), network.getDisplayName());
      }
    }
    

Python

Este é um exemplo básico que mostra como usar a biblioteca do cliente Python. A biblioteca de cliente do Python é compatível com o Python v3.6+. Para informações de uso mais detalhadas, consulte o arquivo README na distribuição da biblioteca de cliente.

  1. Instale a biblioteca e configure suas credenciais.

    Execute os comandos abaixo em um shell:

    pip install googleads
    curl https://raw.githubusercontent.com/googleads/googleads-python-lib/main/googleads.yaml \
         -o ~/googleads.yaml
    
  2. Configure o arquivo ~/googleads.yaml.

    Preencha os campos a seguir:

    ad_manager:
      application_name: INSERT_APPLICATION_NAME_HERE
      network_code: INSERT_NETWORK_CODE_HERE
      path_to_private_key_file: INSERT_PATH_TO_FILE_HERE
    
  3. Execute um código e faça uma solicitação.
    # Import the library.
    from googleads import ad_manager
    
    # Initialize a client object, by default uses the credentials in ~/googleads.yaml.
    client = ad_manager.AdManagerClient.LoadFromStorage()
    
    # Initialize a service.
    network_service = client.GetService('NetworkService', version='v202402')
    
    # Make a request.
    current_network = network_service.getCurrentNetwork()
    
    print("Current network has network code '%s' and display name '%s'." %
            (current_network['networkCode'], current_network['displayName']))
    

PHP

Este é um exemplo básico de como usar a biblioteca do cliente PHP.

  1. Instale a biblioteca e configure suas credenciais.

    Execute os seguintes comandos em um shell para instalar a biblioteca de cliente e fazer o download do arquivo adsapi_php.ini para o diretório principal:

    composer require googleads/googleads-php-lib
    curl https://raw.githubusercontent.com/googleads/googleads-php-lib/main/examples/AdManager/adsapi_php.ini -o ~/adsapi_php.ini
  2. Configure o arquivo ~/adsapi_php.ini.

    Preencha os campos a seguir:

    [AD_MANAGER]
    networkCode = "INSERT_NETWORK_CODE_HERE"
    applicationName = "INSERT_APPLICATION_NAME_HERE"
    
    [OAUTH2]
    jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
    scopes = "https://www.googleapis.com/auth/dfp"
    
  3. Execute um código e faça uma solicitação.
    <?php
    require 'vendor/autoload.php';
    use Google\AdsApi\AdManager\AdManagerSession;
    use Google\AdsApi\AdManager\AdManagerSessionBuilder;
    use Google\AdsApi\AdManager\v202402\ApiException;
    use Google\AdsApi\AdManager\v202402\ServiceFactory;
    use Google\AdsApi\Common\OAuth2TokenBuilder;
    
    // Generate a refreshable OAuth2 credential for authentication.
    $oAuth2Credential = (new OAuth2TokenBuilder())
        ->fromFile()
        ->build();
    // Construct an API session configured from a properties file and the OAuth2
    // credentials above.
    $session = (new AdManagerSessionBuilder())
        ->fromFile()
        ->withOAuth2Credential($oAuth2Credential)
        ->build();
    
    // Get a service.
    $serviceFactory = new ServiceFactory();
    $networkService = $serviceFactory->createNetworkService($session);
    
    // Make a request
    $network = $networkService->getCurrentNetwork();
    printf(
        "Network with code %d and display name '%s' was found.\n",
        $network->getNetworkCode(),
        $network->getDisplayName()
    );
    

.NET

Este é um exemplo básico que mostra como usar a biblioteca de cliente.NET

  1. Criar um novo projeto

    Abra o Visual Studio e crie um novo projeto (aplicativo Console).

  2. Adicionar ao projeto as referências de biblioteca necessárias

    Adicione uma dependência nuget para Google.Dfp.

  3. Configurar App.config

    Copie src\App.config para o diretório do projeto e adicione-o ao projeto. Se o aplicativo tem seu próprio App.config, você pode copiar os seguintes nós para seu App.config:

    • configuração/AdManagerApi
    • configuration/configSections/section[name="AdManagerApi"]
    • configuração/system.net
  4. Configurar credenciais

    Abra App.config e edite as seguintes chaves:

    <add key="ApplicationName" value="INSERT_YOUR_APPLICATION_NAME_HERE" />
    <add key="NetworkCode" value="INSERT_YOUR_NETWORK_CODE_HERE" />
    <add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
    <add key="OAuth2SecretsJsonPath" value="INSERT_OAUTH2_SECRETS_JSON_FILE_PATH_HERE" />
    

  5. Fazer uma chamada para a biblioteca

    É possível chamar a biblioteca conforme mostrado no seguinte snippet de código C#:

    AdManagerUser user = new AdManagerUser();
          using (InventoryService inventoryService = user.GetService<InventoryService>())
                {
                    // Create a statement to select ad units.
                    int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
                    StatementBuilder statementBuilder =
                        new StatementBuilder().OrderBy("id ASC").Limit(pageSize);
    
                    // Retrieve a small amount of ad units at a time, paging through until all
                    // ad units have been retrieved.
                    int totalResultSetSize = 0;
                    do
                    {
                        AdUnitPage page =
                            inventoryService.getAdUnitsByStatement(statementBuilder.ToStatement());
    
                        // Print out some information for each ad unit.
                        if (page.results != null)
                        {
                            totalResultSetSize = page.totalResultSetSize;
                            int i = page.startIndex;
                            foreach (AdUnit adUnit in page.results)
                            {
                                Console.WriteLine(
                                    "{0}) Ad unit with ID \"{1}\" and name \"{2}\" was found.", i++,
                                    adUnit.id, adUnit.name);
                            }
                        }
    
                        statementBuilder.IncreaseOffsetBy(pageSize);
                    } while (statementBuilder.GetOffset() < totalResultSetSize);
    
                    Console.WriteLine("Number of results found: {0}", totalResultSetSize);
                }
            

Se você não quiser definir suas credenciais na App.config, consulte este artigo da wiki para formas alternativas de usar a classe AdManagerUser. Para informações mais detalhadas sobre o uso da biblioteca de cliente .NET, consulte o README . Se você quiser desenvolver em .NET sem a biblioteca do cliente, consulte o artigo da wiki NoClientLibrary.

Ruby

Este é um exemplo básico que mostra como usar a biblioteca de cliente Ruby. A biblioteca de cliente do Ruby requer o Ruby 2.1 ou posterior.

  1. Instale a gem do Ruby e consiga o arquivo de configuração.

    Execute os comandos abaixo em um shell:

    gem install google-dfp-api
    curl https://raw.githubusercontent.com/googleads/google-api-ads-ruby/main/ad_manager_api/ad_manager_api.yml -o ~/ad_manager_api.yml
    
  2. Configurar suas credenciais

    Preencha os campos obrigatórios no arquivo ~/ad_manager_api.yml. Se você ainda não tiver um arquivo de chave OAuth2, siga as etapas para criar suas credenciais do OAuth2.

    :authentication:
      :oauth2_keyfile: INSERT_PATH_TO_JSON_KEY_FILE_HERE
      :application_name: INSERT_APPLICATION_NAME_HERE
      :network_code: INSERT_NETWORK_CODE_HERE
    
  3. Escreva algum código e faça uma solicitação.
    # Import the library.
    require 'ad_manager_api'
    
    # Initialize an Ad Manager client instance (uses credentials in ~/ad_manager_api.yml by default).
    ad_manager = AdManagerApi::Api.new
    
    # Get a service instance.
    network_service = ad_manager.service(:NetworkService, :v202402)
    
    # Make a request.
    network = network_service.get_current_network()
    
    puts "The current network is %s (%d)." %
            [network[:display_name], network[:network_code]]
    

Etapas mais detalhadas para começar podem ser encontradas no arquivo README (em inglês) distribuído com a biblioteca de cliente do Ruby. Além disso, confira nossa biblioteca de exemplo completa para Ruby.

Próximas etapas

Quando uma biblioteca de cliente estiver funcionando, modifique os exemplos fornecidos para ampliá-los de acordo com suas necessidades.

Confira a documentação de referência para saber mais sobre a API.

Se você precisar de ajuda, acesse a página de suporte.