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 (Premium) Connector 4.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, PQL.
MuleSoft maintains the Premium 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 Tutorial. This page requires some basic knowledge of Mule Concepts, Elements in a Mule Flow, and Global Elements.
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 3.6.x+ |
Java |
7+ |
Google Ad Manager |
v201805 |
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 Premium connector in your Mule application, you must configure a global Google Ad Manager Premium element that can be used by the Google Ad Manager Community connector (read more about Global Elements). The Google Ad Manager Premium connector offers the following two global configurations described below.
1. OAuth Authentication
-
Click the Global Elements tab at the base of the canvas, then click Create.
-
In the Choose Global Type menu, use the filter to locate and select Google Ad Manager (Premium): OAuth 2.0, then click OK.
-
Configure the parameters according to the table below.
Parameter Description Name
Name for the configuration so it can be referenced later.
Client Id
Client ID for your Google Ad Manager application created in the API console.
Client Secret
Corresponding client secret.
Application Name
Name of your application chosen in the API console.
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).
2. Service Account Authentication
-
Click the Global Elements tab at the base of the canvas, then click Create.
-
In the Choose Global Type menu, use the filter to locate and select Google Ad Manager (Premium): Service Account, then click OK.
-
Configure the parameters according to the table below.
Parameter Description Name
Name for the configuration so it can be referenced later.
JSON Key File Path
File path for your Google Ad Manager application JSON Key.
Application Name
Name of your application chosen in the Google Ad Manager API console.
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).
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.
Schema Location: http://www.mulesoft.org/schema/mule/google-ad-manager-premium/current/mule-google-ad-manager-premium.xsd
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-premium="http://www.mulesoft.org/schema/mule/google-ad-manager-premium"
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-premium
http://www.mulesoft.org/schema/mule/google-ad-manager-premium/current/mule-google-ad-manager-premium.xsd">
<!-- put your global configuration elements and flows here -->
</mule>
Maven Dependency Information
If Maven is backing the application, this XML snippet must be included in your pom.xml
file.
<dependency>
<groupId>org.mule.modules</groupId>
<artifactId>google-ad-manager-connector-premium</artifactId>
<version>4.0.0</version>
</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.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/createCompany
Port
8081
Method
POST
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows: -
Add a Dataweave transformer after HTTP endpoint to create a new Google Company to pass on to the connector. Do the mapping from a JSON object to a Google Company object to assign the values.
Since internally the Google Ad Manager library uses classes to represent Enum a global MEL function should be defined in the Mule Configuration XML as shown below:
<configuration doc:name="Configuration"> <expression-language> <global-functions> def stringToCompanyType(enumString){ return com.google.api.ads.dfp.axis.v201805.CompanyType.fromString(enumString.toUpperCase()) } </global-functions> </expression-language> </configuration>
-
Add another Dataweave transformer after the Google Ad Manager endpoint to map an object of
List<Long>
returned by the Google Ad Manager to JSON and extract the new company ID. -
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
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" } ] }
-
The Mule application will perform the operation and add the Company record to Google Ad Manager. An ID should be returned 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.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/getCompany/{companyId}
Port
8081
Method
GET
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows: -
In the Query Params field, select Create Object manually. Click the button
…
and in the popup window that opens select the+
sign to create a new object. Configure the new object as follows: -
Add an Object to JSON transformer after the Google Ad Manager connector endpoint.
-
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
Make a GET request to: http://localhost:8081/getCompany/1234. Here 1234 refers to the ID of the company you are trying to retrieve.
-
The Mule application will perform the operation and return JSON data containing information about the company requested.
Update a Company
The following walkthrough describes a simple procedure to use the connector to update a Company record on Google Ad Manager.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/updateCompany
Port
8081
Method
PUT
-
Add a Dataweave transformer after HTTP endpoint to create a new Google Company to pass on to the connector. Do the mapping from a JSON object to a Google Company object to assign the values.
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows: -
Add an Object to JSON transformer after the Google Ad Manager connector endpoint to transform the Google Company object into JSON data.
-
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
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" } ] }
-
The Mule application will perform the operation and return the ID of the update company record.
Create a Report
The following walkthrough describes a simple procedure to use the connector and create a report on Google Ad Manager.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/createReport
Port
8081
Method
POST
-
Add a Dataweave transformer after HTTP endpoint to create a new Report object to pass on to the connector.
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows: -
Add an Object to JSON transformer after the Google Ad Manager connector endpoint to transform the Report object into JSON data.
-
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
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" } }
-
The Mule application will perform the operation and return the contents of the created report.
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.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/createDownload
Port
8081
Method
GET
-
Add a Dataweave transformer to map the data into a Report object. For the purpose of this example, the data for the report we wish to create has been hardcoded.
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows: -
Add another Google Ad Manager (Premium) connector endpoint and configure it with the operations to download a report:
-
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
Make a GET request to: http://localhost:8081/createDownload.
-
The Mule application will perform the operation and the created report should be displayed 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.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/reportUrl/{reportId}
Port
8081
Method
GET
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows:Since internally the Google Ad Manager library uses classes to represent Enum a global MEL function should be defined in the Mule Configuration XML as shown below:
<configuration doc:name="Configuration"> <expression-language> <global-functions> def stringToExportFormat(enumString){ return com.google.api.ads.dfp.axis.v201805.ExportFormat.fromString(enumString.toUpperCase()) } </global-functions> </expression-language> </configuration>
-
Add a Dataweave transformer after the Google Ad Manager connector endpoint and modify it as follows:
-
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
Make a GET request to: http://localhost:8081/reportUrl/1234. Here 1234 refers to the ID of the report you are trying to retrieve.
-
The Mule application will perform the operation and return download URL for the requested report.
Select PQL
This walkthrough describes a procedure to retrieve reports using a PQL statement from Google Ad Manager.
-
Drag an HTTP Endpoint into a new flow. Configure a new HTTP Listener Configuration on Port 8081. In the properties view of the HTTP Endpoint configure the HTTP endpoint as follows:
Field
Value
Display Name
HTTP (or any other name you prefer)
Exchange Pattern
request-response
Path
/pql/{reportId}
Port
8081
Method
GET
-
Drag a Google Ad Manager (Premium) connector endpoint into the same flow. Select it to open the properties editor console. Next to Connector Configuration click the
+
sign to add a new connection configuration and add your credentials. Set the rest of the properties as follows: (For the purpose of demonstrating the operation, the query values have been hardcoded) -
In the Query Params field, select Create Object Manually and click on
…
. In the popup window that appears, click the+
to configure a new Object. Create a new object as follows: -
Add an Object to JSON transformer after the Google Ad Manager connector endpoint.
-
Save the project and then run it as a Mule Application (right-click project name, then select Run As > Mule Application).
-
Make a GET request to: http://localhost:8081/pql/1234. Here 1234 refers to the ID of the report you are trying to retrieve.
-
The Mule application will perform the operation and return the results of the query.
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 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
-
Visit the Google Ad Manager (Premium) Release Notes page for the release notes of the connector.
-
Visit the Google Ad Manager (Premium) Connector API Reference page for the technical documentation of the connector.
-
Visit Google Ad Manager API release notes page for information on Ad Manager v201805 API.
-
Learn how to Install and Configure Anypoint™ Connectors in Anypoint™ Studio here.
-
Access MuleSoft’s forum to pose questions and get help from Mule’s broad community of users.
-
To access MuleSoft’s expert support team, subscribe to Mule ESB Enterprise and log in to MuleSoft’s Customer Portal.
-
Contact the connector developers at Ricston.