Google’s Ad Manager is a comprehensive hosted ad serving platform that streamlines your ad management functions and allows you to generate even-greater advertising margins. It offers publishers a complete ad revenue engine, helping publishers streamline operations and capture the most value for every impression.


Google Ad Manager Connector v1.0.0

The Anypoint Connector for Google Ad Manager enables publishers and third-parties to consume the Google Ad Manager API to help them grow, sell, schedule, deliver, and measure their digital ad inventory on Google Ad Manager through Mule.

The Anypoint Connector for Google Ad Manager allows one to easily build Mule applications to consume the following services of the Google Ad Manager API: Company, Contact, Inventory, Line Item, Order, User, Report, Custom Field, Custom Targeting, Forecast, Placement, and PQL.

MuleSoft maintains the connector under the Certified support policy.


Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and Anypoint Studio. To increase your familiarity with Studio, consider completing a Anypoint Studio Overview. This page requires some basic knowledge of Mule Concepts, Elements in a Mule Flow.

To use the this connector, you will need an account on the Google Ad Manager website. Click on this link to obtain a Google Ad Manager account and the necessary authentication credentials (OAuth/Service Account).

You will also require Anypoint Studio downloaded and installed on your development machine.


Hardware and Software Requirements

For hardware and software requirements, please visit the Hardware and Software Requirements page.

Compatibility

Software Version

Mule Runtime

EE 4.1.x+

Java

8+

Google Ad Manager

v201902


How to Install

You can install the connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

How to Configure

To use the Google Ad Manager connector in your Mule application, you must configure a global Google Ad Manager element with the following two global configurations:

1. OAuth Authentication

  1. Click the Global Elements tab at the base of the canvas, then click Create.

  2. In the Choose Global Type menu, use the filter to locate and select Google Ad Manager Config, then click OK.

  3. Configure the parameters according to the following table:

    Parameter Description

    Name

    Name for the configuration so it can be referenced later.

    Application Name

    Name of your application chosen in the API console.

    Client Id

    Client ID for your Google Ad Manager application created in the API console.

    Client Secret

    Corresponding client secret.

    Endpoint

    Ad Manager API end point server (Optional).

    Network Code

    Header networkCode associated with your application created in the API console.

    Refresh Token

    Refresh token.

    Token Server Url

    Ad Manager API token server URL (Optional).

    oauth config

2. Service Account Authentication

  1. Click the Global Elements tab at the base of the canvas, then click Create.

  2. In the Choose Global Type menu, use the filter to locate and select Google Ad Manager Config, then click OK.

  3. Configure the parameters according to the following table:

    Parameter Description

    Name

    Name for the configuration so it can be referenced later.

    Application Name

    Name of your application chosen in the Google Ad Manager API console.

    JSON Key File Path

    File path for your Google Ad Manager application JSON Key.

    Endpoint

    Google Ad Manager API end point server (Optional).

    Network Code

    Header networkCode associated with your application created in the API console.

    Token Server URL

    Google Ad Manager API token server URL (Optional).

    service account config

Required Connector Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

Tip
If you are manually coding the Mule application in Studio’s XML editor or other text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag.
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:google-ad-manager="http://www.mulesoft.org/schema/mule/google-ad-manager"
      xsi:schemaLocation="
              http://www.mulesoft.org/schema/mule/core
              http://www.mulesoft.org/schema/mule/core/current/mule.xsd
              http://www.mulesoft.org/schema/mule/google-ad-manager
              http://www.mulesoft.org/schema/mule/google-ad-manager/current/mule-google-ad-manager.xsd">
      <!-- put your global configuration elements and flows here -->
</mule>

Maven Dependency Information

The following XML snippet must be included in your pom.xml file:

<dependency>
    <groupId>com.rictson</groupId>
    <artifactId>google-ad-manager-connector-mule4</artifactId>
    <version>1.0.0</version>
    <classifier>mule-plugin</classifier>
</dependency>

Common Use Cases

Create Company

The following walkthrough describes a simple procedure to use the connector and create a company on Google Ad Manager.

usecase createcompany 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /createCompany

    Port

    8081

    Method

    POST

  2. Select the Google Ad Manager from the Mule Pallette and then drag the Create endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase createcompany 02
  3. To create a new Google Ad Manager Company object, add a Transform Message transformer after HTTP endpoint. Map the JSON payload as follows:

    usecase createcompany 03

    Since internally the Google Ad Manager library uses a Java class to represent an Enum, the following DataWeave function should be defined (inline or in a separate .dwl file) to convert an Enum to a Company object:

        %dw 2.0
        import java!com::google::api::ads::admanager::axis::v201902::CompanyType
    
        fun stringToCompanyType(enumString) =
          CompanyType::fromString(upper(enumString))
  4. Add another Transform Message transformer after the Google Ad Manager endpoint to map the payload object (e.g. List<Long> for Companies) to a JSON object as follows:

    usecase createcompany 04
  5. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  6. Make a POST request to: http://localhost:8081/createCompany with a suitable body:

        {
          "Companies":
          [
            {
              "companyName": "demoCompany",
              "companyAddress": "12, John Doe Street, Birkirkara BKR1234",
              "companyEmail": "hello@democompany.com",
              "companyType": "Agency"
            }
          ]
        }
  7. The Mule application will add the respective Company record to Google Ad Manager and return the created object ID in JSON format.

Get a Company

The following walkthrough describes a simple procedure to use the connector and retrieve a company record from Google Ad Manager.

usecase getcompany 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /getCompany/{companyId}

    Port

    8081

    Method

    GET

  2. Select the Google Ad Manager from the Mule Pallette and then drag the Get endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase getcompany 02
  3. In the Query Params field, select Edit inline. Click the + sign to create a new object and configure it as follows:

    usecase getcompany 03
  4. Add an Transform Message transformer after the Google Ad Manager connector endpoint to convert to payload to a JSON object (output application/json).

  5. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  6. Make a GET request to: http://localhost:8081/getCompany/1234. Here 1234 refers to the ID of the company you are trying to retrieve.

  7. The Mule application will retrieve the respective company and its information as JSON.

Update a Company

The following walkthrough describes a simple procedure to use the connector to update a Company record on Google Ad Manager.

usecase updatecompany 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /updateCompany

    Port

    8081

    Method

    PUT

  2. Add a Transform Message transformer after the HTTP endpoint to create a new Google Ad Manager Company to pass to the connector as payload. In the Transform Message properties view, map a JSON object to a Company object and assign the respective values.

    usecase updatecompany 02
  3. Select the Google Ad Manager from the Mule Pallette and then drag the Update endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase updatecompany 03
  4. Add another Transform Message transformer after the Google Ad Manager connector endpoint to transform the Google Company object into JSON object.

  5. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  6. Make a PUT request to: http://localhost:8081/updateCompany with a suitable body:

        {
          "Companies":
          [
            {
            "companyId": "12345",
            "companyEmail" : "updatedcompanyemail@mycompany.com",
            "companyName": "updatedCompany",
            "companyAddress": "60, John Doe Street, Birkirkara BKR1234"
            }
          ]
        }
  7. The Mule application will update the respective company record and return its ID.

Create a Report

The following walkthrough describes a simple procedure to use the connector and create a report on Google Ad Manager.

usecase createreport 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /createReport

    Port

    8081

    Method

    POST

  2. Add a Transform Message transformer after HTTP endpoint to create a new Report object to pass on to the connector as payload.

    usecase createreport 02
  3. Select the Google Ad Manager from the Mule Pallette and then drag the Create Report endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase createreport 03
  4. Add another Transfrom Message transformer after the Google Ad Manager connector endpoint to transform the Report object into JSON data.

  5. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  6. Make a POST request to: http://localhost:8081/createReport with a suitable body:

        {
          "Report": {
            "dimensions": "LINE_ITEM_ID,MONTH_AND_YEAR",
            "columns": "AD_SERVER_IMPRESSIONS",
            "dimensionAttributes": null,
            "startDate": "2017-01-01",
            "endDate": "2019-01-31"
          }
        }
  7. The Mule application will create the report and return its contents.

Create and Download a Report

The following walkthrough describes a simple procedure to use the connector to create a report and then retrieve it as an XML file.

usecase downloadrep 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /createDownload

    Port

    8081

    Method

    GET

  2. Add a Transform Message transformer to map the data to a Java object.

    usecase downloadrep 02
  3. Select the Google Ad Manager from the Mule Pallette and then drag the Create Report endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase downloadrep 03
  4. From the Mule Pallette drag the Download Report endpoint and configure it as follows:

    usecase downloadrep 04
  5. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  6. Make a GET request to: http://localhost:8081/createDownload.

  7. The Mule application will create the report and provide a link to download it in XML format.

Get Report Download URL

The following walkthrough describes a simple procedure to use the connector and retrieve a report by obtaining a download URL.

usecase reporturl 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /reportUrl/{reportId}

    Port

    8081

    Method

    GET

  2. Select the Google Ad Manager from the Mule Pallette and then drag the Get Report Download Url endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase reporturl 02

    Since internally the Google Ad Manager library uses a Java class to represent an Enum, a DataWeave function containing the following code should be defined (inline or in a new .dwl file):

        %dw 2.0
        import java!com::google::api::ads::admanager::axis::v201902::ExportFormat
    
        fun stringToExportFormat(enumString) =
          ExportFormat::fromString(upper(enumString))
  3. Add a Transform Message transformer after the Google Ad Manager connector endpoint and modify it as follows:

    usecase reporturl 03
  4. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  5. Make a GET request to: http://localhost:8081/reportUrl/1234. Here 1234 refers to the ID of the report you are trying to retrieve.

  6. The Mule application will return the download URL for the requested report.

Select PQL

This walkthrough describes a procedure to retrieve reports using a PQL statement from Google Ad Manager.

usecase pql 01
  1. Drag an HTTP Listener endpoint into a new flow. In the properties view of the HTTP Listener endpoint configure it as follows:

    Field

    Value

    Display Name

    HTTP (or any other name you prefer)

    Path

    /pql/{reportId}

    Port

    8081

    Method

    GET

  2. Select the Google Ad Manager from the Mule Pallette and then drag the Select PQL endpoint into the same flow. Select it to open its properties editor. Next to Connector Configuration click the + sign to add a new connection configuration or choose one from the list. Set the remaining properties as follows:

    usecase pql 02
  3. In the Query Params field, select Edit inline and click the + sign to configure a new parameter. Configure it follows:

    usecase pql 03
  4. Add an Transform Message transformer after the Google Ad Manager connector endpoint and configure it to convert the payload to a JSON object.

  5. Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).

  6. Make a GET request to: http://localhost:8081/pql/1234. Here 1234 refers to the ID of the report you are trying to retrieve.

  7. The Mule application will return the query results.

Supported Operations

Operations that are Currently Supported (ordered by Service):

  • Company Service:

    • Create Companies

    • Get Companies

    • Update Companies

  • Contact Service:

    • Create Contacts

    • Get Contacts

    • Update Contacts

  • Custom Field Service:

    • Create Custom Field Options

    • Create Custom Field

    • Get Custom Fields

    • Get Custom Field Option

    • Perform Custom Field Action

    • Update Custom Field Option

    • Update Custom Fields

  • Custom Targeting Service:

    • Create Custom Targeting Keys

    • Create Custom Targeting Values

    • Get Custom Targeting Keys

    • Get Custom Targeting Values

    • Perform Custom Targeting Keys

    • Perform Custom Targeting Values

    • Update Custom Targeting Keys

    • Update Custom Targeting Values

  • Forecast Service:

    • Get Availability Forecast

    • Get Availability Forecast by ID

    • Get Delivery Forecast

    • Get Delivery Forecast by ID

  • Inventory Service (Ad Units):

    • Create Ad Units

    • Get Ad Units

    • Get Ad Unit Sizes

    • Perform Ad Units

    • Update Ad Units

  • Line Item Service:

    • Create Line Items

    • Get Line Items

    • Perform Line Items

    • Update Line Items

  • Order Service:

    • Create Orders

    • Get Orders

    • Perform Orders Action

    • Update Orders

  • Placement Service:

    • Create Placements

    • Get Placements

    • Perform Placements

    • Update Placements

  • Publisher Query Language Service:

    • Select PQL

  • Report Service:

    • Create Report Asynchronously

    • Create Report Synchronously

    • Download Report

    • Get Report Download URL With Options

    • Get Report Status

    • Get Saved Queries by Statement

  • User Service:

    • Create Users

    • Get All Roles

    • Get Current User

    • Get Users

    • Perform Users

    • Update Users

Resources