This project will teach you how to build a backend for your web app that integrates with Google Ads using Google Ads API. To see the project for the frontend, go here.
See here a 15-minute demo of the product you can have by cloning this repo and following the instructions. Here is a shorter product demo (6 minutes) that shows the flow for users without existing Google Ads accounts.
The main goal of this project is to smooth and accelerate the integration process, while decreasing the cost of implementation & integration.
Companies can use my open-source app and the technical guide I wrote as the entry point to elements within the Google Ads API.
They can learn about what they can do with Google Ads API and get a clear idea of how a finished solution could look like.
If this project helped you, please give it a star.
Give us your feedback here please. Any feature requests, bugs, satisfaction with the project, or others.
Testimonial from a company who used this project:
"We looked at your app in great detail and learnt a lot from it. Your app worked like a charm and gave us a good sense of various components involved. The document you provided was also very helpful. Thank you for putting this together."
-
You already have a Google account. If you haven’t, go here.
-
You already have a Google Ads Manager account. If you haven’t, go here.
-
You already have a basic/standard developer token access. If you haven’t, go here. I have the basic access that gives me 15,000 operations / day (15k resources/day) and 1,000 requests / day, which is more than enough for this tutorial.
-
You know Python, JavaScript, full-stack web development, and APIs.
I’ll use Django (Python framework) for the backend, React (JavaScript framework/library) for the frontend, and Bootstrap for CSS.
Also, I will use environment variables for privacy concerns and ignore the client_secret.json file from my Google Cloud Platform project.
In the main directory, there are two important folders called api and backend, plus the README.md file and the manage.py file. The manage.py file is to use it in the command line (if you are not familiar with Django, read about it).
The backend folder has the settings.py file of the backend app, and the api folder has the files of the api I built for the project, which also includes the files to make API calls to Google Ads.
Important files in the api folder:
- urls.py has the API endpoints for my frontend to communicate with my backend.
- views.py has the functions that will make the API calls to Google.
There are two files that are ignored so you will not see them here, but I have them in my local machine. One is client_secret.json that contains the secret keys of my Google Cloud Platform project. The other one is the db.sqlite3 which is the database file that contains information of my models.
See here a video tutorial on how to set up this web app.
Clone this repo and the repo for the frontend. To install the packages needed for the frontend, follow the instructions in the README file of that repo.
Here are the instructions for the backend.
- Install of dependencies.
pip install -r requirements.txt
-
Get a new secret key for the app.
- Go to MiniWebTool to generate a secret key for the backend app.
- Go to the settings.py file inside the backend folder.
- Replace the secret key value in line #37 for the secret key generated using the web tool.
-
Make the necessary migrations.
python manage.py migrate
- Create a super user to manage the backend.
python manage.py createsuperuser
- Start the backend server.
python manage.py runserver
- Open the backend app in your browser.
localhost:8000/admin/
- You are all set!
You have to create a Google Cloud project and get the necessary credentials to consume Google's APIs.
You need to register your app as a client of Google Ads. You will receive unique client credentials that you will use to authenticate that the one making the calls to the API is your app.
Sign into your Google Cloud Platform console, and go to your project. If you haven’t created one, follow the steps outlined below.
- Go to GCP and go to APIs & Services > Credentials.
- Create a project.
- Click on Create credentials > OAuth client id
- Following the steps, you will be prompted to choose the type of user. Choose ‘External’ as your project will support external users as it is usually the case with our partners.
- Fill out the required fields: App name, User support email, and Email addresses in the Developer contact information section.
- Click on ADD OR REMOVE SCOPES. The scopes that you will need to add depend on if you want to offer Google Business Information (aka Google My Business) or not (see the next sub-section called Google My Business (GMB)). You will definitely use the Google Ads API, so you can add it by copying and pasting the following: https://www.googleapis.com/auth/adwords
- Add your google email address as a user.
- Go again to Credentials > Create credentials > OAuth client id.
- In Application type put ‘Web application’. As stated in the value proposition section, we are not going to create a service account because that is not usually the case for our partners.
- In the Authorized JavaScript origins section and Authorized redirect URIs section, put "http://localhost:8080" in both. This is important because the OAuth flow will redirect you to that URI, and if you don’t include it in the project, you will get an error.
- Download the json file with your credentials (your Client ID, Client Secret, redirect uris, etc.) and save it anywhere in your project.
- Enable the APIs you are going to use (Google Ads API, My Business Business Information API, and My Business Account Management API) by navigating to APIs & Services > Dashboard, in your GCP project and click on ‘ENABLE APIS AND SERVICES’. Use the search bar to find them faster. The OAuth credentials will be the same as the ones you already created for the project.
When you have your OAuth credentials, download the JSON file and save it to your backend folder. That will be the file that stores your client credentials that authenticates your app to Google’s services. That file contains information to link your app with your GCP project. Very important are the client id and client secret that tells Google which app project you are using.
You can use a YAML file to load your credentials, or you can use a dictionary to use it like I did. I recommend you store the values of client secret, client id, developer token, and login customer id in environment variables like I did.
If your users have Google My Business (now called Google Business Profile), it makes sense to also integrate those APIs to your app. To do so, you will need:
- Get your project approved for GMB. This is a different approval process that you went through when getting a developer token for the Google Ads API.
- Fill out this form. Find more information about this here. Important: You will get it approved for a specific project, so if you requested access to the GMB API for one project, and then you want to use it on another project, you need to request access to that one too.
- Go to the project on GCP and enable these two APIs like you did with the Google Ads API:
- My Business Business Information API
- My Business Account Management API
- You are going to be able to use those APIs after you get approval from Google.
Those two API for Google My Business are needed to get the business location id that you can use when creating a Smart Campaign. Check the Campaign Creation section for more information on this.
Important: if you are not using Google My Business (aka Business Profile), you need to make the following changes to the code repositories that you are going to clone:
- In the backend, eliminate L41 and L75 from the authenticate.py. This will eliminate the scope during OAuth about Google My Business.
- In the frontend, eliminate the useEffect to get data from that API that is in L65 to L100 in CreateCampaign.js.
In parallel, you will need to verify your app. See here and here for helpful documentation. You can start this now or later on. It can take several weeks. The Cloud team will send you emails and you should try to answer quickly so they don’t block the process.
Create environment variables to store all the credentials. Create the following environment variables.
-
GOOGLE_CLIENT_ID to store the client_id of the Google Cloud project.
-
GOOGLE_CLIENT_SECRET to store the client_secret of the Google Cloud project.
-
GOOGLE_DEVELOPER_TOKEN to store your developer token.
-
GOOGLE_CLIENT_SECRET_PATH to store the pack to the client_secret.json file you downloaded in the previous step.
More info about each of these below.
The client secret and client ID are in your client_secret.json file you downloaded from your GCP panel after creating the OAuth credentials for your app. And the login customer id is the customer id of your manager account on google ads (you have to put it without hyphens).
To copy paste your developer token, sign in your Manager account on Google Ads, go to Tools & Settings > Settings > API center. There you will see your developer token.
For the refresh token (see steps here), you need to know that the authorization sequence begins when your application redirects a browser to a Google URL; the URL includes query parameters that indicate the type of access being requested.
Google handles the user authentication, session selection, and user consent. The result is an authorization code, which the application can exchange for an access token and a refresh token.
The application should store the refresh token for future use and use the access token to access a Google API. Once the access token expires, the application uses the refresh token to obtain a new one.
To learn more about the expiration of refresh tokens, go here.
To generate the refresh token, create a temporary authenticate_in_web_application.py file and make sure that the redirect URI is one that you have authorized in your GCP project.
Make sure that the URL you are using in your code to redirect users is included in the authorized redirect URIs section in the GCP project. See image below.
Also, make sure that you include the gmail account in the list of authorized test users in your GCP project. See image below.
Although deploying to production is out of the scope of this project, I wanted to provide guidance on important things to consider, and deployment alternatives.
This section has two sub-sections (backend and frontend) that explains what you need to do to deploy Fran Ads to production. These changes are needed for the app to work correctly.
This section doesn't cover load balancers, queue systems, nor scaling architectures. That's on you to define how and what to use.
In the Authentication & Authorization components, we set it up in a way that helps during development, but you have to change when pushing to production. Check that section of the guide.
There are three things to consider when thinking of deploying the backend to production.
- The first thing you should do is turn off the debug mode. You don't want it running when your app is in production. Go to the settings.py file, and change the
DEBUG = True
to
DEBUG = False
in line 40.
- Set up error email alerts so you know when an exception has been raised. This is important to fix those issues that can appear. Include all email addresses that you want by adding the ADMINS setting in the settings.py file. Below an example.
ADMINS = [ ('John', 'john@example.com'), ('Mary', 'mary@example.com') ]
- Enable your server to send emails so you get the error email alerts. Depending on your arragement complexity, you need to add to the settings.py file all of these below.
Here you will learn different ways to set up your settings files to keep your dev environment isolated from your prod environment.
First, you need to create a production build by running
npm run build
This will create a build directory with a production build of your app. Inside the build/static directory will be your JavaScript and CSS files. Each filename inside of build/static will contain a unique hash of the file contents. This hash in the file name enables long term caching techniques.
The frontend is completely platform-agnostic, so you can use any server software of your choice. See here how to serve the index.html for any unkown paths.
Finally, you can override where your app is hosted by adding the field homepage in your package.json file. See example below.
"homepage": "http://mywebsite.com/relativepath"
Check out the links provided below for each Cloud provider.
This is just to get you started so you can learn about making API calls to Google Ads API and Google My Business API.
By cloning this project and the frontend that is in a separate repo in my GitHub profile, you are ready to start exploring what you can do with Google Ads API.